vue3-measuring-scale
vue3-measuring-scale是一款为Vue 3开发的高性能、高定制性、交互优雅的Canvas 刻度尺（标尺选择器）组件库。它专为移动端及大屏可视化表单场景设计，可用于身高、体重、温度、年龄等任何连续或离散数值的直观滑动选择。
🔗在线 Demo 演示
✨ 特性
- ⚡Canvas 渲染：核心部分完全由 HTML Canvas 绘制，避免大量 DOM 渲染，即使大范围数值交互也极为流畅。
- 📱高清显示支持：自动适配高分屏（Retina），智能检测并应用
window.devicePixelRatio缩放，避免线条模糊。 - 🏃物理惯性滑动：内置甩拽减速运动学模型（Momentum Physics），支持随手势甩动滑行。
- 🧲自动磁吸对齐：当惯性滑动结束或拖拽释放时，会自动回弹并磁吸对齐到最接近的有效步长（
step）数值。 - ⚙️高精度防噪：内置高精度过滤截断机制，彻底根治 JavaScript 浮点数在运算时产生的类似
62.30000000000004等浮点噪点。 - 📐双向布局：支持水平（Horizontal）与垂直（Vertical）两套布局朝向。
- 🌓内置主题与高定制性：支持白昼（light）/ 深色（dark）两套内置配色系统，支持动态调整指针颜色、刻度间距、大刻度间隔，并支持完全自定义的标签文字格式化函数。
- 🔄支持滚轮/触控板：支持鼠标滚轮与笔记本双指滚动操作。
📦 安装
使用您喜爱的包管理器安装组件包：
# npmnpminstallvue3-measuring-scale# yarnyarnaddvue3-measuring-scale# pnpmpnpmaddvue3-measuring-scale🚀 快速上手
1. 全局注册使用（作为插件）
在main.ts/main.js中注册插件：
import{createApp}from'vue'importAppfrom'./App.vue'// 导入组件包与样式文件importVue3MeasuringScalefrom'vue3-measuring-scale'import'vue3-measuring-scale/dist/style.css'constapp=createApp(App)// 注册插件app.use(Vue3MeasuringScale)app.mount('#app')全局注册后，您可以在项目任何地方直接使用<MeasuringScale />组件：
<script setup lang="ts"> import { ref } from 'vue' const weight = ref(72.5) </script> <template> <div class="scale-box"> <MeasuringScale v-model="weight" :min="30" :max="150" :step="0.1" unit="kg" /> </div> </template> <style> .scale-box { width: 100%; height: 120px; } </style>2. 局部导入组件
如果您不需要全局注册，可以直接进行局部按名导入：
<script setup lang="ts"> import { ref } from 'vue' import { MeasuringScale } from 'vue3-measuring-scale' import 'vue3-measuring-scale/dist/style.css' const height = ref(175) </script> <template> <div class="scale-box"> <MeasuringScale v-model="height" :min="100" :max="220" :step="1" unit="cm" :vertical="true" /> </div> </template> <style> .scale-box { width: 200px; height: 400px; } </style>🔧 API 参考
属性 (Props)
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
v-model(modelValue) | number | 必填 | 双向绑定的当前选中数值。 |
min | number | 0 | 尺子允许的最小值。 |
max | number | 100 | 尺子允许的最大值。 |
step | number | 1 | 刻度步长精度（如0.1表示一位小数精度，5表示以 5 递增）。支持浮点数。 |
ruleWidth | number | 8 | 最小相邻刻度线之间的像素间距（单位：px）。增大此值会使尺子显得更稀疏，反之更紧凑。 |
unit | string | "" | 数值显示区域的单位后缀（例如"kg"、"cm"、"℃"）。 |
vertical | boolean | false | 是否为垂直刻度尺布局。false为水平朝向，true为垂直朝向。 |
theme | 'light' | 'dark' | 'light' | 内置配色主题。light（浅色，适用于白底）和dark（深色，适用于暗色背景）。 |
pointerColor | string | '#3b82f6' | 中间红色准星指示针的自定义颜色（支持各种 Hex/RGB/HSL 色值）。 |
lineColor | string | "" | 刻度线和水平基线的自定义颜色。为空时会自动根据主题明暗色计算半透明色。 |
textColor | string | "" | 大刻度文本标注的自定义颜色。为空时会自动根据主题计算文字色。 |
showValue | boolean | true | 是否在标尺内部上方/侧边自动渲染当前的数值预览框。 |
tickInterval | number | 10 | 大刻度线间隔。表示每隔多少个step步长，绘制一条带有数值标签的的长刻度线。 |
labelFormatter | (val: number) => string | undefined | 自定义刻度线下的数值文本格式化函数。可以用来将数值转换成月份、定制文字等。 |
事件 (Events)
| 事件名 | 参数 | 说明 |
|---|---|---|
update:modelValue | value: number | 触发双向绑定更新。在滑动过程中，值会随着当前滑过的步长位置以高精度输出。 |
change | value: number | 用户释放手指且刻度尺执行完磁吸回弹对齐动画并最终静止后触发。参数为最终落点的数值。 |
🛠️ 本地开发与测试
如果您希望下载该项目并在本地进行二开调试：
克隆项目并安装依赖
pnpminstall启动本地交互式验证页面
pnpmrun dev启动后可在浏览器中打开
http://localhost:5173/访问可视化测试大屏。在此大屏中，您可以调节控制面板中的各项属性并实时预览。打包生产包
pnpmrun build该命令会利用 Vite 编译出库的 ES 及 UMD 代码，并自动通过
vue-tsc运行类型检查，于dist/生成所有模块的.d.ts类型声明文件。
📄 授权协议
MIT License
