HomeLease/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>
```