Slider 滑块

17:06

说明

在 start–end 范围内拖动选择数值，v-model 双向绑定，step 控制步长，min / max 进一步限制可拖动区间。可选显示当前数值（show-value，位置由 value-position 控制）与两端边界值（show-edge-value）；滑块按钮提供默认插槽可自定义滑块内容。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

v-model 绑定当前值，拖动滑块或点击滑块条改变值。

查看源码

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

<script setup lang="uts">
const value = ref<number>(30);
</script>

自定义范围

通过 start/end 设置范围，step 设置步长，这里为 -50 到 50 步长 5。

查看源码

<template>
    <ux-slider v-model="value" :start="-50" :end="50" :step="5" />
</template>

<script setup lang="uts">
const value = ref<number>(0);
</script>

显示数值

show-value=true 时在滑块上方显示当前数值。

查看源码

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

<script setup lang="uts">
const value = ref<number>(50);
</script>

数值位置与边界数值

value-position 可将当前数值放到滑块下方；show-edge-value=true 在两端显示 start/end 边界值。这些文本不占流内高度，组件会自动预留上下空间，不会压到相邻元素。

查看源码

<template>
    <ux-slider v-model="value1" :show-value="true" value-position="bottom" />
    <ux-slider v-model="value2" custom-class="slider-gap" :show-value="true" :show-edge-value="true" edge-value-position="top" />
</template>

<script setup lang="uts">
const value1 = ref<number>(35);
const value2 = ref<number>(70);
</script>

<style lang="scss">
.slider-gap {
    margin-top: 20px;
}
</style>

自定义颜色

通过 active-color 和 inactive-color 自定义进度条颜色。

查看源码

<template>
    <ux-slider v-model="value" active-color="#fa3534" inactive-color="#e4e7ed" />
</template>

<script setup lang="uts">
const value = ref<number>(40);
</script>

禁用状态

disabled=true 时滑块不可拖动。

查看源码

<template>
    <ux-slider v-model="value" :disabled="true" />
</template>

<script setup lang="uts">
const value = ref<number>(60);
</script>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
modelValue	当前值（默认0）	number | string	0	-
start	整体范围起点值（默认0）	number | string	0	-
end	整体范围终点值（默认50）	number | string	100	-
min	有效拖动最小值（默认0）	number | string	0	-
max	有效拖动最大值（默认50）	number | string	100	-
step	步长（默认1）	number | string	1	-
blockWidth	滑块宽度，高等于宽，单位px（默认15）	number | string	15	-
height	滑块条高度，单位px（默认3）	number | string	3	-
activeColor	进度条激活部分颜色	string	''	-
inactiveColor	进度条背景颜色	string	''	-
blockColor	滑块颜色	string	''	-
blockStyle	滑块自定义样式	UTSJSONObject	-	-
disabled	是否禁用滑块（默认false）	boolean	false	-
showValue	是否显示当前数值（默认false）	boolean	false	-
valuePosition	数值显示位置，top-上方，bottom-下方（默认top）	string	'top'	-
showEdgeValue	是否显示起始和结束数值（默认false）	boolean	false	-
edgeValuePosition	起始和结束数值显示位置（默认top）	string	'top'	-
validateState	是否处于校验错误状态（由父级 form-item 联动，默认false）	boolean	false	-

Events

事件名	说明	回调参数	版本
start	开始滑动时触发	-	-
moving	滑动过程中持续触发	-	-
end	滑动结束时触发	-	-

Slots

插槽名	说明	版本
default	自定义滑块按钮内容（默认渲染白色圆形滑块）	-

注意事项

• 有效拖动区间由 min / max 与 start / end 共同决定：min / max 会被夹取到 start / end 之内。
• 最终值按 step 四舍五入对齐（Math.round(v / step) * step）；step 非正数时按 1 处理。
• show-value / show-edge-value 的文本为绝对定位、不占流内高度，组件会在根节点上下自动预留空间（各 26px），避免压到相邻元素。
• 拖动过程中持续发出 update:modelValue 与 moving，start 在开始滑动时发出，end 在滑动结束时发出。
• 滑块按钮为正方形（宽高同取 block-width），支持默认插槽自定义滑块内容。
• 组件可注入 ux-form-item 上下文，拖动结束与点击轨道后触发其校验；validate-state 时轨道加红色描边。