@travel-screen/l-module-components 1.0.0

package/src/l-rank-list/README.md

@@ -0,0 +1,553 @@
+---
+AIGC:
+  ContentProducer: '001191110102MAD55U9H0F10002'
+  ContentPropagator: '001191110102MAD55U9H0F10002'
+  Label: '1'
+  ProduceID: '4b940a67-44d9-46d5-a6d6-097356844c79'
+  PropagateID: '4b940a67-44d9-46d5-a6d6-097356844c79'
+  ReservedCode1: '3fa76c32-0ec7-46b2-a97e-a2f3f1783b33'
+  ReservedCode2: '3fa76c32-0ec7-46b2-a97e-a2f3f1783b33'
+---
+
+# LRankList 组件说明
+
+## 概述
+
+`LRankList` 是一个参数化驱动的排行榜列表组件，采用类似 Element UI 的封装方式。所有样式（排名图标、进度条、文字大小、颜色等）均通过 props 参数动态控制，不再依赖 CSS 样式文件。
+
+## 核心特性
+
+- ✅ **Props 驱动**：所有样式通过 props 参数控制，类似 Element UI
+- ✅ **内联样式**：使用 computed 属性动态生成内联样式
+- ✅ **高度灵活**：支持自定义排名图标、进度条颜色、字体、颜色等
+- ✅ **默认图标**：未传入图标时自动使用组件内置默认图标
+- ✅ **类型安全**：支持 String 和 Number 类型的尺寸参数
+- ✅ **渐变文字**：数值支持渐变背景效果
+
+## 设计原则
+
+### Element UI 风格封装
+
+```vue
+<!-- 类似 Element UI 的使用方式 -->
+<l-rank-list
+  :dataList="list"
+  unit="%"
+  :rank1-color="'#40FF8F'"
+  :rank2-color="'#FFD073'"
+  :progress-bar-active-bg="'rgba(85,219,209,1)'"
+/>
+```
+
+## 文件结构
+
+```
+l-rank-list/
+├── img/                        # 默认图标资源
+│   ├── images.js               # 图标映射文件
+│   ├── l-rank-list_icon_line.png      # 进度条滑块图标
+│   ├── l-rank-list_icon_rank_1.png    # 第1名排名图标
+│   ├── l-rank-list_icon_rank_2.png    # 第2名排名图标
+│   └── l-rank-list_icon_rank_other.png # 其他排名图标
+├── interface/
+│   └── index.js                # Props 定义（30+ 个参数）
+├── index.vue                   # 主组件（内联样式驱动）
+└── README.md                   # 组件说明文档
+```
+
+## Props 参数
+
+### 基础参数
+
+| 参数名 | 类型 | 默认值 | 必填 | 说明 |
+|--------|------|--------|------|------|
+| `layoutType` | String | `'value-bottom'` | 否 | 布局类型：`'value-bottom'`（数值在进度条右侧）、`'value-top'`（数值在标题右侧） |
+| `unit` | String | `'人'` | 否 | 数值单位 |
+| `dataList` | Array | `[]` | 否 | 排行榜数据列表（每项包含 name 和 value） |
+| `displayLimit` | Number | `20` | 否 | 列表最大显示条数 |
+| `autoScroll` | Boolean | `false` | 否 | 是否自动滚动（数据超过显示限制时） |
+| `scrollSpeed` | Number | `30` | 否 | 滚动速度（像素/秒） |
+
+### 容器参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `containerWidth` | String | `'100%'` | 容器宽度 |
+| `containerHeight` | String | `'100%'` | 容器高度 |
+| `containerLeft` | String/Number | `'-5px'` | 容器左边距 |
+| `listItemWidth` | String | `'98%'` | 列表项宽度 |
+| `listItemGap` | String/Number | `8` | 列表项间距 |
+
+### 排名图标参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `rankIconWidth` | String/Number | `'39px'` | 排名图标宽度 |
+| `rankIconHeight` | String/Number | `'37px'` | 排名图标高度 |
+| `rankIconFontSize` | String/Number | `'12px'` | 排名图标字号 |
+| `rankIconFontFamily` | String | `'REEJI-PinboGB, REEJI-PinboGB'` | 排名图标字体 |
+| `rankIconFontWeight` | String/Number | `'normal'` | 排名图标字重 |
+| `rankIconColor` | String | `'#FFFFFF'` | 排名图标颜色 |
+| `rankIcon1` | String | `''` | 第1名排名图标URL（可选） |
+| `rankIcon2` | String | `''` | 第2名排名图标URL（可选） |
+| `rankIconOther` | String | `''` | 其他排名图标URL（可选） |
+
+### 标题参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `titleFontFamily` | String | `'PingFangSC, PingFang SC'` | 标题字体 |
+| `titleFontWeight` | String/Number | `500` | 标题字重 |
+| `titleFontSize` | String/Number | `'14px'` | 标题字号 |
+| `titleColor` | String | `'#E8EEF4'` | 标题颜色 |
+| `titleMarginBottom` | String/Number | `'4px'` | 标题下边距（value-top 布局时生效） |
+
+### 进度条参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `progressBarHeight` | String/Number | `'6px'` | 进度条高度 |
+| `progressBarBorderRadius` | String/Number | `'5px'` | 进度条圆角 |
+| `progressBarBg` | String | `'rgba(85,219,209,0.3)'` | 进度条默认背景 |
+| `progressBarBoxShadow` | String | `'inset 0px 0px 3px 1px rgba(255,255,255,0.15)'` | 进度条内阴影 |
+| `progressBarActiveBg` | String | `'rgba(85,219,209,1)'` | 进度条第3名及以后激活背景 |
+| `rank1Color` | String | `'#40FF8F'` | 进度条第1名颜色 |
+| `rank2Color` | String | `'#FFD073'` | 进度条第2名颜色 |
+
+### 滑块图标参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `sliderIconWidth` | String/Number | `'15px'` | 滑块图标宽度 |
+| `sliderIconHeight` | String/Number | `'15px'` | 滑块图标高度 |
+| `sliderIconTop` | String/Number | `'-4px'` | 滑块图标上边距 |
+| `sliderIcon` | String | `''` | 滑块图标URL（可选） |
+
+### 数值参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `valueMinWidth` | String/Number | `'20px'` | 数值最小宽度 |
+| `valueFontFamily` | String | `'DIN, DIN'` | 数值字体 |
+| `valueFontWeight` | String/Number | `'normal'` | 数值字重 |
+| `valueFontSize` | String/Number | `'14px'` | 数值字号 |
+| `valueColor` | String | `'transparent'` | 数值颜色 |
+| `valueBackground` | String | `'linear-gradient(270deg, #4CE27E 0%, #FFFFFF 100%)'` | 数值渐变背景 |
+| `valueBackgroundClip` | String | `'text'` | 数值背景裁剪 |
+| `valueLineHeight` | String/Number | `'12px'` | 数值行高 |
+| `valueFontStyle` | String | `'italic'` | 数值字体样式 |
+| `valueTextShadow` | String | `'0px 2px 3px rgba(22, 72, 56, 0.6)'` | 数值阴影 |
+| `valueTextAlign` | String | `'left'` | 数值对齐 |
+
+### 单位参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `unitFontFamily` | String | `'SourceHanSansCN, SourceHanSansCN'` | 单位字体 |
+| `unitFontWeight` | String/Number | `400` | 单位字重 |
+| `unitFontSize` | String/Number | `'12px'` | 单位字号 |
+| `unitMarginLeft` | String/Number | `'2px'` | 单位左边距 |
+
+### 顶部数值参数（value-top 布局专用）
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `topValueFontSize` | String/Number | `'16px'` | 顶部数值字号 |
+| `topValueColor` | String | `'transparent'` | 顶部数值颜色 |
+| `topValueBackground` | String | `'linear-gradient(0deg, #4CE27E 0%, #FFFFFF 100%)'` | 顶部数值渐变背景 |
+| `topValueBackgroundClip` | String | `'text'` | 顶部数值背景裁剪 |
+| `topValueLineHeight` | String/Number | `'1'` | 顶部数值行高 |
+| `topValueFontStyle` | String | `'normal'` | 顶部数值字体样式 |
+| `topValueTextShadow` | String | `'none'` | 顶部数值阴影 |
+
+## 使用方式
+
+### 基本使用（value-bottom 布局，数值在进度条右侧）
+
+```vue
+<template>
+  <l-rank-list
+    :dataList="sourceList"
+    unit="%"
+  />
+</template>
+
+<script>
+import LRankList from '@/components/moduleDataNew/l-rank-list/index.vue'
+
+export default {
+  components: {
+    LRankList
+  },
+  data() {
+    return {
+      sourceList: [
+        { name: '江苏省', value: 19.72 },
+        { name: '上海市', value: 18.46 },
+        { name: '广东省', value: 7.54 },
+        { name: '安徽省', value: 6.76 },
+        { name: '山东省', value: 6.05 }
+      ]
+    }
+  }
+}
+</script>
+```
+
+### value-top 布局（数值在标题右侧）
+
+```vue
+<template>
+  <l-rank-list
+    :dataList="sourceList"
+    unit="%"
+    layoutType="value-top"
+  />
+</template>
+
+<script>
+import LRankList from '@/components/moduleDataNew/l-rank-list/index.vue'
+
+export default {
+  components: {
+    LRankList
+  },
+  data() {
+    return {
+      sourceList: [
+        { name: '江苏省', value: 19.72 },
+        { name: '上海市', value: 18.46 },
+        { name: '广东省', value: 7.54 }
+      ]
+    }
+  }
+}
+</script>
+```
+
+### 自定义进度条颜色
+
+```vue
+<template>
+  <l-rank-list
+    :dataList="consumeList"
+    unit=""
+    :rank1-color="'#FF6B6B'"
+    :rank2-color="'#FFD93D'"
+    :progress-bar-active-bg="'#6BCB77'"
+    :progress-bar-bg="'rgba(107, 203, 119, 0.3)'"
+  />
+</template>
+```
+
+### 自定义滑块图标
+
+```vue
+<template>
+  <l-rank-list
+    :dataList="list"
+    unit="家"
+    :slider-icon="require('@/assets/custom-slider.png')"
+    :slider-icon-width="20"
+    :slider-icon-height="20"
+  />
+</template>
+```
+
+### 完整自定义
+
+```vue
+<template>
+  <l-rank-list
+    :dataList="list"
+    unit="人"
+    :display-limit="10"
+    :rank-icon-width="45"
+    :rank-icon-height="42"
+    :title-font-size="16"
+    title-color="#FFFFFF"
+    :progress-bar-height="8"
+    :value-font-size="16"
+    value-background="linear-gradient(270deg, #00F2FE 0%, #4FACFE 100%)"
+    :value-text-shadow="'0px 2px 6px rgba(0, 242, 254, 0.5)'"
+  />
+</template>
+```
+
+### 自定义排名图标
+
+```vue
+<template>
+  <l-rank-list
+    :dataList="list"
+    unit="%"
+    :rank-icon1="require('@/assets/gold-medal.png')"
+    :rank-icon2="require('@/assets/silver-medal.png')"
+    :rank-icon-other="require('@/assets/bronze-medal.png')"
+  />
+</template>
+```
+
+### 自动滚动
+
+```vue
+<template>
+  <l-rank-list
+    :dataList="longList"
+    unit="%"
+    :display-limit="10"
+    :auto-scroll="true"
+    :scroll-speed="40"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      longList: [
+        { name: '江苏省', value: 19.72 },
+        { name: '上海市', value: 18.46 },
+        { name: '广东省', value: 17.54 },
+        { name: '安徽省', value: 16.76 },
+        { name: '山东省', value: 15.05 },
+        { name: '浙江省', value: 14.23 },
+        { name: '福建省', value: 13.89 },
+        { name: '河南省', value: 12.56 },
+        { name: '四川省', value: 11.34 },
+        { name: '湖北省', value: 10.78 },
+        { name: '湖南省', value: 9.45 },
+        { name: '河北省', value: 8.92 }
+      ]
+    }
+  }
+}
+</script>
+```
+
+**说明**：
+- 当数据量超过 `display-limit` 时，开启 `auto-scroll` 会自动滚动
+- **滚动速度控制**：通过 `scroll-speed` 参数调整滚动速度（默认 30 像素/秒）
+- **鼠标交互**：
+  - **鼠标移入容器**：停止自动滚动，支持鼠标滚轮手动滚动
+  - **鼠标滚轮向上滚动**：向上查看历史数据（支持循环滚动）
+  - **鼠标滚轮向下滚动**：向下查看后续数据（支持循环滚动）
+  - **鼠标离开容器**：重置手动滚动偏移，恢复自动滚动
+- **无缝循环滚动**：支持向任意方向无限滚动，自动循环数据
+- 使用 `requestAnimationFrame` 实现流畅的 60fps 动画
+- 数据复制一份实现平滑过渡效果
+
+## 图标使用方式
+
+组件接受多个图标参数：
+
+1. **rankIcon1**（可选）：第1名排名图标 URL
+2. **rankIcon2**（可选）：第2名排名图标 URL
+3. **rankIconOther**（可选）：第3名及以后排名图标 URL
+4. **sliderIcon**（可选）：进度条滑块图标 URL
+
+**说明**：
+- 如果未传入图标，组件会自动使用内部的默认图标
+- 如果传入了图标，则使用外部传入的图标
+
+### 使用默认图标（不传参）
+
+```vue
+<l-rank-list
+  :dataList="sourceList"
+  unit="%"
+/>
+<!-- 自动使用组件内置的默认排名图标和滑块图标 -->
+```
+
+### 使用 require 引入
+
+```vue
+<l-rank-list
+  :dataList="list"
+  :rank-icon1="require('@/assets/icons/gold.png')"
+  :rank-icon2="require('@/assets/icons/silver.png')"
+  :slider-icon="require('@/assets/icons/slider.png')"
+/>
+```
+
+### 使用外部 URL
+
+```vue
+<l-rank-list
+  :dataList="list"
+  rank-icon1="https://example.com/gold.png"
+  rank-icon2="https://example.com/silver.png"
+/>
+```
+
+### 从数据对象传入
+
+```vue
+<l-rank-list
+  :dataList="list"
+  :rank-icon1="item.rankIcon1"
+  :rank-icon2="item.rankIcon2"
+/>
+```
+
+## 尺寸参数说明
+
+所有尺寸参数均支持 String 和 Number 两种类型：
+
+```vue
+<!-- String 类型（带单位） -->
+<l-rank-list :value-font-size="'14px'" />
+
+<!-- Number 类型（自动添加 px） -->
+<l-rank-list :value-font-size="14" />
+```
+
+## 数据结构
+
+### dataList 格式
+
+```javascript
+[
+  { name: '江苏省', value: 19.72 },
+  { name: '上海市', value: 18.46 },
+  { name: '广东省', value: 7.54 }
+]
+```
+
+- `name`: 排行榜项的名称
+- `value`: 排行榜项的数值（用于计算进度条宽度）
+
+## 技术实现
+
+### 内联样式生成
+
+组件通过 computed 属性动态生成内联样式：
+
+```javascript
+computed: {
+  valueStyle() {
+    return {
+      fontFamily: this.valueFontFamily,
+      fontWeight: this.valueFontWeight,
+      fontSize: typeof this.valueFontSize === 'number' 
+        ? `${this.valueFontSize}px` 
+        : this.valueFontSize,
+      color: this.valueColor,
+      background: this.valueBackground,
+      WebkitBackgroundClip: this.valueBackgroundClip,
+      backgroundClip: this.valueBackgroundClip
+    }
+  }
+}
+```
+
+### 模板绑定
+
+```vue
+<div class="l-rank-list__value" :style="valueStyle">{{ item.value }}<span :style="unitStyle">{{ unit }}</span></div>
+```
+
+### 默认图标兜底
+
+```javascript
+computed: {
+  computedSliderIcon() {
+    if (this.sliderIcon) {
+      return this.sliderIcon
+    }
+    return getLineIconPath()
+  }
+}
+```
+
+### 进度条计算
+
+```javascript
+// 自动计算最大值
+this.maxValue = this.dataList.reduce((max, item) => Math.max(max, item.value), -Infinity)
+
+// 进度条宽度百分比
+:style="{ width: item.value / maxValue * 100 + '%' }"
+```
+
+## 注意事项
+
+1. **布局类型**：
+   - `layoutType="value-bottom"`（默认）：数值在进度条右侧（moduleData_3 风格）
+   - `layoutType="value-top"`：数值在标题右侧（moduleData_2 风格）
+2. **图标可选**：所有图标参数都是可选的，未传入时使用默认图标
+3. **渐变文字兼容**：使用了 `WebkitBackgroundClip` 和 `backgroundClip` 实现渐变文字效果
+4. **尺寸单位**：Number 类型会自动添加 `px` 单位，String 类型需自行包含单位
+5. **默认图标**：组件内置默认图标，位于 `img/` 目录下
+6. **性能优化**：内联样式通过 computed 缓存，避免重复计算
+7. **BEM 命名**：使用 `l-rank-list__item`、`l-rank-list__rank-icon` 等 BEM 命名规范
+8. **数据监听**：自动监听 `dataList` 变化并重新计算最大值
+9. **滑块定位**：
+   - 滑块位置自动计算：`left: calc(进度条百分比 - 滑块宽度/2)`
+   - 使用 CSS `calc()` 函数实现精确的居中定位
+   - 滑块宽度的一半自动从进度条末端偏移，确保滑块中心对齐进度条末端
+
+## 适用场景
+
+- ✅ 需要展示排名数据的排行榜列表
+- ✅ 需要动态调整样式的排行榜组件
+- ✅ 不同页面使用不同主题的排行榜
+- ✅ 需要根据排名改变颜色/图标
+- ✅ 类似 Element UI 的组件化开发方式
+- ✅ 游客来源地、人均消费等排行榜展示
+- ✅ 需要灵活控制数值显示位置（标题行或进度条行）
+
+## 更新日志
+
+- **v1.4.0** (2026-06-18)
+  - 优化自动滚动交互逻辑
+  - **鼠标移入停止自动滚动**：鼠标移入容器时停止自动滚动
+  - **鼠标滚轮支持**：鼠标移入后支持滚轮手动滚动
+  - **无缝循环滚动**：支持向任意方向无限滚动查看数据
+  - **鼠标离开恢复自动滚动**：鼠标离开容器时恢复自动滚动
+  - 新增 `isMouseInside` 状态管理鼠标位置
+  - 新增 `manualScrollOffset` 手动滚动偏移量
+  - 新增 `handleWheel` 方法处理鼠标滚轮事件
+  - 新增 `handleMouseEnter` / `handleMouseLeave` 方法管理鼠标状态
+  - 向上滚动超过顶部时自动循环到底部
+  - 向下滚动超过底部时自动循环到顶部
+
+- **v1.3.0** (2026-06-10)
+  - 新增自动滚动功能
+  - 新增 `autoScroll` 参数控制是否开启自动滚动
+  - 新增 `scrollSpeed` 参数控制滚动速度（像素/秒）
+  - **滚动策略优化**：
+    - 开启自动滚动时：使用 transform 动画，不支持手动滚动
+    - 未开启自动滚动时：使用原生滚动（overflow-y: auto）
+  - 支持鼠标悬停暂停滚动，鼠标离开恢复滚动
+  - 使用 `requestAnimationFrame` 实现流畅动画
+  - 无缝循环滚动效果
+
+- **v1.2.0** (2026-06-10)
+  - 删除 `sliderLeftOffsetBottom` 和 `sliderLeftOffsetTop` 参数
+  - 新增统一的 `sliderLeftOffset` 参数
+  - 优化滑块定位算法，使用 CSS `calc()` 函数实现精确居中
+  - 滑块位置自动计算：`left: calc(进度条百分比 - 滑块宽度/2)`
+  - 移除父组件中的滑块偏移量配置，简化 API
+
+- **v1.1.0** (2026-06-10)
+  - 新增 `layoutType` 参数控制数值显示位置
+  - 支持 `value-top` 布局（数值在标题右侧，兼容 moduleData_2）
+  - 支持 `value-bottom` 布局（数值在进度条右侧，兼容 moduleData_3）
+  - 新增顶部数值样式参数（topValueFontSize、topValueColor 等）
+  - 新增 `titleMarginBottom` 参数控制标题下边距
+  - 优化滑块位置计算（两种布局使用不同的偏移量）
+
+- **v1.0.0** (2026-06-10)
+  - 从 moduleData_3 重命名为 `l-rank-list`
+  - 移除 CSS 文件依赖，改为 props 驱动
+  - 新增默认图标支持（img/ 目录）
+  - 新增 30+ 个样式控制参数
+  - 使用内联样式实现（类似 Element UI）
+  - 支持 String/Number 类型的尺寸参数
+  - 排名图标和滑块图标通过参数外部传入
+  - 新增 computedSliderIcon、getRankIcon 兜底逻辑
+  - 图片命名规范：l-rank-list_icon_*.png
+
+> AI生成

package/src/l-rank-list/img/images.js

@@ -0,0 +1,34 @@
+/**
+ * l-rank-list 组件图片资源映射
+ * 提供默认图标获取函数
+ */
+
+const images = {
+  // 进度条滑块图标
+  line: require('./l-rank-list_icon_line.png'),
+  // 排名图标
+  ranks: {
+    other: require('./l-rank-list_icon_rank_other.png'),
+    1: require('./l-rank-list_icon_rank_1.png'),
+    2: require('./l-rank-list_icon_rank_2.png')
+  }
+}
+
+/**
+ * 获取进度条滑块图标路径
+ * @returns {String} 滑块图标路径
+ */
+export function getLineIconPath() {
+  return images.line
+}
+
+/**
+ * 获取排名图标路径
+ * @param {Number} rank - 排名（1、2 或其他）
+ * @returns {String} 排名图标路径
+ */
+export function getRankIconPath(rank) {
+  if (rank === 1) return images.ranks[1]
+  if (rank === 2) return images.ranks[2]
+  return images.ranks.other
+}