mini-programs/src/components/GuideBar

GuideBar 组件使用说明

概述

GuideBar 组件的显示/隐藏状态已经集中管理在 global store 中，方便各个组件调用。

在组件中使用

1. 基础用法：获取状态

import { useGlobalState } from "@/store/global";

function YourComponent() {
  const { showGuideBar, guideBarZIndex } = useGlobalState();
  
  return (
    <View>
      {showGuideBar ? <Text>GuideBar 已显示</Text> : <Text>GuideBar 已隐藏</Text>}
    </View>
  );
}

2. 控制 GuideBar 显示/隐藏

import { useGlobalState } from "@/store/global";

function YourComponent() {
  const { setShowGuideBar, toggleGuideBar } = useGlobalState();
  
  const handleHideGuideBar = () => {
    setShowGuideBar(false); // 隐藏 GuideBar
  };
  
  const handleShowGuideBar = () => {
    setShowGuideBar(true); // 显示 GuideBar
  };
  
  const handleToggle = () => {
    toggleGuideBar(); // 切换显示/隐藏状态
  };
  
  return (
    <View>
      <Button onClick={handleHideGuideBar}>隐藏底部导航</Button>
      <Button onClick={handleShowGuideBar}>显示底部导航</Button>
      <Button onClick={handleToggle}>切换底部导航</Button>
    </View>
  );
}

3. 控制 GuideBar z-index

import { useGlobalState } from "@/store/global";

function YourComponent() {
  const { setGuideBarZIndex } = useGlobalState();
  
  const handleOpenModal = () => {
    // 打开弹窗时，降低 GuideBar 层级
    setGuideBarZIndex('low');
  };
  
  const handleCloseModal = () => {
    // 关闭弹窗时，恢复 GuideBar 层级
    setGuideBarZIndex('high');
  };
  
  return (
    <View>
      <Button onClick={handleOpenModal}>打开弹窗</Button>
    </View>
  );
}

4. 完整示例：视频播放器

import { useGlobalState } from "@/store/global";
import { useEffect } from "react";

function VideoPlayer() {
  const { setShowGuideBar } = useGlobalState();
  
  // 进入全屏时隐藏 GuideBar
  const handleFullscreen = () => {
    setShowGuideBar(false);
  };
  
  // 退出全屏时显示 GuideBar
  const handleExitFullscreen = () => {
    setShowGuideBar(true);
  };
  
  // 组件卸载时恢复 GuideBar
  useEffect(() => {
    return () => {
      setShowGuideBar(true);
    };
  }, [setShowGuideBar]);
  
  return (
    <View>
      <Video onFullscreenChange={handleFullscreen} />
    </View>
  );
}

API 说明

状态

属性	类型	说明
showGuideBar	boolean	GuideBar 是否显示
guideBarZIndex	'low' | 'high'	GuideBar 的层级，用于处理与弹窗的层级关系

方法

方法	参数	说明
setShowGuideBar	(show: boolean) => void	设置 GuideBar 显示/隐藏
setGuideBarZIndex	(zIndex: 'low' | 'high') => void	设置 GuideBar z-index 层级
toggleGuideBar	() => void	切换 GuideBar 显示/隐藏状态

使用场景

1. 全屏播放/浏览

当用户进入全屏模式（如视频播放、图片预览）时，应该隐藏 GuideBar：

const handleEnterFullscreen = () => {
  setShowGuideBar(false);
};

2. 弹窗/遮罩层

当页面显示弹窗或遮罩层时，需要调整 GuideBar 的层级：

const handleShowModal = () => {
  setGuideBarZIndex('low'); // 让弹窗在 GuideBar 之上
};

3. 沉浸式阅读

在某些需要沉浸式体验的页面（如长文阅读、详情页滚动）：

const handleScroll = (e) => {
  if (e.detail.scrollTop > 200) {
    setShowGuideBar(false); // 滚动到一定距离后隐藏
  } else {
    setShowGuideBar(true);
  }
};

注意事项

1. 恢复状态：在组件卸载时，记得恢复 GuideBar 的状态，避免影响其他页面
2. 层级管理：guideBarZIndex 通常由主页面自动管理，除非有特殊需求，否则不建议手动设置
3. 性能优化：频繁切换显示/隐藏可能影响性能，建议使用防抖或节流