zx-navbar 组件优化说明

🎉 优化内容

1. 功能增强

• ✅ 新增副标题支持 (subtitle)
• ✅ 新增透明背景模式 (transparent)
• ✅ 新增沉浸式模式 (immersive)
• ✅ 新增阴影效果 (shadow)
• ✅ 新增加载状态显示 (loading)
• ✅ 新增主题模式支持 (theme: light/dark/auto)
• ✅ 新增禁用状态 (leftDisabled, rightDisabled)
• ✅ 新增右侧图标大小和颜色控制
• ✅ 新增层级控制 (zIndex)
• ✅ 新增按钮交互时间控制 (hoverTime)

2. 样式改进

• ✅ 移除硬编码的背景色 #9acafc
• ✅ 改进布局逻辑，支持更灵活的中央区域定位
• ✅ 新增过渡动画效果
• ✅ 新增响应式设计支持
• ✅ 新增暗色模式适配
• ✅ 改进图标和文字的间距

3. 用户体验优化

• ✅ 增加无障碍支持 (aria-label, role)
• ✅ 改进错误处理和容错机制
• ✅ 优化点击反馈效果
• ✅ 新增加载状态动画

4. 代码质量提升

• ✅ 使用 Composition API 重构
• ✅ 改进 TypeScript 支持
• ✅ 优化性能，减少不必要的计算
• ✅ 改进事件处理机制
• ✅ 增强属性验证

📖 使用指南

基础用法

<template>
  <zx-navbar 
    title="页面标题"
    left-text="返回"
    right-text="更多"
    @left-click="onBack"
    @right-click="onMore"
  />
</template>

高级功能

1. 副标题支持

<zx-navbar 
  title="主标题"
  subtitle="副标题说明"
/>

2. 透明背景

<zx-navbar 
  title="透明导航栏"
  :transparent="true"
  left-icon="arrow-left"
/>

3. 沉浸式模式

<zx-navbar 
  title="沉浸式导航栏"
  :immersive="true"
  :shadow="true"
/>

4. 主题模式

<!-- 暗色主题 -->
<zx-navbar 
  title="暗色主题"
  theme="dark"
  bg-color="#1f1f1f"
/>

<!-- 自动主题（跟随系统） -->
<zx-navbar 
  title="自动主题"
  theme="auto"
/>

5. 加载状态

<zx-navbar 
  title="正在加载..."
  :loading="true"
  :left-disabled="true"
/>

6. 自定义插槽

<zx-navbar>
  <template #left>
    <view class="custom-left">
      <zx-icon name="home" />
      <text>首页</text>
    </view>
  </template>
  
  <template #center>
    <view class="custom-center">
      <image src="/logo.png" />
      <text>品牌名称</text>
    </view>
  </template>
  
  <template #right>
    <view class="custom-right">
      <zx-icon name="search" />
      <zx-icon name="cart" />
    </view>
  </template>
</zx-navbar>

🔧 API 文档

Props

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | title | String/Number | '' | 导航栏标题 | | subtitle | String | '' | 导航栏副标题 | | bgColor | String | '#ffffff' | 背景颜色 | | theme | String | 'light' | 主题模式：light/dark/auto | | transparent | Boolean | false | 是否透明背景 | | immersive | Boolean | false | 是否沉浸式模式 | | shadow | Boolean | false | 是否显示阴影 | | loading | Boolean | false | 是否显示加载状态 | | fixed | Boolean | false | 是否固定在顶部 | | placeholder | Boolean | true | 固定时是否生成占位元素 | | safeAreaInsetTop | Boolean | true | 是否开启顶部安全区适配 | | border | Boolean | false | 是否显示底部边框 | | borderColor | String | '#ececec' | 边框颜色 | | height | String/Number | '44px' | 导航栏高度 | | zIndex | Number | 980 | 层级 | | autoBack | Boolean | true | 是否自动返回 | | leftIcon | String | 'arrow-left' | 左侧图标 | | leftText | String | '' | 左侧文字 | | leftIconSize | String/Number | '36rpx' | 左侧图标大小 | | leftIconColor | String | '#303133' | 左侧图标颜色 | | leftDisabled | Boolean | false | 是否禁用左侧 | | rightIcon | String | '' | 右侧图标 | | rightText | String | '' | 右侧文字 | | rightIconSize | String/Number | '36rpx' | 右侧图标大小 | | rightIconColor | String | '#303133' | 右侧图标颜色 | | rightDisabled | Boolean | false | 是否禁用右侧 | | titleWidth | String/Number | '400rpx' | 标题最大宽度 | | titleStyle | Object/String | null | 标题样式 | | subtitleStyle | Object/String | null | 副标题样式 | | hoverTime | Number | 150 | 按钮按下时间 |

Events

| 事件名 | 说明 | 参数 | |--------|------|------| | left-click | 点击左侧区域 | - | | right-click | 点击右侧区域 | - |

Slots

| 插槽名 | 说明 | |--------|------| | left | 左侧内容 | | center | 中央内容 | | right | 右侧内容 |

🎨 样式定制

CSS 变量

.zx-navbar {
  --navbar-height: 44px;
  --navbar-bg-color: #ffffff;
  --navbar-text-color: #303133;
  --navbar-icon-size: 36rpx;
  --navbar-padding: 32rpx;
}

主题定制

<template>
  <zx-navbar 
    :title-style="customTitleStyle"
    :subtitle-style="customSubtitleStyle"
  />
</template>

<script setup>
const customTitleStyle = {
  fontSize: '40rpx',
  fontWeight: 'bold',
  color: '#333333'
};

const customSubtitleStyle = {
  fontSize: '24rpx',
  color: '#999999'
};
</script>

🔍 最佳实践

1. 响应式使用

<zx-navbar 
  :title="title"
  :loading="isLoading"
  :left-disabled="isLoading"
  @left-click="handleBack"
/>

2. 主题适配

<zx-navbar 
  theme="auto"
  :bg-color="isDark ? '#1f1f1f' : '#ffffff'"
  :left-icon-color="isDark ? '#ffffff' : '#333333'"
/>

3. 错误处理

<script setup>
const handleBack = () => {
  try {
    if (canGoBack) {
      uni.navigateBack();
    } else {
      uni.reLaunch({ url: '/pages/index/index' });
    }
  } catch (error) {
    console.error('导航失败:', error);
  }
};
</script>

🚀 迁移指南

从旧版本迁移

1. 事件名称变更

   <!-- 旧版本 -->
   @click-left="onBack"
   @click-right="onMore"
      
   <!-- 新版本 -->
   @left-click="onBack"
   @right-click="onMore"

2. 默认值变更

   • placeholder 默认值从 false 改为 true
   • autoBack 默认值从 false 改为 true

3. 样式更新

   • 移除了硬编码的蓝色背景
   • 改进了图标和文字的间距

🐛 注意事项

1. 使用 immersive 模式时，需要确保系统支持 backdrop-filter
2. auto 主题模式需要浏览器支持 prefers-color-scheme
3. 固定导航栏时建议开启 placeholder 避免内容被遮挡
4. 自定义插槽时需要注意样式兼容性

📝 更新日志

v2.0.0 (最新)

• 🎉 全面重构，使用 Composition API
• ✨ 新增副标题、透明背景、沉浸式等功能
• 🎨 改进样式系统，支持主题切换
• 🔧 优化性能和用户体验
• 📱 增强响应式和无障碍支持

v1.0.0 (原版本)

• 基础导航栏功能
• 支持标题、左右按钮
• 固定定位和安全区适配