From 238578b1f4f024785138eb70d9e4b9271bae66b2 Mon Sep 17 00:00:00 2001
From: WindowBird <13870814+windows-bird@user.noreply.gitee.com>
Date: Tue, 14 Oct 2025 11:00:34 +0800
Subject: [PATCH] =?UTF-8?q?=E8=87=AA=E5=AE=9A=E4=B9=89=E5=AF=BC=E8=88=AA?=
=?UTF-8?q?=E6=A0=8F=E6=96=87=E6=A1=A3=E6=9B=B4=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
components/custom-navbar/README.md | 376 ++++++++++++++++++-----------
1 file changed, 241 insertions(+), 135 deletions(-)
diff --git a/components/custom-navbar/README.md b/components/custom-navbar/README.md
index 9704f4c..a55c222 100644
--- a/components/custom-navbar/README.md
+++ b/components/custom-navbar/README.md
@@ -1,171 +1,277 @@
-# Custom Navbar 组件使用说明
+# 自定义变色导航栏组件
+
+## 概述
+
+这是一个支持滚动时动态变色的自定义导航栏组件，通过配合 `page-scroll-mixin.js` 实现页面滚动监听和导航栏样式自动切换。
## 功能特性
-- 自动监听页面滚动
-- 滚动时导航栏变为纯色背景
-- 回到顶部时导航栏变为透明
-- 支持自定义背景色和滚动阈值
-- 提供滚动状态事件回调
+- ✅ **自适应系统状态栏**：自动适配不同设备的状态栏高度
+- ✅ **滚动变色效果**：页面滚动时导航栏背景色和阴影自动切换
+- ✅ **平滑过渡动画**：CSS 过渡效果让颜色变化更自然
+- ✅ **可配置参数**：支持自定义滚动阈值、背景色等
+- ✅ **事件系统**：提供丰富的滚动事件供父组件监听
+- ✅ **插槽支持**：右侧支持自定义内容
+- ✅ **全局混入**：通过 Mixin 实现滚动逻辑自动处理
-## 基本用法
+## 文件结构
-```vue
-
-
-
-
-
-
+```
+components/custom-navbar/
+├── custom-navbar.vue # 导航栏组件
+├── README.md # 文档说明
+mixins/
+├── page-scroll-mixin.js # 滚动监听混入
+main.js # 全局混入注册
```
-## 高级用法
+## 核心组件
+
+### 1. custom-navbar.vue
+
+#### Props 配置
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | String | "" | 导航栏标题 |
+| backIcon | String | CommonEnum.BACK_BUTTON | 返回按钮图标 |
+| showBack | Boolean | true | 是否显示返回按钮 |
+| backgroundColor | String | CommonEnum.BASE_COLOR | 滚动时的背景色 |
+| scrollThreshold | Number | 20 | 滚动阈值（px） |
+| enableScrollEffect | Boolean | true | 是否启用滚动效果 |
+
+#### 事件
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| back | - | 点击返回按钮时触发 |
+| scroll-change | { isScrolled, scrollTop } | 滚动状态变化时触发 |
+| scroll | { scrollTop, isScrolled } | 滚动时触发 |
+
+#### 方法
+
+| 方法名 | 参数 | 说明 |
+|--------|------|------|
+| handlePageScroll | e | 处理页面滚动事件（供 Mixin 调用） |
+| setScrollState | scrollTop | 手动设置滚动状态 |
+
+### 2. page-scroll-mixin.js
+
+#### 功能
+- 自动监听页面滚动事件
+- 将滚动事件传递给配置的组件
+- 支持多个组件同时监听
+
+#### 配置选项
+- `scrollRefs`: 需要传递滚动事件的组件 ref 数组，默认为 `['customNavbar']`
+
+## 使用方法
+
+### 1. 基础用法
```vue
-
-
-
- 更多
-
-
-
+
+
```
-## Props 参数
+### 2. 自定义配置
-| 参数 | 类型 | 默认值 | 说明 |
-| ------------------ | ------- | ---------------------- | ---------------- |
-| title | String | '' | 导航栏标题 |
-| backIcon | String | CommonEnum.BACK_BUTTON | 返回按钮图标 |
-| showBack | Boolean | true | 是否显示返回按钮 |
-| backgroundColor | String | '#ffffff' | 滚动时的背景色 |
-| scrollThreshold | Number | 50 | 滚动阈值（像素） |
-| enableScrollEffect | Boolean | true | 是否启用滚动效果 |
+```vue
+
+
+
+
+
-## Events 事件
+
+```
-| 事件名 | 参数 | 说明 |
-| ------------- | ------------------------- | ------------------ |
-| back | - | 点击返回按钮时触发 |
-| scroll-change | { isScrolled, scrollTop } | 滚动状态变化时触发 |
-| scroll | { scrollTop, isScrolled } | 页面滚动时触发 |
+### 3. 多个组件监听
-## 方法
+```vue
+
+
+
+
+
+
-| 方法名 | 参数 | 说明 |
-| -------------- | --------- | ---------------- |
-| setScrollState | scrollTop | 手动设置滚动状态 |
+
+```
-## 样式定制
+### 4. 自定义右侧内容
-组件会自动添加以下 CSS 类：
+```vue
+
+
+
+
+ 自定义
+
+
+
+
+```
-- `.navbar-scrolled`: 滚动状态下的样式
-- 过渡动画：背景色变化有 0.3s 的过渡效果
-- 阴影效果：滚动时自动添加阴影
+## 全局配置
+
+### main.js 中的配置
+
+```javascript
+// 引入滚动混入
+import PageScrollMixin from "./mixins/page-scroll-mixin.js";
+
+// 注册全局混入
+Vue.mixin(PageScrollMixin);
+```
+
+通过全局混入，所有页面都会自动支持滚动监听功能。
+
+## 样式说明
+
+### 核心样式类
+
+```scss
+.custom-navbar {
+ position: fixed;
+ top: 0;
+ left: 0;
+ right: 0;
+ z-index: 999;
+ background-color: transparent;
+ transition: background-color 0.3s ease; /* 平滑过渡 */
+}
+
+.navbar-scrolled {
+ box-shadow: 0 2rpx 10rpx rgba(0, 0, 0, 0.1); /* 滚动时阴影 */
+}
+```
+
+### 自适应布局
+
+- **状态栏适配**：`paddingTop: statusBarHeight`
+- **胶囊按钮适配**：自动计算导航栏高度
+- **填充区**：避免内容被导航栏遮挡
+
+## 工作原理
+
+### 1. 滚动监听流程
+
+```mermaid
+graph TD
+ A[页面滚动] --> B[onPageScroll 触发]
+ B --> C[Mixin 分发事件]
+ C --> D[customNavbar.handlePageScroll]
+ D --> E[判断滚动阈值]
+ E --> F{超过阈值?}
+ F -->|是| G[设置 isScrolled = true]
+ F -->|否| H[设置 isScrolled = false]
+ G --> I[更新样式和阴影]
+ H --> I
+ I --> J[触发 scroll-change 事件]
+```
+
+### 2. 样式切换机制
+
+```javascript
+// 动态样式绑定
+:style="{
+ backgroundColor: isScrolled ? backgroundColor : 'transparent',
+}"
+
+// 动态类名绑定
+:class="{ 'navbar-scrolled': isScrolled }"
+```
+
+## 实际应用示例
+
+### activity.vue 页面使用
+
+```vue
+
+
+
+
+
+
+
+
+```
+
+## 最佳实践
+
+### 1. 性能优化
+- 使用 `enableScrollEffect` 控制是否启用滚动效果
+- 合理设置 `scrollThreshold` 避免频繁切换
+
+### 2. 样式定制
+- 通过 `backgroundColor` 属性自定义滚动时的背景色
+- 使用 CSS 变量实现主题切换
+
+### 3. 事件处理
+- 监听 `scroll-change` 事件处理滚动状态变化
+- 使用 `scroll` 事件获取实时滚动信息
## 注意事项
-1. **重要**：需要在父页面的 `onPageScroll` 生命周期中调用组件的 `handlePageScroll` 方法
-2. 滚动效果默认启用，可通过 `enableScrollEffect` 关闭
-3. 背景色变化有平滑过渡动画
-4. 组件使用 `ref` 引用，确保在页面中正确引用
+1. **必须设置 ref**：组件必须有 `ref="customNavbar"` 属性
+2. **全局混入**：确保在 `main.js` 中注册了 `PageScrollMixin`
+3. **系统适配**：组件会自动适配不同设备的状态栏高度
+4. **性能考虑**：滚动监听可能影响性能，建议在不需要时禁用
-## 完整使用示例
+## 故障排除
-### 方法一：使用 Mixin（推荐）
+### 常见问题
-```vue
-
-
-
-
-
-
+1. **滚动效果不生效**
+ - 检查是否正确设置了 `ref="customNavbar"`
+ - 确认 `enableScrollEffect` 为 `true`
-
-```
+3. **事件不触发**
+ - 确认全局混入已正确注册
+ - 检查组件是否正确引入
-### 方法二：手动处理
+## 更新日志
-```vue
-
-
-
-
-
-
-
-
-```
+- **v1.0.0**: 初始版本，支持基础滚动变色功能
+- **v1.1.0**: 添加全局混入支持，简化使用方式
+- **v1.2.0**: 优化性能，添加可配置选项
\ No newline at end of file