更新记录

1.0.3（2026-04-24） 下载此版本

新增v-model

1.0.2（2026-04-24） 下载此版本

完善示例

1.0.0（2026-04-24） 下载此版本

init

平台兼容性

uni-app(4.03)

ideal-ruler - uni-app 高度可定制刻度尺组件

这是一个为 uni-app 设计的高度灵活和可定制的刻度尺组件，适用于各种需要值选择的场景。

概述

ideal-ruler 通过利用插槽（slots），可以完全定制其外观，包括容器、指针和刻度项。它还具有在滚动停止后自动吸附到最近刻度的功能。

特性

• 高可定制性：通过插槽完全控制指针和刻度的样式。
• 易于集成：作为 uni_module，它支持 easycom，无需安装即可轻松使用。
• 数据驱动：只需提供一个数据数组即可生成刻度尺。
• 流畅体验：包含自动吸附动画，提供更好的用户体验。
• v-model支持：支持 v-model 双向绑定当前选中项的索引。
• 跨平台：支持 uni-app 所支持的各种平台。

核心概念

为了更好地使用此组件，理解以下几个核心概念非常重要：

1. 刻度 (Scale Item) 刻度尺是由一个个独立的“刻度”组成的。您传入的 list 数组中的每一项数据，都会对应生成一个刻度。

2. 刻度容器与 gap 属性

   • 每个刻度实际上是一个宽度由 gap 属性决定的容器。例如，如果您设置 :gap="40"，那么每个刻度的宽度就是 40px。
   • 您在 #item 插槽中编写的自定义内容（例如刻度线、数字）都是在这个容器内部进行布局的。
   • 这个容器的高度默认为 100%，它会撑满整个组件的高度。

3. 吸附行为 (Snapping) 当您停止滚动时，组件会自动计算距离中心指针最近的一个刻度，并平滑地滚动，使得该刻度的正中心与指针完全对齐。change 事件会在吸附完成后触发。

4. 关于高度 再次强调，本组件的高度由其父容器决定。您必须为 <ideal-ruler> 的外部容器设置一个明确的高度（例如 height: 100px;），否则组件将无法显示。

如何使用

由于此组件以 uni_module 形式打包，您可以直接在页面中使用它，无需导入或注册，这得益于 uni-app 的 easycom 特性。

示例代码

以下是一个完整的示例，演示如何自定义指针和刻度项。

<template>
    <view class="container">
        <!-- 刻度尺包装容器，用于控制整体高度 -->
        <view class="ruler-wrapper">
            <ideal-ruler :list="rulerList" :gap="40" @change="rulerChange">
                <!-- 1. 自定义中间指针 -->
                <template #pointer>
                    <view class="custom-pointer" />
                </template>

                <!-- 2. 自定义刻度项 -->
                <template #item="{ item, index }">
                    <view class="custom-item">
                        <!-- 逻辑：每10个刻度变长 -->
                        <view class="tick-line" :class="{ 'is-major': index % 10 === 0 }" />
                        <!-- 逻辑：只在整10处显示文字 -->
                        <text v-if="index % 10 === 0" class="tick-text">{{ item }}</text>
                    </view>
                </template>
            </ideal-ruler>
        </view>

        <view class="value-display">当前选择：{{ activeValue }}</view>
    </view>
</template>

<script setup lang="ts">
    import { ref } from 'vue'

    // 准备数据：10 到 60 的刻度
    const rulerList = ref(Array.from({ length: 51 }, (_, i) => i + 10))
    const activeValue = ref(10)

    // 监听刻度尺的 change 事件
    function rulerChange(item : number, index : number) {
        activeValue.value = item
        console.log('当前索引:', index)
    }
</script>

<style>
    /* 您必须为父容器指定高度 */
    .ruler-wrapper {
        width: 100%;
        height: 100px;
        margin-top: 50px;
    }

    /* 指针样式 */
    .custom-pointer {
        height: 40px;
        width: 3px;
        background-color: #6cc541;
        border-radius: 2px;
    }

    /* 刻度容器 */
    .custom-item {
        width: 100%;
        height: 100%;
        display: flex;
        flex-direction: column;
        align-items: center;
        justify-content: flex-start;
    }

    /* 刻度线 */
    .tick-line {
        width: 2px;
        height: 20px;
        background-color: #e0e0e0;
    }

    /* 主要刻度线的样式 */
    .tick-line.is-major {
        height: 35px;
        background-color: #333;
    }

    /* 文字样式 */
    .tick-text {
        font-size: 12px;
        color: #666;
        margin-top: 10px;
    }

    .value-display {
        text-align: center;
        margin-top: 30px;
        font-size: 20px;
        font-weight: bold;
    }
</style>

组件属性 (Props)

v-model

组件支持 v-model 来双向绑定当前选中的索引。

示例

你可以使用 v-model 来简化状态管理，直接读取和设置刻度尺的当前位置。

<template>
  <view class="ruler-wrapper">
    <ideal-ruler v-model="currentIndex" :list="dataList" />
  </view>
  <view>当前索引: {{ currentIndex }}</view>
  <button @click="goToIndex">跳转到索引 15</button>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const dataList = ref(Array.from({ length: 51 }, (_, i) => i));
const currentIndex = ref(0); // v-model 绑定的是索引

function goToIndex() {
  currentIndex.value = 15;
}
</script>

组件事件 (Events)

组件插槽 (Slots)