@tanzhenxing/zx-slider v1.0.3

zx-slider 滑动选择器组件

基于 uni-app 原生 slider 组件的增强版本，提供更多自定义功能和更好的用户体验。

特性

• ✅ 完全兼容 uni-app 官方 slider 组件
• ✅ 支持 Vue 3 Composition API
• ✅ 支持双向绑定 (v-model)
• ✅ 多种值显示位置（左侧、右侧、底部、原生）
• ✅ 自定义格式化函数和配置
• ✅ 刻度显示和标签
• ✅ 范围值显示
• ✅ 标签和单位支持
• ✅ 实时更新选项
• ✅ 完整的属性验证
• ✅ TypeScript 友好
• ✅ 兼容旧版本属性

安装使用

<template>
  <zx-slider v-model="value" :show-value="true" />
</template>

<script setup>
import { ref } from 'vue'
import zxSlider from '@/components/zx-slider/zx-slider.vue'

const value = ref(50)
</script>

属性说明

基础属性

样式属性

显示属性

刻度属性

格式化属性

行为属性

事件说明

使用示例

基础用法

<template>
  <zx-slider v-model="value" />
</template>

<script setup>
import { ref } from 'vue'
const value = ref(30)
</script>

显示当前值

<template>
  <!-- 原生显示 -->
  <zx-slider v-model="value" :show-value="true" />
  
  <!-- 右侧显示 -->
  <zx-slider v-model="value" :show-value="true" value-position="right" />
  
  <!-- 底部显示 -->
  <zx-slider v-model="value" :show-value="true" value-position="bottom" />
</template>

设置范围和步长

<template>
  <zx-slider 
    v-model="value"
    :min="10"
    :max="90"
    :step="5"
    :show-value="true"
    :show-range="true"
  />
</template>

自定义颜色

<template>
  <zx-slider 
    v-model="value"
    active-color="#ff5722"
    background-color="#ffebee"
    block-color="#e91e63"
    :block-size="24"
  />
</template>

带标签和单位

<template>
  <zx-slider 
    v-model="volume"
    :show-label="true"
    label="音量"
    unit="%"
    :show-value="true"
  />
</template>

自定义格式化

<template>
  <!-- 使用格式化函数 -->
  <zx-slider 
    v-model="percent"
    :formatter="percentFormatter"
    :show-value="true"
  />
  
  <!-- 使用格式化配置 -->
  <zx-slider 
    v-model="price"
    :formatter="{ prefix: '¥', suffix: '.00', decimals: 0 }"
    :show-value="true"
  />
</template>

<script setup>
function percentFormatter(value) {
  return `${value}%`
}
</script>

显示刻度

<template>
  <zx-slider 
    v-model="value"
    :show-ticks="true"
    :show-tick-labels="true"
    :tick-count="5"
    :show-value="true"
  />
</template>

小数精度

<template>
  <zx-slider 
    v-model="decimal"
    :min="0"
    :max="10"
    :step="0.1"
    :precision="1"
    :show-value="true"
  />
</template>

实时更新

<template>
  <zx-slider 
    v-model="value"
    :update-on-changing="true"
    @changing="onChanging"
    :show-value="true"
  />
</template>

<script setup>
function onChanging(e) {
  console.log('实时值：', e.value, e.formattedValue)
}
</script>

高级示例

温度控制器

<template>
  <zx-slider 
    v-model="temperature"
    :min="-10"
    :max="50"
    :step="1"
    :show-label="true"
    label="室内温度"
    :show-value="true"
    :show-range="true"
    :show-ticks="true"
    :show-tick-labels="true"
    :tick-count="6"
    active-color="#ff6b35"
    :formatter="temperatureFormatter"
  />
</template>

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

const temperature = ref(22)

function temperatureFormatter(value) {
  if (value < 0) return `${value}°C (冷)`
  if (value < 10) return `${value}°C (凉)`
  if (value < 25) return `${value}°C (适宜)`
  if (value < 35) return `${value}°C (温暖)`
  return `${value}°C (炎热)`
}
</script>

组件方法

通过 ref 可以访问组件的方法：

<template>
  <zx-slider ref="sliderRef" v-model="value" />
</template>

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

const sliderRef = ref()
const value = ref(50)

// 获取格式化后的值
const formatted = sliderRef.value?.formatValue(value.value)

// 验证并修正值
const validated = sliderRef.value?.validateValue(75)

// 获取当前值
const current = sliderRef.value?.currentValue
</script>

兼容性说明

• 支持 uni-app 全平台
• 兼容 Vue 3 Composition API
• 向下兼容旧版本属性命名
• 支持 HBuilderX 4.23+ 的 HarmonyOS 编译

注意事项

1. step 值必须大于 0
2. blockSize 范围为 12-28
3. 使用 backgroundColor 替代 inactiveColor（保持兼容）
4. 格式化函数的优先级高于其他格式化配置
5. 在拖动过程中，默认不更新 modelValue，可通过 updateOnChanging 开启

更新日志

v1.0.0

• 基础功能实现
• 支持 Vue 3 Composition API
• 完整的属性验证
• 多种显示模式
• 自定义格式化
• 刻度显示功能