添加程序选择

2025-11-23 00:24:31 +08:00
parent 17015c0cca
commit 8b3f6c5a3a
18 changed files with 1296 additions and 47 deletions
--- a/src/components/GuideBar/README.md
+++ b/src/components/GuideBar/README.md
@@ -0,0 +1,169 @@
+# GuideBar 组件使用说明
+
+## 概述
+`GuideBar` 组件的显示/隐藏状态已经集中管理在 `global store` 中，方便各个组件调用。
+
+## 在组件中使用
+
+### 1. 基础用法：获取状态
+
+```tsx
+import { useGlobalState } from "@/store/global";
+
+function YourComponent() {
+  const { showGuideBar, guideBarZIndex } = useGlobalState();
+  
+  return (
+    <View>
+      {showGuideBar ? <Text>GuideBar 已显示</Text> : <Text>GuideBar 已隐藏</Text>}
+    </View>
+  );
+}
+```
+
+### 2. 控制 GuideBar 显示/隐藏
+
+```tsx
+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
+
+```tsx
+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. 完整示例：视频播放器
+
+```tsx
+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：
+
+```tsx
+const handleEnterFullscreen = () => {
+  setShowGuideBar(false);
+};
+```
+
+### 2. 弹窗/遮罩层
+当页面显示弹窗或遮罩层时，需要调整 GuideBar 的层级：
+
+```tsx
+const handleShowModal = () => {
+  setGuideBarZIndex('low'); // 让弹窗在 GuideBar 之上
+};
+```
+
+### 3. 沉浸式阅读
+在某些需要沉浸式体验的页面（如长文阅读、详情页滚动）：
+
+```tsx
+const handleScroll = (e) => {
+  if (e.detail.scrollTop > 200) {
+    setShowGuideBar(false); // 滚动到一定距离后隐藏
+  } else {
+    setShowGuideBar(true);
+  }
+};
+```
+
+## 注意事项
+
+1. **恢复状态**：在组件卸载时，记得恢复 GuideBar 的状态，避免影响其他页面
+2. **层级管理**：`guideBarZIndex` 通常由主页面自动管理，除非有特殊需求，否则不建议手动设置
+3. **性能优化**：频繁切换显示/隐藏可能影响性能，建议使用防抖或节流
+
--- a/src/components/GuideBar/usage-example.tsx
+++ b/src/components/GuideBar/usage-example.tsx
@@ -0,0 +1,203 @@
+/**
+ * GuideBar Store 使用示例
+ * 
+ * 这个文件展示了如何在不同场景下使用 GuideBar 的 store
+ */
+
+import { useGlobalState } from "@/store/global";
+import { useEffect } from "react";
+import { View, Button } from "@tarojs/components";
+
+// ============ 示例 1: 视频播放器组件 ============
+export function VideoPlayerExample() {
+  const { setShowGuideBar } = useGlobalState();
+  
+  // 进入全屏
+  const handleFullscreen = () => {
+    setShowGuideBar(false);
+  };
+  
+  // 退出全屏
+  const handleExitFullscreen = () => {
+    setShowGuideBar(true);
+  };
+  
+  // 组件卸载时恢复
+  useEffect(() => {
+    return () => {
+      setShowGuideBar(true);
+    };
+  }, [setShowGuideBar]);
+  
+  return (
+    <View>
+      <Button onClick={handleFullscreen}>进入全屏</Button>
+      <Button onClick={handleExitFullscreen}>退出全屏</Button>
+    </View>
+  );
+}
+
+// ============ 示例 2: 弹窗组件 ============
+export function ModalExample() {
+  const { setGuideBarZIndex } = useGlobalState();
+  
+  const handleShowModal = () => {
+    // 显示弹窗时，降低 GuideBar 层级
+    setGuideBarZIndex('low');
+  };
+  
+  const handleCloseModal = () => {
+    // 关闭弹窗时，恢复 GuideBar 层级
+    setGuideBarZIndex('high');
+  };
+  
+  return (
+    <View>
+      <Button onClick={handleShowModal}>打开弹窗</Button>
+    </View>
+  );
+}
+
+// ============ 示例 3: 沉浸式滚动页面 ============
+export function ImmersiveScrollExample() {
+  const { showGuideBar, setShowGuideBar } = useGlobalState();
+  
+  const handleScroll = (e: any) => {
+    const scrollTop = e.detail.scrollTop;
+    
+    // 向下滚动超过 200px 时隐藏 GuideBar
+    if (scrollTop > 200 && showGuideBar) {
+      setShowGuideBar(false);
+    }
+    // 向上滚动回到顶部时显示 GuideBar
+    else if (scrollTop <= 200 && !showGuideBar) {
+      setShowGuideBar(true);
+    }
+  };
+  
+  return (
+    <View onScroll={handleScroll}>
+      {/* 页面内容 */}
+    </View>
+  );
+}
+
+// ============ 示例 4: 图片预览器 ============
+export function ImagePreviewExample() {
+  const { setShowGuideBar } = useGlobalState();
+  
+  const handlePreviewImage = () => {
+    // 预览图片时隐藏 GuideBar
+    setShowGuideBar(false);
+  };
+  
+  const handleClosePreview = () => {
+    // 关闭预览时显示 GuideBar
+    setShowGuideBar(true);
+  };
+  
+  useEffect(() => {
+    return () => {
+      // 组件卸载时恢复 GuideBar
+      setShowGuideBar(true);
+    };
+  }, [setShowGuideBar]);
+  
+  return (
+    <View>
+      <Button onClick={handlePreviewImage}>预览图片</Button>
+    </View>
+  );
+}
+
+// ============ 示例 5: 切换开关 ============
+export function ToggleExample() {
+  const { showGuideBar, toggleGuideBar } = useGlobalState();
+  
+  return (
+    <View>
+      <Button onClick={toggleGuideBar}>
+        {showGuideBar ? '隐藏底部导航' : '显示底部导航'}
+      </Button>
+    </View>
+  );
+}
+
+// ============ 示例 6: 游戏/互动页面 ============
+export function GamePageExample() {
+  const { setShowGuideBar } = useGlobalState();
+  
+  // 游戏开始时隐藏 GuideBar
+  const handleStartGame = () => {
+    setShowGuideBar(false);
+  };
+  
+  // 游戏结束时显示 GuideBar
+  const handleGameOver = () => {
+    setShowGuideBar(true);
+  };
+  
+  // 页面显示时隐藏，离开时恢复
+  useEffect(() => {
+    setShowGuideBar(false);
+    
+    return () => {
+      setShowGuideBar(true);
+    };
+  }, [setShowGuideBar]);
+  
+  return (
+    <View>
+      <Button onClick={handleStartGame}>开始游戏</Button>
+      <Button onClick={handleGameOver}>结束游戏</Button>
+    </View>
+  );
+}
+
+// ============ 示例 7: 详情页（根据内容动态显示） ============
+export function DetailPageExample() {
+  const { setShowGuideBar } = useGlobalState();
+  
+  useEffect(() => {
+    // 进入详情页时根据内容长度决定是否显示 GuideBar
+    const contentHeight = 1500; // 假设内容高度
+    const screenHeight = 800; // 假设屏幕高度
+    
+    if (contentHeight > screenHeight * 2) {
+      // 内容很长时，初始隐藏 GuideBar，提供更好的阅读体验
+      setShowGuideBar(false);
+    }
+    
+    return () => {
+      setShowGuideBar(true);
+    };
+  }, [setShowGuideBar]);
+  
+  return (
+    <View>
+      {/* 详情内容 */}
+    </View>
+  );
+}
+
+// ============ 示例 8: 表单页面（避免键盘遮挡） ============
+export function FormPageExample() {
+  const { setShowGuideBar } = useGlobalState();
+  
+  // 输入框聚焦时隐藏 GuideBar（避免键盘遮挡）
+  const handleFocus = () => {
+    setShowGuideBar(false);
+  };
+  
+  // 输入框失焦时显示 GuideBar
+  const handleBlur = () => {
+    setShowGuideBar(true);
+  };
+  
+  return (
+    <View>
+      <input onFocus={handleFocus} onBlur={handleBlur} />
+    </View>
+  );
+}
+