buddhism/components/custom-navbar/README.md

# Custom Navbar 组件使用说明

## 功能特性

- 自动监听页面滚动
- 滚动时导航栏变为纯色背景
- 回到顶部时导航栏变为透明
- 支持自定义背景色和滚动阈值
- 提供滚动状态事件回调

## 基本用法

```vue
<template>
  <view>
    <custom-navbar title="页面标题" />
    <!-- 页面内容 -->
  </view>
</template>
```

## 高级用法

```vue
<template>
  <view>
    <custom-navbar
      title="古刹巡礼"
      :backgroundColor="'#FAF8F3'"
      :scrollThreshold="100"
      :enableScrollEffect="true"
      @scroll-change="onScrollChange"
      @scroll="onScroll"
    >
      <template #right>
        <view class="right-button">更多</view>
      </template>
    </custom-navbar>

    <!-- 页面内容 -->
  </view>
</template>

<script>
  export default {
    methods: {
      onScrollChange(data) {
        console.log('滚动状态变化:', data.isScrolled)
      },
      onScroll(data) {
        console.log('滚动位置:', data.scrollTop)
      },
    },
  }
</script>
```

## Props 参数

| 参数               | 类型    | 默认值                 | 说明             |
| ------------------ | ------- | ---------------------- | ---------------- |
| title              | String  | ''                     | 导航栏标题       |
| backIcon           | String  | CommonEnum.BACK_BUTTON | 返回按钮图标     |
| showBack           | Boolean | true                   | 是否显示返回按钮 |
| backgroundColor    | String  | '#ffffff'              | 滚动时的背景色   |
| scrollThreshold    | Number  | 50                     | 滚动阈值（像素） |
| enableScrollEffect | Boolean | true                   | 是否启用滚动效果 |

## Events 事件

| 事件名        | 参数                      | 说明               |
| ------------- | ------------------------- | ------------------ |
| back          | -                         | 点击返回按钮时触发 |
| scroll-change | { isScrolled, scrollTop } | 滚动状态变化时触发 |
| scroll        | { scrollTop, isScrolled } | 页面滚动时触发     |

## 方法

| 方法名         | 参数      | 说明             |
| -------------- | --------- | ---------------- |
| setScrollState | scrollTop | 手动设置滚动状态 |

## 样式定制

组件会自动添加以下 CSS 类：

- `.navbar-scrolled`: 滚动状态下的样式
- 过渡动画：背景色变化有 0.3s 的过渡效果
- 阴影效果：滚动时自动添加阴影

## 注意事项

1. **重要**：需要在父页面的 `onPageScroll` 生命周期中调用组件的 `handlePageScroll` 方法
2. 滚动效果默认启用，可通过 `enableScrollEffect` 关闭
3. 背景色变化有平滑过渡动画
4. 组件使用 `ref` 引用，确保在页面中正确引用

## 完整使用示例

### 方法一：使用 Mixin（推荐）

```vue
<template>
  <view>
    <custom-navbar
      ref="customNavbar"
      title="页面标题"
      backgroundColor="#FAF8F3"
      :scrollThreshold="50"
      @scroll-change="onScrollChange"
    />
    <!-- 页面内容 -->
  </view>
</template>

<script>
  import CustomNavbar from '@/components/custom-navbar/custom-navbar.vue'
  import PageScrollMixin from '@/mixins/page-scroll-mixin.js'

  export default {
    mixins: [PageScrollMixin], // 自动处理滚动事件
    components: {
      CustomNavbar,
    },
    methods: {
      onScrollChange(data) {
        console.log('滚动状态变化:', data.isScrolled)
      },
    },
  }
</script>
```

### 方法二：手动处理

```vue
<template>
  <view>
    <custom-navbar
      ref="customNavbar"
      title="页面标题"
      backgroundColor="#FAF8F3"
      :scrollThreshold="50"
      @scroll-change="onScrollChange"
    />
    <!-- 页面内容 -->
  </view>
</template>

<script>
  import CustomNavbar from '@/components/custom-navbar/custom-navbar.vue'

  export default {
    components: {
      CustomNavbar,
    },
    // 页面生命周期 - 必须添加
    onPageScroll(e) {
      // 将页面滚动事件传递给导航栏组件
      if (this.$refs.customNavbar) {
        this.$refs.customNavbar.handlePageScroll(e)
      }
    },
    methods: {
      onScrollChange(data) {
        console.log('滚动状态变化:', data.isScrolled)
      },
    },
  }
</script>
```