zoujing/YGChatCS

Fork 0

Files

duanshuwen ea5841d594 feat: 商品详情页面交互

2025-08-02 17:35:57 +08:00

6.6 KiB

Raw Blame History

TopNavBar 组件使用指南

组件概述

TopNavBar 是一个功能完整的顶部导航栏组件，专为 uni-app 项目设计。该组件支持固定定位、自定义样式、插槽内容等功能，可以满足大部分页面的导航需求。

核心特性

1. 可配置固定定位

默认行为: 组件默认不固定，跟随页面滚动
固定模式: 设置 fixed="true" 可将导航栏固定在页面顶部
自动适配: 固定模式下自动处理状态栏高度和安全区域

2. 智能状态栏适配

自动获取系统状态栏高度
支持不同平台的导航栏高度适配（iOS: 44px, Android: 48px）
可选择隐藏状态栏占位区域

3. 灵活的自定义选项

支持自定义背景色、标题色、图标色
可控制返回按钮显示/隐藏
支持自定义 z-index 层级
支持标题对齐方式配置（居中/左对齐）

快速开始

基础使用

<!-- 最简单的使用方式 -->
<TopNavBar title="页面标题" />

固定在顶部

<!-- 固定导航栏，适合长页面滚动 -->
<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>

自定义样式

<!-- 深色主题导航栏 -->
<TopNavBar 
  title="深色导航栏" 
  backgroundColor="#1a1a1a"
  titleColor="#ffffff"
  backIconColor="#ffffff"
/>

<!-- 品牌色导航栏 -->
<TopNavBar 
  title="品牌导航栏" 
  backgroundColor="#007AFF"
  titleColor="#ffffff"
  backIconColor="#ffffff"
/>

<!-- 左对齐标题 -->
<TopNavBar 
  title="左对齐标题" 
  titleAlign="left"
/>

<!-- 居中标题（默认） -->
<TopNavBar 
  title="居中标题" 
  titleAlign="center"
/>

高级用法

使用插槽自定义内容

<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>

监听返回事件

<template>
  <TopNavBar 
    title="自定义返回" 
    @back="handleCustomBack"
  />
</template>

<script setup>
const handleCustomBack = () => {
  // 自定义返回逻辑
  uni.showModal({
    title: '提示',
    content: '确定要离开当前页面吗？',
    success: (res) => {
      if (res.confirm) {
        uni.navigateBack()
      }
    }
  })
}
</script>

实际应用场景

1. 商品详情页

<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. 订单列表页

<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. 聊天页面

<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. 固定导航栏的页面布局

// 推荐的页面结构
.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. 响应式设计

// 适配不同屏幕尺寸
@media screen and (max-width: 375px) {
  .page-content {
    padding-top: calc(var(--status-bar-height, 44px) + 40px);
  }
}

3. 主题适配

<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>

注意事项

固定定位的性能考虑: 固定导航栏会创建新的层叠上下文，在复杂页面中可能影响性能
状态栏适配: 在不同设备上状态栏高度可能不同，组件会自动处理，但建议在测试时验证各种设备
插槽内容: 使用插槽时注意内容的响应式设计，确保在不同屏幕尺寸下都能正常显示
z-index 管理: 如果页面中有其他固定定位元素，注意调整 z-index 避免层级冲突
返回按钮: 默认返回行为是 uni.navigateBack()，如需自定义请监听 @back 事件

故障排除

常见问题

Q: 固定导航栏下的内容被遮挡了？ A: 需要为页面内容添加顶部间距，参考上面的最佳实践。

Q: 在某些设备上状态栏高度不正确？ A: 组件会自动获取状态栏高度，如果仍有问题，可以手动设置 hideStatusBar="true" 并自行处理。

Q: 自定义颜色不生效？ A: 确保传入的颜色值格式正确，支持 hex、rgb、rgba 等标准 CSS 颜色格式。

Q: 插槽内容显示异常？ A: 检查插槽内容的样式，确保没有影响导航栏布局的 CSS 属性。

6.6 KiB Raw Blame History Unescape Escape