TDesign 小程序 Slider 滑动选择器完全指南:引入、配置、事件与样式定制
TDesign 小程序 Slider 滑动选择器完全指南:引入、配置、事件与样式定制
本文是 TDesign 小程序组件库中 Slider 滑动选择器的技术实战指南。Slider 用于在横轴(或纵轴)上选择数值、区间与档位,覆盖单游标、双游标(区间)、带数值文本、带刻度、禁用、胶囊风格与垂直方向等全部形态。阅读本文后,你将掌握组件的引入方式、全部 Props 与 Events 的语义、External Classes 与 CSS Variables 的定制方法,并理解组件底层基于 touch 事件的取值换算逻辑,能够直接在业务中落地使用。
组件概述与渲染支持
t-slider 是 TDesign 小程序组件库中负责“滑动选择”的表单类组件,其官方描述为“用于选择横轴上的数值、区间、档位”,在组件库中的分类归属为 form(表单)类。当前仓库中该组件的实现位于 packages/components/slider,核心文件包括:
- slider.ts:组件逻辑实现,基于
SuperComponent与@wxComponent()装饰器构建; - props.ts:全部属性声明;
- type.ts:
TdSliderProps与SliderValue的 TypeScript 类型定义; - slider.wxml:模板结构;
- slider.less:样式实现;
- _example:官方演示页面,包含
base、range、label、step、disabled、capsule、vertical、max八个场景。
渲染框架支持情况为 WebView。仓库同时提供了 Skyline 渲染器下的演示示例 packages/components/slider/_example/skyline/slider.json(配置了 "renderer": "skyline"),但其 WXML 注释中说明在 Skyline 模式下 e.changedTouches 返回的坐标为 0,因此垂直方向演示在 Skyline 下被暂时屏蔽,垂直滑块形态建议在 WebView 渲染下使用。
组件引入
Slider 组件的引入遵循 TDesign 小程序组件库的统一规范,分为全局引入与局部引入两种方式。
全局引入
在 miniprogram 根目录下的 app.json 中配置 usingComponents:
{
"usingComponents": {
"t-slider": "tdesign-miniprogram/slider/slider"
}
}
局部引入
在需要使用的页面或组件的 index.json 中配置,例如官方演示页面 packages/components/slider/_example/base/index.json:
{
"component": true,
"usingComponents": {
"t-slider": "tdesign-miniprogram/slider/slider"
}
}
配置完成后,即可在 WXML 中使用 <t-slider />。若想快速预览全部效果,可导入开发者工具后依次执行 npm i、构建 npm 包、勾选“将 JS 编译成 ES5”三个步骤。
组件类型与演示场景
单游标滑块(base)
最简单的用法,示例见 packages/components/slider/_example/base/index.wxml:
<view class="wrapper">
<t-slider default-value="{{23}}" step="{{0.1}}" bind:change="handleChange" />
</view>
对应 JS(packages/components/slider/_example/base/index.js):
Component({
methods: {
handleChange(e) {
console.log(e.detail.value);
},
},
});
bind:change 回调中,e.detail.value 即为当前滑块值。
双游标滑块(range)
设置 range 属性后组件渲染为双游标区间选择器,value/default-value 需传入 <a href="https://link.gitcode.com/i/2bddfcd826081866cd6dba6d60eab00e" target="_blank">最小值, 最大值] 形式的数组。示例见 [packages/components/slider/_example/range/index.wxml:
<view class="wrapper">
<t-slider range defaultValue="{{[35, 65]}}" bind:dragstart="onDragstart" bind:dragend="onDragend" />
</view>
起始非零的滑动选择器(max)
通过 min/max/step/marks 组合可以实现非零起点且带刻度的滑块,示例见 packages/components/slider/_example/max/index.wxml:
<view class="wrapper">
<t-slider
defaultValue="{{30}}"
min="{{20}}"
max="{{100}}"
step="{{20}}"
marks="{{marks}}"
bind:change="handleChange"
></t-slider>
</view>
带数值滑动选择器(label)
label 属性支持 true、false、字符串模板(如 ${value}%)或函数四种形态。示例见 packages/components/slider/_example/label/index.wxml:
<t-slider value="{{value}}" label="${value}%" bind:change="handleChange"></t-slider>
<t-slider show-extreme-value label="{{label}}" default-value="{{ [40, 60] }}" range />
当 label 为函数时,参数 value 标识滑块值,参数 position 用于标识位置(start 表示范围滑块起始值,end 表示范围滑块终点值,min/max 表示边界值)。对应 JS(packages/components/slider/_example/label/index.js):
Component({
data: {
value: 35,
label(value, position) {
const symbols = { min: '%', max: '%', start: '%', end: '%' };
return `${value}${symbols[position]}`;
},
},
methods: {
handleChange(e) {
this.setData({ value: e.detail.value });
},
},
});
带刻度滑动选择器(step)
marks 支持数组(如 <a href="https://link.gitcode.com/i/a0af449ce61d10d64aad063e4b4cde90" target="_blank">0, 10, 40, 200],仅渲染刻度点)或对象(如 { 5: '5¥', 10: '10%' },同时渲染刻度文字)。示例见 [packages/components/slider/_example/step/index.wxml:
<t-slider defaultValue="{{60}}" marks="{{marks}}" step="{{20}}" bind:change="handleChange" />
<t-slider range defaultValue="{{ [20, 60] }}" marks="{{marks}}" step="{{20}}" />
对应 marks 数据(packages/components/slider/_example/step/index.js):
data: {
marks: {
0: '0',
20: '20',
40: '40',
60: '60',
80: '80',
100: '100',
},
}
从 slider.ts 的 handleMark 实现可以看到:当 marks 为数组时,每个元素被换算为 { val, left } 结构(left 通过 valueToPosition 换算为像素位置);当 marks 为对象时,key 作为刻度值、value 作为刻度文字,分别进入 scaleArray 与 scaleTextArray,最终在 slider.wxml 中按 isScale 状态渲染刻度点与说明文字。
组件状态与特殊形态
禁用状态(disabled)
设置 disabled 后组件不可交互,游标与滑道颜色切换为禁用色。示例见 packages/components/slider/_example/disabled/index.wxml:
<t-slider value="{{35}}" disabled />
<t-slider show-extreme-value label="${value}%" value="{{ [40, 60] }}" range disabled />
<t-slider range value="{{ [20, 60] }}" marks="{{marks}}" step="{{20}}" disabled />
源码中所有触摸处理(onSingleLineTap、onLineTap、onTouchMoveLeft、onTouchMoveRight)在入口处都做了 if (disabled) return 拦截,因此在禁用状态下点击与拖动均不会触发 change。
胶囊型滑块(capsule)
theme="capsule" 将滑块渲染为胶囊风格(圆角滑道、可自定义宽度高度),支持与 range、label、marks、vertical 任意组合。示例见 packages/components/slider/_example/capsule/index.wxml:
<t-slider defaultValue="{{30}}" theme="capsule" />
<t-slider defaultValue="{{ [40, 60] }}" range theme="capsule" />
<t-slider defaultValue="{{ [40, 60] }}" range label="${value}%" theme="capsule" />
<t-slider defaultValue="{{60}}" marks="{{marks}}" step="{{20}}" theme="capsule" />
<t-slider defaultValue="{{ [20, 80] }}" range marks="{{marks}}" step="{{20}}" theme="capsule" />
垂直状态(vertical)
设置 vertical 后滑块沿垂直方向渲染。渲染垂直滑块时默认高度为 400rpx,可通过修改 CSS 变量 --td-slider-bar-height 自定义高度(该 CSS 变量在 slider.less 的 --vertical 作用域中被覆盖为 400rpx)。示例见 packages/components/slider/_example/vertical/index.wxml:
<t-slider vertical value="{{singlevalue}}" label="${value}%" bind:change="handleSingleChange" />
<t-slider vertical range defaultValue="{{ [20, 60] }}" marks="{{marks}}" step="{{20}}" />
<t-slider vertical value="{{capsuleValue}}" label="${value}%" theme="capsule" bind:change="handleCapsuleChange" />
<t-slider vertical defaultValue="{{ [20, 80] }}" range marks="{{marks}}" step="{{20}}" theme="capsule" />
垂直模式下,组件在 getPagePosition 中改用 pageY 计算位置,并在 slider.ts 的 injectPageScroll 中注入页面 onPageScroll,以便在页面滚动时校正游标位置(仅 range && vertical 同时为真时生效)。
FAQ:hidden 包裹后的重新渲染
当 slider 外层使用 hidden 包裹时,组件初始化时 #sliderLine 的布局尺寸为 0,会导致滑道无法正确渲染。此时需要在 hidden = false(即组件可见)后重新调用组件的 init 方法。该场景同样适用于 t-popup、t-dialog 等容器内使用 slider 的情况。
<t-slider id="slider" />
const $slider = this.selectComponent('#slider');
$slider.init();
从源码看,init()(slider.ts)通过 getRect(this, '#sliderLine') 异步获取滑道节点尺寸,据此计算 maxRange(可滑动范围)、initialLeft、initialRight 等关键数据,并通过内部 bus.emit('initial') 触发刻度与线条的渲染;handlePropsChange 在 maxRange === 0 时也会等待 init() 完成后才写入 _value。这就是“先初始化、后渲染数据”的底层原因。
API 详解
Slider Props
以下属性定义来源于 props.ts,类型定义可参考 type.ts:
| 名称 | 类型 | 默认值 | 描述 | 必传 |
|---|---|---|---|---|
| style | Object | - | 样式 | N |
| custom-style | Object | - | 样式,一般用于开启虚拟化组件节点场景 | N |
| colors | Array | [] | 已废弃。颜色,[已选择, 未选择]。TS 类型:Array<string> |
N |
| disabled | Boolean | undefined | 是否禁用组件 | N |
| disabled-color | Array | [] | 已废弃。禁用状态滑动条的颜色,[已选, 未选]。TS 类型:Array<string> |
N |
| label | String / Boolean / Function | false | 滑块当前值文本。值为 true 显示默认文案;值为 false 不显示滑块当前值文本;值为 ${value}% 表示组件会根据占位符渲染文案;值类型为函数时,参数 value 标识滑块值,参数 position=start 表示范围滑块的起始值,参数 position=end 表示范围滑块的终点值。TS 类型:string | boolean |
N |
| marks | Object / Array | {} | 刻度标记,示例:[0, 10, 40, 200] 或者 { 5: '5¥', 10: '10%' }。TS 类型:Record<number, string> | Array<number> |
N |
| max | Number | 100 | 滑块范围最大值 | N |
| min | Number | 0 | 滑块范围最小值 | N |
| range | Boolean | false | 双游标滑块 | N |
| show-extreme-value | Boolean | false | 是否显示边界值 | N |
| step | Number | 1 | 步长 | N |
| theme | String | default | 滑块风格。可选项:default/capsule(theme 属性自 0.30.0 版本起支持) |
N |
| value | Number / Array | 0 | 滑块值。TS 类型:SliderValue,type SliderValue = number | Array<number> |
N |
| default-value | Number / Array | undefined | 滑块值。非受控属性。TS 类型:SliderValue |
N |
| vertical | Boolean | false | 是否是垂直的滑块(渲染垂直滑块时,默认高度为 400rpx,可通过修改 --td-slider-bar-height 来自定义高度) |
N |
几个关键属性的底层行为说明:
value与default-value的受控/非受控差异:slider.ts中通过controlledProps = <a href="https://link.gitcode.com/i/b3e54311ee20eacf05481f2bc6181025" target="_blank">{ key: 'value', event: 'change' }]声明value为受控属性;default-value仅作为初始化值。演示页面中受控用法需要像 [label 示例 那样在handleChange中setData({ value: e.detail.value })回写。- 数值越界与步长校准:
tool.ts的trimSingleValue将越界值钳制到<a href="https://link.gitcode.com/i/6b4e430296e46f3313abdf213f23f992" target="_blank">min, max]区间,trimValue还会保证双游标下value[0] <= value[1](否则自动交换);stepValue按step取整,且针对小数步长(如 0.1)依据小数位精度进行toFixed处理,避免浮点误差。测试用例value is over limited([packages/components/slider/test/index.test.js)验证了value = -1时被钳制为 0、value = 101时被钳制为 100 的行为。 label函数签名:函数形式为label(value, position),其中position取值包括min、max、start、end,getLabelByValue(slider.ts)在字符串模板未包含${value}占位符时会console.warn提示格式错误。
Slider Events
| 名称 | 参数 | 描述 |
|---|---|---|
| change | (value: SliderValue) |
滑块值变化时触发 |
| dragend | (value: SliderValue, e: TouchEvent) |
结束拖动时触发 |
| dragstart | (e: TouchEvent) |
开始拖动时触发 |
事件触发链路:onTouchStart 触发 dragstart(并在 data.identifier 中记录触点标识以区分左右游标);拖动与点击过程经 triggerValue 内部去重(preval 对比)后通过 _trigger('change', { value }) 触发 change;onTouchEnd 触发 dragend。测试用例 :base 验证了点击滑道后 change 事件触发、值更新为对应位置的取整值,以及 disabled 后点击不再改变值的完整流程。
Slider External Classes
| 类名 | 描述 |
|---|---|
| t-class | 根节点样式类 |
| t-class-bar | 滑道底部样式类 |
| t-class-bar-active | 滑道激活态样式类 |
| t-class-bar-disabled | 滑道禁用态样式类 |
| t-class-cursor | 游标样式类 |
这些外部样式类在 slider.ts 的 externalClasses 中声明,并在 slider.wxml 的对应节点上挂载,用于从外部覆盖组件内部样式。
CSS Variables
组件在 slider.less 中提供了下列 CSS 变量,可通过自定义样式覆盖变量值来定制外观:
| 名称 | 默认值 | 描述 |
|---|---|---|
| --td-slider-active-color | @brand-color | 滑道激活态颜色 |
| --td-slider-bar-height | 8rpx | 滑道高度(垂直模式下默认为 400rpx) |
| --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 | 文本颜色 |
以 --td-slider-dot-size 为例,其在 less 中被读取为 @slider-dot-size 并作用于 .t-slider__dot 的宽高;--td-slider-bar-height 同时影响滑道高度与刻度点尺寸。需要说明的是,CSS 变量名称中的 heihgt/line-heihgt 为官方命名中保留的拼写,使用时请按上表原样书写。
源码层面的取值原理
Slider 的核心是将触摸坐标换算为数值,理解这一过程有助于排查定位异常:
init()通过getRect('#sliderLine')拿到滑道的left/right/top/bottom,计算出可滑动范围maxRange与初始边界initialLeft/initialRight(胶囊主题下会扣除游标半宽与 6rpx 边框);- 单游标点击/拖动时,
getSingleChangeValue将pageX - initialLeft - offset除以maxRange再乘以(max - min),得到目标值后经stepValue步长校准并钳制边界; - 双游标点击滑道时,
onLineTap比较点击位置与左右游标的距离,决定移动哪个游标;拖动时onTouchMoveLeft/onTouchMoveRight分别换算左右游标的值; - 垂直模式下统一改用
pageY,并在范围+垂直组合下注入页面滚动监听以校正位置。
此外,组件内置了无障碍支持:模板中游标节点带有 aria-role="slider"、aria-valuenow、aria-valuetext 等属性,并在值变化时通过 toggleA11yTips 短暂开启 aria-live 播报,供读屏软件使用。
小结
TDesign 小程序 Slider 是一个功能完整的表单控件,支持单/双游标、刻度、数值标签、胶囊主题、垂直方向、禁用与无障碍播报等能力。将其引入业务只需在 app.json 或页面 index.json 中声明 t-slider 即可;配合 change/dragstart/dragend 事件与受控 value 可实现任意业务交互;而 External Classes 与 CSS Variables 提供了从节点级到变量级的灵活定制手段。若遇到 hidden 容器下渲染异常,记得在可见时调用组件的 init() 方法重新计算滑道尺寸。