TDesign Uniapp Slider 滑动选择器实战指南:Props、事件与样式定制全解析
TDesign Uniapp Slider 滑动选择器实战指南:Props、事件与样式定制全解析
TDesign Uniapp 组件库中的 Slider(滑动选择器)用于在横轴(或纵轴)上选择数值、区间与档位,覆盖单游标、双游标(range)、带数值、带刻度、胶囊型与垂直方向等多种形态。本文以仓库中 Slider 官方文档 为骨架,结合 slider.vue、props.ts、slider.less 等源码,系统讲解组件的引入方式、全部配置项、事件回调、外部样式类、CSS 变量及底层实现原理,帮助你直接在 Uniapp 项目中开箱即用并完成深度定制。
组件引入与使用前提
该组件属于 TDesign Uniapp 组件库(npm 包名 @tdesign/uniapp)。推荐使用 easycom 自动导入模式,配置后无需手动 import 即可在模板中直接使用 <t-slider />,完整安装与配置步骤见快速开始。
{
"easycom": {
"custom": {
"^t-(.*)": "@tdesign/uniapp/$1/$1.vue"
}
}
}
如需手动引入,在 <script> 中按需导入(组件库只提供按需导入方式,不支持全量导入):
import TSlider from '@tdesign/uniapp/slider/slider.vue';
注册后即可在模板中使用,示例见仓库中的 base 示例:
<view class="wrapper">
<t-slider :default-value="23" :step="0.1" @change="handleChange" />
</view>
组件形态总览
Slider 通过属性组合可以覆盖以下六种典型形态,对应仓库 _example 目录下的独立示例:
| 形态 | 关键属性 | 参考示例 |
|---|---|---|
| 单游标滑块 | 默认 | base/index.vue |
| 双游标滑块(区间) | range |
range/index.vue |
| 带数值滑动选择器 | label="${value}" |
label/index.vue |
| 带刻度滑动选择器 | marks + step |
step/index.vue |
| 胶囊型滑块 | theme="capsule" |
capsule/index.vue |
| 垂直方向滑块 | vertical |
vertical/index.vue |
Slider Props 完整说明
组件全部属性定义位于 props.ts,类型定义位于 type.ts。下表逐项说明(默认值与类型均与源码一致):
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| custom-style | Object | - | 自定义样式 |
| colors | Array | [] | 已废弃。颜色,[已选择, 未选择]。TS 类型:Array<string> |
| disabled | Boolean | undefined | 是否禁用组件 |
| disabled-color | Array | [] | 已废弃。禁用状态滑动条的颜色,[已选, 未选]。TS 类型:Array<string> |
| label | String / Boolean / Function | false | 滑块当前值文本。true 显示默认文案;false 不显示;${value}% 表示按占位符渲染文案;函数类型时参数 value 为滑块值,position=start 表示范围滑块起始值,position=end 表示终点值。TS 类型:string | boolean |
| marks | Object / Array | {} | 刻度标记,示例:[0, 10, 40, 200] 或 { 5: '5¥', 10: '10%' }。TS 类型:Record<number, string> | Array<number> |
| max | Number | 100 | 滑块范围最大值 |
| min | Number | 0 | 滑块范围最小值 |
| range | Boolean | false | 双游标滑块(区间选择) |
| show-extreme-value | Boolean | false | 是否显示边界值 |
| step | Number | 1 | 步长 |
| theme | String | default | 滑块风格,可选项:default / capsule |
| value | Number / Array | 0 | 滑块值,支持 v-model:value 语法糖。TS 类型:SliderValue,即 number | Array<number>,详细类型定义 |
| default-value | Number / Array | 0 | 滑块值,非受控属性。TS 类型:SliderValue,详细类型定义 |
| vertical | Boolean | false | 是否是垂直滑块(默认高度 400rpx,可通过修改 --td-slider-bar-height 自定义高度) |
其中几个易混淆点需要特别说明:
theme枚举校验:源码 props.ts 中通过validator仅接受default与capsule两个取值,传入其他值会被拒绝,这一点与文档“options: default/capsule”完全对应。value与default-value的取舍:value为受控属性(配合@change更新),default-value为非受控属性(组件内部自行维护)。源码mounted阶段通过coalesce(value, defaultValue, 0)决定初始值,参见 slider.vue。marks两种写法:数组<a href="https://link.gitcode.com/i/debc1d7cb39cc57fd7bc6cf2e4506e75" target="_blank">0, 10, 40, 200]仅渲染刻度点;对象{ 5: '5¥', 10: '10%' }还会在刻度下方渲染对应文本。源码 [handleMark 分别对Array与Object两种形态做了位置计算与文案映射。
受控模式与 v-model 绑定
在受控模式下,value 通过 change 事件回传并驱动组件更新,标签页 label 示例 展示了标准写法:
<t-slider :value="value" label="${value}" @change="handleChange" />
methods: {
handleChange(e) {
this.value = e.value;
},
},
组件内部通过 uniComponent 的 controlledProps: <a href="https://link.gitcode.com/i/4386a69edc9f16ed1d15548ed2d3bbc0" target="_blank">{ key: 'value', event: 'change' }] 声明受控契约(见 [slider.vue),并配合 triggerValue 在值变化时抛出 change 事件;若处于非受控模式(使用 default-value),组件会自行更新内部值,参见 triggerValue 实现。
Slider Events 事件说明
组件暴露三个事件,对应源码中的 onChange、onDragend、onDragstart 声明(props.ts):
| 名称 | 参数 | 说明 |
|---|---|---|
| change | (context: { value: SliderValue }) |
滑块值变化时触发 |
| dragend | (context: { value: SliderValue, e: TouchEvent }) |
结束拖动时触发 |
| dragstart | (context: { e: TouchEvent }) |
开始拖动时触发 |
dragstart在touchstart时触发(onTouchStart),dragend在touchend时触发并携带最终值与触摸事件(onTouchEnd)。- 事件参数中的
value会经过trimValue校正:超出<a href="https://link.gitcode.com/i/8e302cab7432e5b0757ad1c3b3ee491f" target="_blank">min, max]的值会被钳制,双游标场景下若起止值倒置会自动交换,保证value[0] <= value[1],见 [tool.js。
双游标事件的监听示例见 range 示例:
<t-slider range :default-value="[35, 65]" @dragstart="onDragstart" @dragend="onDragend" />
滑块外部样式类(External Classes)
组件通过 externalClasses 暴露了五个样式类,用于从外部精准覆盖局部样式(声明见 slider.vue):
| 类名 | 说明 |
|---|---|
| t-class | 根节点样式类 |
| t-class-bar | 滑道底部样式类 |
| t-class-bar-active | 滑道激活态样式类 |
| t-class-bar-disabled | 滑道禁用态样式类 |
| t-class-cursor | 游标样式类 |
CSS 变量:无需改源码的深度定制
组件在 slider.less 中通过 CSS 变量驱动全部关键视觉参数,开发者可以在页面或组件层级覆盖这些变量实现主题定制:
| 变量名 | 默认值 | 说明 |
|---|---|---|
| --td-slider-active-color | @brand-color | 激活态(已选)颜色 |
| --td-slider-bar-height | 8rpx | 滑道高度 |
| --td-slider-bar-width | 8rpx | 滑道宽度(垂直场景) |
| --td-slider-capsule-bar-color | @bg-color-component | 胶囊型滑道底色 |
| --td-slider-capsule-bar-heihgt | 48rpx | 胶囊型滑道高度 |
| --td-slider-capsule-bar-width | 48rpx | 胶囊型滑道宽度(垂直场景) |
| --td-slider-capsule-line-heihgt | 36rpx | 胶囊型内部激活线高度 |
| --td-slider-default-color | @bg-color-component | 滑道默认(未选)颜色 |
| --td-slider-disabled-color | @brand-color-disabled | 禁用态激活线颜色 |
| --td-slider-disabled-text-color | @text-color-disabled | 禁用态文字颜色 |
| --td-slider-dot-bg-color | #fff | 游标背景色 |
| --td-slider-dot-color | @component-border | 游标边框色 |
| --td-slider-dot-disabled-bg-color | #fff | 禁用态游标背景色 |
| --td-slider-dot-disabled-border-color | #f3f3f3 | 禁用态游标边框色 |
| --td-slider-dot-size | 40rpx | 游标尺寸 |
| --td-slider-text-color | @text-color-primary | 数值文字颜色 |
使用示例(以页面 <style> 覆盖为例):
.t-slider {
--td-slider-active-color: #0052d9;
--td-slider-dot-size: 48rpx;
}
特别注意垂直模式:样式源码在垂直类上设置了 --td-slider-bar-height: 400rpx(见 slider.less),因此垂直滑块默认高度为 400rpx,如需调整高度,直接覆盖 --td-slider-bar-height 即可,这也是文档中 vertical 属性说明的来源。
底层实现原理:值-位置换算与步长处理
从源码可以梳理出 Slider 的核心交互链路:
- 初始化测量:
init()与getInitialInfo()通过getRect(this, '#sliderLine')获取滑道实际尺寸,计算出可滑动范围maxRange与左右边界initialLeft/initialRight(slider.vue)。 - 位置转数值:
valueToPosition将值按(value - min) / (max - min) * maxRange线性映射为像素位置;convertPosToValue反向将触摸位置换算为值。 - 步长取整:
stepValue支持小数步长——先按小数点位数做四舍五入取整,再钳制到<a href="https://link.gitcode.com/i/d9d04e9d25d4e69cdffd6123b9cd9597" target="_blank">min, max]区间([slider.vue)。 - 点击与拖拽:点击滑道(
onLineTap/onSingleLineTap)会计算触摸点距左右游标的距离,就近移动游标;拖拽通过touchmove持续触发change。 - 无障碍支持:游标节点带有
aria-role="slider"、aria-valuemax/min/now等语义属性,并在值变化时短暂显示可屏幕阅读的提示(toggleA11yTips),便于无障碍读屏。
FAQ:hidden 包裹下的重新渲染
当 Slider 外层使用 hidden 包裹(例如置于 t-popup / t-dialog 中)时,组件挂载时滑道尺寸测量可能为 0,导致无法正常渲染。此时需要在 hidden = false 之后重新调用组件的 init 方法:
<t-slider id="slider" />
const $slider = this.selectComponent('#slider');
$slider.init();
该 init 方法正是上述初始化测量流程的公开入口,内部通过 __inited 标记防止重复初始化(见 slider.vue),因此在 hidden 场景下反复调用也是安全的。
小结
TDesign Uniapp 的 Slider 组件通过 14 个 Props、3 个事件、5 个外部样式类和 16 个 CSS 变量,覆盖了从基础单值选择到区间、刻度、胶囊、垂直等全部常见交互形态。理解 value/default-value 的受控与半受控差异、theme 枚举校验、trimValue 的值校正逻辑以及 CSS 变量的覆盖方式,即可在业务中快速落地并保持与 TDesign 设计规范一致。更多运行示例可参阅仓库 slider/_example 目录下的各类示例页面。