feat: 商品详情页面交互

components/TopNavBar/使用指南.md

@@ -0,0 +1,312 @@
+# TopNavBar 组件使用指南
+
+## 组件概述
+
+TopNavBar 是一个功能完整的顶部导航栏组件，专为 uni-app 项目设计。该组件支持固定定位、自定义样式、插槽内容等功能，可以满足大部分页面的导航需求。
+
+## 核心特性
+
+### 1. 可配置固定定位
+- **默认行为**: 组件默认不固定，跟随页面滚动
+- **固定模式**: 设置 `fixed="true"` 可将导航栏固定在页面顶部
+- **自动适配**: 固定模式下自动处理状态栏高度和安全区域
+
+### 2. 智能状态栏适配
+- 自动获取系统状态栏高度
+- 支持不同平台的导航栏高度适配（iOS: 44px, Android: 48px）
+- 可选择隐藏状态栏占位区域
+
+### 3. 灵活的自定义选项
+- 支持自定义背景色、标题色、图标色
+- 可控制返回按钮显示/隐藏
+- 支持自定义 z-index 层级
+- 支持标题对齐方式配置（居中/左对齐）
+
+## 快速开始
+
+### 基础使用
+
+```vue
+<!-- 最简单的使用方式 -->
+<TopNavBar title="页面标题" />
+```
+
+### 固定在顶部
+
+```vue
+<!-- 固定导航栏，适合长页面滚动 -->
+<template>
+  <view class="page-container">
+    <TopNavBar title="商品详情" :fixed="true" />
+    <view class="page-content">
+      <!-- 页面内容 -->
+    </view>
+  </view>
+</template>
+
+<style>
+.page-content {
+  /* 为固定导航栏预留空间 */
+  padding-top: calc(var(--status-bar-height, 44px) + 44px);
+}
+</style>
+```
+
+### 自定义样式
+
+```vue
+<!-- 深色主题导航栏 -->
+<TopNavBar 
+  title="深色导航栏" 
+  backgroundColor="#1a1a1a"
+  titleColor="#ffffff"
+  backIconColor="#ffffff"
+/>
+
+<!-- 品牌色导航栏 -->
+<TopNavBar 
+  title="品牌导航栏" 
+  backgroundColor="#007AFF"
+  titleColor="#ffffff"
+  backIconColor="#ffffff"
+/>
+
+<!-- 左对齐标题 -->
+<TopNavBar 
+  title="左对齐标题" 
+  titleAlign="left"
+/>
+
+<!-- 居中标题（默认） -->
+<TopNavBar 
+  title="居中标题" 
+  titleAlign="center"
+/>
+```
+
+## 高级用法
+
+### 使用插槽自定义内容
+
+```vue
+<template>
+  <TopNavBar>
+    <!-- 自定义标题区域 -->
+    <template #title>
+      <view class="custom-title">
+        <image src="/static/logo.png" class="logo" />
+        <text class="brand-name">品牌名称</text>
+      </view>
+    </template>
+    
+    <!-- 自定义右侧操作 -->
+    <template #right>
+      <view class="nav-actions">
+        <uni-icons type="search" size="20" @click="handleSearch" />
+        <uni-icons type="more" size="20" @click="showMore" />
+      </view>
+    </template>
+  </TopNavBar>
+</template>
+
+<style>
+.custom-title {
+  display: flex;
+  align-items: center;
+  
+  .logo {
+    width: 24px;
+    height: 24px;
+    margin-right: 8px;
+  }
+  
+  .brand-name {
+    font-size: 18px;
+    font-weight: 600;
+  }
+}
+
+.nav-actions {
+  display: flex;
+  align-items: center;
+  gap: 15px;
+}
+</style>
+```
+
+### 监听返回事件
+
+```vue
+<template>
+  <TopNavBar 
+    title="自定义返回" 
+    @back="handleCustomBack"
+  />
+</template>
+
+<script setup>
+const handleCustomBack = () => {
+  // 自定义返回逻辑
+  uni.showModal({
+    title: '提示',
+    content: '确定要离开当前页面吗？',
+    success: (res) => {
+      if (res.confirm) {
+        uni.navigateBack()
+      }
+    }
+  })
+}
+</script>
+```
+
+## 实际应用场景
+
+### 1. 商品详情页
+
+```vue
+<template>
+  <view class="goods-detail">
+    <TopNavBar 
+      title="商品详情" 
+      :fixed="true"
+      backgroundColor="rgba(255, 255, 255, 0.95)"
+    >
+      <template #right>
+        <uni-icons type="share" size="20" @click="shareGoods" />
+      </template>
+    </TopNavBar>
+    
+    <view class="goods-content">
+      <!-- 商品内容 -->
+    </view>
+  </view>
+</template>
+```
+
+### 2. 订单列表页
+
+```vue
+<template>
+  <view class="order-list">
+    <TopNavBar>
+      <template #title>
+        <Tabs 
+          :tabs="orderTabs" 
+          :active="activeTab" 
+          @change="switchTab"
+        />
+      </template>
+    </TopNavBar>
+    
+    <view class="order-content">
+      <!-- 订单列表 -->
+    </view>
+  </view>
+</template>
+```
+
+### 3. 聊天页面
+
+```vue
+<template>
+  <view class="chat-page">
+    <TopNavBar 
+      title="客服小沐" 
+      :fixed="true"
+      backgroundColor="#f8f9fa"
+    >
+      <template #right>
+        <uni-icons type="phone" size="20" @click="makeCall" />
+      </template>
+    </TopNavBar>
+    
+    <view class="chat-content">
+      <!-- 聊天内容 -->
+    </view>
+  </view>
+</template>
+```
+
+## 最佳实践
+
+### 1. 固定导航栏的页面布局
+
+```scss
+// 推荐的页面结构
+.page-container {
+  .page-content {
+    // 方法1: 使用 padding-top
+    padding-top: calc(var(--status-bar-height, 44px) + 44px);
+    
+    // 方法2: 使用 margin-top
+    // margin-top: calc(var(--status-bar-height, 44px) + 44px);
+  }
+}
+```
+
+### 2. 响应式设计
+
+```scss
+// 适配不同屏幕尺寸
+@media screen and (max-width: 375px) {
+  .page-content {
+    padding-top: calc(var(--status-bar-height, 44px) + 40px);
+  }
+}
+```
+
+### 3. 主题适配
+
+```vue
+<script setup>
+import { computed } from 'vue'
+
+// 根据系统主题动态调整颜色
+const navBarStyle = computed(() => {
+  const isDark = uni.getSystemInfoSync().theme === 'dark'
+  return {
+    backgroundColor: isDark ? '#1a1a1a' : '#ffffff',
+    titleColor: isDark ? '#ffffff' : '#333333',
+    backIconColor: isDark ? '#ffffff' : '#333333'
+  }
+})
+</script>
+
+<template>
+  <TopNavBar 
+    title="自适应主题" 
+    :backgroundColor="navBarStyle.backgroundColor"
+    :titleColor="navBarStyle.titleColor"
+    :backIconColor="navBarStyle.backIconColor"
+  />
+</template>
+```
+
+## 注意事项
+
+1. **固定定位的性能考虑**: 固定导航栏会创建新的层叠上下文，在复杂页面中可能影响性能
+
+2. **状态栏适配**: 在不同设备上状态栏高度可能不同，组件会自动处理，但建议在测试时验证各种设备
+
+3. **插槽内容**: 使用插槽时注意内容的响应式设计，确保在不同屏幕尺寸下都能正常显示
+
+4. **z-index 管理**: 如果页面中有其他固定定位元素，注意调整 z-index 避免层级冲突
+
+5. **返回按钮**: 默认返回行为是 `uni.navigateBack()`，如需自定义请监听 `@back` 事件
+
+## 故障排除
+
+### 常见问题
+
+**Q: 固定导航栏下的内容被遮挡了？**
+A: 需要为页面内容添加顶部间距，参考上面的最佳实践。
+
+**Q: 在某些设备上状态栏高度不正确？**
+A: 组件会自动获取状态栏高度，如果仍有问题，可以手动设置 `hideStatusBar="true"` 并自行处理。
+
+**Q: 自定义颜色不生效？**
+A: 确保传入的颜色值格式正确，支持 hex、rgb、rgba 等标准 CSS 颜色格式。
+
+**Q: 插槽内容显示异常？**
+A: 检查插槽内容的样式，确保没有影响导航栏布局的 CSS 属性。