mini-programs/_doc/DEBUG_GUIDEBAR.md

GuideBar 隐藏问题调试指南

当前实现

1. Store 配置 (src/store/global.ts)

// GuideBar 状态
showGuideBar: true,
guideBarZIndex: 'high',

// 控制方法
setShowGuideBar: (show: boolean) => {
  console.log('[Store] setShowGuideBar called with:', show);
  set({ showGuideBar: show });
  console.log('[Store] showGuideBar updated to:', show);
},

2. HomeNavbar 使用 (src/components/HomeNavbar/index.tsx)

const { getLocationLoading, statusNavbarHeightInfo, setShowGuideBar } = useGlobalState();

const showLocationConfirmDialog = (detectedProvince: string, cachedCity: [string, string]) => {
  console.log('[LocationDialog] 准备显示定位确认弹窗，隐藏 GuideBar');
  setLocationDialogData({ detectedProvince, cachedCity });
  setLocationDialogVisible(true);
  setShowGuideBar(false); // 隐藏 GuideBar
  console.log('[LocationDialog] setShowGuideBar(false) 已调用');
};

3. MainPage 渲染 (src/main_pages/index.tsx)

const { showGuideBar, guideBarZIndex, setShowGuideBar, setGuideBarZIndex } = useGlobalState();

// 渲染逻辑
{
  showGuideBar ?
    <GuideBar
      currentPage={currentTab}
      guideBarClassName={guideBarZIndex === 'low' ? 'guide-bar-low-z-index' : 'guide-bar-high-z-index'}
      onTabChange={handleTabChange}
      onPublishMenuVisibleChange={handlePublishMenuVisibleChange}
    /> :
    null
}

调试步骤

步骤 1: 检查控制台日志

当 LocationConfirmDialog 弹窗显示时，应该能看到以下日志：

[LocationDialog] 准备显示定位确认弹窗，隐藏 GuideBar
[Store] setShowGuideBar called with: false
[Store] showGuideBar updated to: false
[LocationDialog] setShowGuideBar(false) 已调用

步骤 2: 检查是否有其他组件覆盖状态

搜索以下可能的干扰：

• UserInfo 组件通过 FamilyContext 调用 handleGrandchildTrigger
• 其他组件可能直接调用 setShowGuideBar(true)

步骤 3: 使用 React DevTools 检查状态

1. 打开 React DevTools
2. 找到 MainPage 组件
3. 查看 showGuideBar 的实时值
4. 当弹窗显示时，检查值是否变为 false

步骤 4: 检查 CSS 样式

如果状态正确但 GuideBar 仍然可见，可能是 CSS 问题：

// 检查 GuideBar 的样式是否有 !important 覆盖
.guide-bar-container {
  display: block; // 不应该有 !important
}

可能的问题原因

原因 1: UserInfo 组件干扰

src/components/UserInfo/index.tsx 使用 FamilyContext 控制 GuideBar：

const { handleGrandchildTrigger } = useContext(FamilyContext);

// 可能在某些情况下调用
handleGrandchildTrigger(false); // 这会设置 setShowGuideBar(true)

解决方案：检查 UserInfo 组件是否在 LocationConfirmDialog 显示时被触发。

原因 2: useEffect 依赖问题

HomeNavbar 中的 useEffect 可能在状态更新后重新运行：

useEffect(() => {
  // 检查这里的逻辑
}, [locationProvince]);

解决方案：确保 useEffect 不会在弹窗显示后重置状态。

原因 3: 异步状态更新

Zustand 的状态更新应该是同步的，但如果有异步操作可能延迟：

setShowGuideBar(false);
// 如果这里有异步操作，可能导致状态被覆盖
await someAsyncOperation();

解决方案：确保 setShowGuideBar(false) 之后没有异步操作重置状态。

测试方法

方法 1: 手动测试

1. 清除缓存：Taro.clearStorageSync()
2. 重新打开小程序
3. 等待定位完成
4. 观察是否弹出 LocationConfirmDialog
5. 检查 GuideBar 是否隐藏

方法 2: 代码测试

在 HomeNavbar 中添加测试按钮：

<Button onClick={() => {
  console.log('[Test] 手动触发弹窗');
  showLocationConfirmDialog('北京', ['中国', '上海']);
}}>
  测试弹窗
</Button>

方法 3: 添加更多日志

在 MainPage 中监听 showGuideBar 变化：

useEffect(() => {
  console.log('[MainPage] showGuideBar 状态变化:', showGuideBar);
}, [showGuideBar]);

验证清单

• 控制台显示正确的日志
• React DevTools 显示 showGuideBar 为 false
• GuideBar 组件不在 DOM 中渲染（使用元素审查工具检查）
• 没有其他组件调用 setShowGuideBar(true)
• CSS 样式没有强制显示 GuideBar

紧急修复方案

如果以上都无法解决，可以尝试以下紧急方案：

方案 1: 直接在 LocationConfirmDialog 中控制

// src/components/LocationConfirmDialog/index.tsx
import { useGlobalState } from "@/store/global";

const LocationConfirmDialog = (props) => {
  const { setShowGuideBar } = useGlobalState();
  
  useEffect(() => {
    if (visible) {
      setShowGuideBar(false);
    }
    return () => {
      setShowGuideBar(true);
    };
  }, [visible, setShowGuideBar]);
  
  // ...
};

方案 2: 使用 CSS 强制隐藏

// 当弹窗显示时，添加 class 隐藏 GuideBar
.location-dialog-visible {
  .guide-bar-container {
    display: none !important;
  }
}

方案 3: 添加延迟

const showLocationConfirmDialog = (detectedProvince: string, cachedCity: [string, string]) => {
  setLocationDialogData({ detectedProvince, cachedCity });
  setLocationDialogVisible(true);
  
  // 添加微小延迟确保状态更新
  setTimeout(() => {
    setShowGuideBar(false);
  }, 0);
};

联系支持

如果问题仍然存在，请提供：

1. 完整的控制台日志
2. React DevTools 截图
3. 复现步骤
4. 小程序版本和环境信息