YGChatCS/src/uni_modules/yo-indicator-dot/readme.md

yo-indicator-dot

🚀 功能强大的轮播指示器组件，支持多种显示模式、形状和动画效果

✨ 功能特点

• 🎯 零配置开箱即用 - 不传任何参数就能正常工作
• 🎨 多种显示模式 - 点状、数字、进度条、缩略图
• 🔷 多种形状 - 圆形、方形、菱形、条形、自定义
• ⚡️ 丰富动画 - 缩放、旋转、弹性、脉冲、淡入淡出
• 📍 灵活位置 - 顶部、底部、左侧、右侧、内嵌
• 🖱️ 交互功能 - 点击跳转、悬停效果
• 📱 全平台支持 - H5、小程序、App
• 🔄 向后兼容 - 现有代码升级无压力

🚀 快速开始

1. 安装

通过 HBuilderX 插件市场安装：

1. 打开 HBuilderX
2. 点击菜单栏 工具 → 插件安装
3. 搜索 yo-indicator-dot 并安装
4. 或直接下载 uni_modules 文件夹到项目中

2. 基础使用

<template>
  <view>
    <swiper @change="onSwiperChange" indicator-dots="false">
      <swiper-item v-for="(item, index) in bannerList" :key="index">
        <view>{{ item.title }}</view>
      </swiper-item>
    </swiper>
    
    <!-- 最简单的使用方式 -->
    <yo-indicator-dot 
      :current-index="currentIndex" 
      :length="bannerList.length"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue'

const currentIndex = ref(0)
const bannerList = ref([
  { title: '轮播图 1' },
  { title: '轮播图 2' },
  { title: '轮播图 3' }
])

const onSwiperChange = (e) => {
  currentIndex.value = e.detail.current
}
</script>

🎨 显示模式

点状模式（默认）

<yo-indicator-dot 
  :current-index="currentIndex" 
  :length="length"
  mode="dots"
  shape="circle"
  animation="scale"
/>

数字模式

<yo-indicator-dot 
  :current-index="currentIndex" 
  :length="length"
  mode="numbers"
  active-color="#00cc66"
/>

进度条模式

<yo-indicator-dot 
  :current-index="currentIndex" 
  :length="length"
  mode="progress"
  default-color="#e5e5e5"
  active-color="#ff6b6b"
  progress-height="8rpx"
/>

缩略图模式

<yo-indicator-dot 
  :current-index="currentIndex" 
  :length="length"
  mode="thumbnails"
  thumbnail-size="60rpx"
>
  <template #thumbnail="{ index, isActive }">
    <image :src="thumbnails[index]" />
  </template>
</yo-indicator-dot>

🔷 形状样式

<!-- 圆形（默认） -->
<yo-indicator-dot shape="circle" />

<!-- 方形 -->
<yo-indicator-dot shape="square" />

<!-- 菱形 -->
<yo-indicator-dot shape="diamond" />

<!-- 条形 -->
<yo-indicator-dot shape="bar" />

<!-- 自定义 -->
<yo-indicator-dot shape="custom" custom-content>
  <template #indicator="{ index, isActive }">
    <text>{{ index + 1 }}</text>
  </template>
</yo-indicator-dot>

⚡️ 动画效果

<!-- 缩放动画（默认） -->
<yo-indicator-dot animation="scale" />

<!-- 旋转动画 -->
<yo-indicator-dot animation="rotate" />

<!-- 弹性动画 -->
<yo-indicator-dot animation="bounce" />

<!-- 脉冲动画 -->
<yo-indicator-dot animation="pulse" />

<!-- 淡入淡出 -->
<yo-indicator-dot animation="fade" />

<!-- 无动画 -->
<yo-indicator-dot animation="none" />

📍 位置布局

<!-- 底部（默认） -->
<yo-indicator-dot position="bottom" />

<!-- 顶部 -->
<yo-indicator-dot position="top" />

<!-- 左侧 -->
<yo-indicator-dot position="left" />

<!-- 右侧 -->
<yo-indicator-dot position="right" />

<!-- 内嵌 -->
<yo-indicator-dot position="inside" />

🖱️ 交互功能

<yo-indicator-dot 
  :current-index="currentIndex" 
  :length="length"
  :clickable="true"
  :hoverable="true"
  @click="onIndicatorClick"
  @change="onIndicatorChange"
  @hover="onIndicatorHover"
/>

📋 完整参数

基础参数（向后兼容）

参数	类型	默认值	说明
current-index	Number	0	当前轮播的下标
length	Number	0	轮播数据的长度
default-color	String	#cccccc	默认指示点的颜色
active-color	String	#007aff	选中指示点的颜色
default-width	String	12rpx	默认指示点宽度
active-width	String	20rpx	选中指示点宽度
dot-height	String	12rpx	指示点高度
gap	String	12rpx	指示点间距
duration	String	0.3s	动画持续时间

💡 智能形状提示: 当 active-width 或 default-width 是 dot-height 的2倍以上时，组件会自动使用条形样式，确保视觉效果更佳。

新增功能参数

参数	类型	默认值	说明
mode	String	dots	显示模式：dots/numbers/progress/thumbnails
shape	String	circle	指示器形状：circle/square/diamond/bar/custom
animation	String	scale	动画效果：scale/rotate/bounce/pulse/fade/none
position	String	bottom	位置：top/bottom/left/right/inside
clickable	Boolean	true	是否可点击
hoverable	Boolean	true	是否显示悬停效果
custom-content	Boolean	false	自定义内容（用于custom形状）
progress-height	String	6rpx	进度条高度（progress模式）
thumbnail-size	String	60rpx	缩略图尺寸（thumbnails模式）

🎯 事件

事件名	说明	参数
change	指示器切换时触发	index: 新的下标
click	点击指示器时触发	index: 点击的下标
hover	悬停指示器时触发	{ index, isHover }

🔧 插槽

插槽名	说明	参数
indicator	自定义指示器内容	{ index, isActive }
thumbnail	自定义缩略图内容	{ index, isActive }

💡 使用技巧

1. 渐进式增强

<!-- 基础使用 -->
<yo-indicator-dot :current-index="index" :length="length" />

<!-- 需要更多功能时再添加参数 -->
<yo-indicator-dot 
  :current-index="index" 
  :length="length"
  mode="numbers"
  animation="bounce"
/>

2. 主题定制

<yo-indicator-dot 
  :current-index="index" 
  :length="length"
  default-color="rgba(255,255,255,0.3)"
  active-color="rgba(255,255,255,0.9)"
  position="inside"
/>

3. 响应式设计

<yo-indicator-dot 
  :current-index="index" 
  :length="length"
  :gap="isMobile ? '8rpx' : '12rpx'"
  :dot-height="isMobile ? '8rpx' : '12rpx'"
/>

📱 平台支持

• ✅ H5（Safari、Chrome、Firefox）
• ✅ App（Android、iOS、HarmonyOS）
• ✅ 微信小程序、支付宝小程序、百度小程序
• ✅ 字节跳动小程序、QQ小程序、快手小程序
• ✅ 钉钉小程序、京东小程序

🔄 更新日志

v2.0.0

• ✨ 新增多种显示模式（数字、进度条、缩略图）
• ✨ 新增多种形状（方形、菱形、条形、自定义）
• ✨ 新增丰富动画效果
• ✨ 新增位置布局选项
• ✨ 新增交互功能（点击、悬停）
• 🔧 保持向后兼容，现有代码无需修改
• 📚 完善文档和演示

v1.0.0

• 🎉 初始版本发布
• 基础点状指示器功能
• 支持自定义颜色和尺寸

License

MIT