vue3-measuring-scale

v0.1.0

Published

3 months ago

`vue3-measuring-scale` 是一款为 **Vue 3** 开发的高性能、高定制性、交互优雅的 **Canvas 刻度尺（标尺选择器）组件库**。它专为移动端及大屏可视化表单场景设计，可用于身高、体重、温度、年龄等任何连续或离散数值的直观滑动选择。

0High
0Medium
0Low

_htwoo

vue3-measuring-scale

vue3-measuring-scale 是一款为 Vue 3 开发的高性能、高定制性、交互优雅的 Canvas 刻度尺（标尺选择器）组件库。它专为移动端及大屏可视化表单场景设计，可用于身高、体重、温度、年龄等任何连续或离散数值的直观滑动选择。

✨ 特性

⚡ Canvas 渲染：核心部分完全由 HTML Canvas 绘制，避免大量 DOM 渲染，即使大范围数值交互也极为流畅。
📱 高清显示支持：自动适配高分屏（Retina），智能检测并应用 window.devicePixelRatio 缩放，避免线条模糊。
🏃 物理惯性滑动：内置甩拽减速运动学模型（Momentum Physics），支持随手势甩动滑行。
🧲 自动磁吸对齐：当惯性滑动结束或拖拽释放时，会自动回弹并磁吸对齐到最接近的有效步长（step）数值。
⚙️ 高精度防噪：内置高精度过滤截断机制，彻底根治 JavaScript 浮点数在运算时产生的类似 62.30000000000004 等浮点噪点。
📐 双向布局：支持 水平（Horizontal） 与 垂直（Vertical） 两套布局朝向。
🌓 内置主题与高定制性：支持白昼（light）/ 深色（dark）两套内置配色系统，支持动态调整指针颜色、刻度间距、大刻度间隔，并支持完全自定义的标签文字格式化函数。
🔄 支持滚轮/触控板：支持鼠标滚轮与笔记本双指滚动操作。

📦 安装

使用您喜爱的包管理器安装组件包：

# npm
npm install vue3-measuring-scale

# yarn
yarn add vue3-measuring-scale

# pnpm
pnpm add vue3-measuring-scale

🚀 快速上手

1. 全局注册使用（作为插件）

在 main.ts / main.js 中注册插件：

import { createApp } from 'vue'
import App from './App.vue'

// 导入组件包与样式文件
import Vue3MeasuringScale from 'vue3-measuring-scale'
import 'vue3-measuring-scale/dist/style.css'

const app = 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)

事件 (Events)

| 事件名 | 参数 | 说明 | | :--- | :--- | :--- | | update:modelValue | value: number | 触发双向绑定更新。在滑动过程中，值会随着当前滑过的步长位置以高精度输出。 | | change | value: number | 用户释放手指且刻度尺执行完磁吸回弹对齐动画并最终静止后触发。参数为最终落点的数值。 |

🛠️ 本地开发与测试

如果您希望下载该项目并在本地进行二开调试：

克隆项目并安装依赖
```
pnpm install
```
启动本地交互式验证页面
```
pnpm run dev
```
启动后可在浏览器中打开 http://localhost:5173/ 访问可视化测试大屏。在此大屏中，您可以调节控制面板中的各项属性并实时预览。
打包生产包
```
pnpm run build
```
该命令会利用 Vite 编译出库的 ES 及 UMD 代码，并自动通过 vue-tsc 运行类型检查，于 dist/ 生成所有模块的 .d.ts 类型声明文件。

📄 授权协议

MIT License

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

vue3-measuring-scale

✨ 特性

📦 安装

🚀 快速上手

1. 全局注册使用（作为插件）

2. 局部导入组件

🔧 API 参考

属性 (Props)

事件 (Events)

🛠️ 本地开发与测试

📄 授权协议