miniprogram-demo 中的 TDesign Slider 滑动选择器组件:配置、源码原理与实战
miniprogram-demo 中的 TDesign Slider 滑动选择器组件:配置、源码原理与实战
本指南以 slider 组件官方 README 为核心骨架,深入讲解 TDesign 滑动选择器(t-slider)在微信小程序 miniprogram-demo 中的引入方式、全部 Props / Events / 样式类 / CSS 变量,并结合组件源码剖析其数值换算、刻度渲染、双游标与垂直滑块的底层实现。读完本文,你将能在自己的小程序页面中快速接入单游标、双游标、带刻度、胶囊型与垂直方向滑块,并能通过 init() 方法解决隐藏场景下的渲染问题。
一、组件概述
TDesign 滑动选择器用于在横轴上选择数值、区间或档位,是数据类(spline: data)基础组件之一。在 miniprogram-demo 中,该组件被打包在 packageChatTool 分包下,真实业务场景用于"创建活动"页面中限制参与人数的档位选择(见 activity_create/index.wxml):
<t-slider value="{{number}}" min="1" max="20" label="${number}" bind:change="onNumberChange" />
页面在 onNumberChange 中通过 e.detail.value 回写 number,再把它作为 wx.selectGroupMembers 的 maxSelectCount 上限(见 activity_create/index.js)。这是理解该组件"受控更新 + change 事件回传"机制的最佳实战范例。
二、组件引入
在 miniprogram 根目录下的 app.json 中配置即全局引入;在需要引入的页面或组件的 index.json 中配置即局部引入。官方推荐局部引入:
{
"usingComponents": {
"t-slider": "tdesign-miniprogram/slider/slider"
}
}
在 miniprogram-demo 中,实际使用的是相对路径形式(见 activity_create/index.json):
{
"usingComponents": {
"t-slider": "../../components/tdesign-miniprogram/slider/slider"
}
}
两种写法指向同一份组件实现。组件自身的 slider.json 声明了 "component": true 与 "styleIsolation": "apply-shared"(slider.json),即允许页面样式渗入组件,方便配合外部样式类微调。
若希望在开发者工具中预览官方 demo,需保持工具打开,导入后依次执行:
npm i> 构建 npm 包 > 勾选"将 JS 编译成 ES5"。
三、代码演示:四种组件类型
1. 单游标滑块(base)
默认形态,一个游标沿滑道移动,value 为单个数值。渲染时组件通过 setSingleBarWidth 按"当前值在 min, max] 区间内的占比 × 可用轨道长度"计算激活条宽度(见 [slider.js)。
2. 双游标滑块(range)
设置 range="{{true}}" 后切换为区间选择。此时 value 必须为 <a href="https://link.gitcode.com/i/e50ed84b7194de373ea3697259e2dea9" target="_blank">start, end] 形式的数组;若传入非法值,[tool.js 中的 trimValue 会自动对两端做 min/max 裁剪并保证 value[0] <= value[1],防止区间倒置。
3. 带数值滑动选择器(label)
label 控制游标上方数值文案的展示方式:
- 值为
true:显示默认数值文案; - 值为
false:不显示(默认); - 值为
${value}%这类含${value}占位符的字符串:组件按占位符渲染当前值; - 值为函数:参数
value为滑块值,双滑块时position=start表示起始值、position=end表示终点值。
占位符的替换由 WXS 模块完成:slider.wxs 用正则 <a href="https://link.gitcode.com/i/fc178b998a874a70d1051b494e5d17d2" target="_blank">$][{value}] 匹配 ${value} 并替换为实际值(见 [slider.wxs)。活动创建页中 label="${number}" 即让游标上方实时显示当前参与人数。
4. 带刻度滑动选择器(step)
marks 用于渲染刻度,支持两种格式(见 props.js 与 slider.js 中的 handleMark):
marks: [0, 10, 40, 200] // 数组:仅标记位置
marks: { 5: '5¥', 10: '10%' } // 对象:位置 + 刻度文案
handleMark 将每个刻度按 item / max * maxRange 换算成像素位置(胶囊主题额外加上半个游标尺寸作为 margin),同时根据 marks 类型设置 isScale、scaleArray 与 scaleTextArray。单滑块下,当前值 _value >= item.val 的刻度标记为激活态(t-slider__scale-item--active)。
四、组件状态与特殊样式
1. 禁用状态(disabled)
disabled="{{true}}" 后所有手势(点击滑道、拖动游标)在 onSingleLineTap / onLineTap / onTouchMoveLeft / onTouchMoveRight 入口处直接 return(见 slider.js)。样式上,滑道、激活条、游标与数值文案会切换到禁用色(--td-slider-disabled-color、--td-slider-dot-disabled-* 等),且 WXML 中通过 _.cls(..., <a href="https://link.gitcode.com/i/0c6994fc3cfb64dd76af44e1ff6e0d65" target="_blank">['disabled', disabled]]) 给根节点挂上 t-slider--disabled 类(见 [slider.wxml)。
2. 胶囊型滑块(capsule)
theme="capsule" 启用胶囊风格。源码对胶囊主题做了多处特殊补偿:
- 初始化时
maxRange减去blockSize + 6,并对initialLeft/initialRight减去半个游标,以抵消 6rpx 边框与游标半径(见 slider.js); - 单滑块宽度计算、点击与拖动偏移量同样加上
blockSize相关补偿(setSingleBarWidth、getSingleChangeValue、onLineTap、onTouchMoveLeft等); - 样式上,胶囊滑道高 48rpx、激活条高 36rpx,刻度渲染为竖条形态(见 slider.wxss)。
3. 垂直滑块(vertical)
vertical="{{true}}" 渲染垂直方向滑块,默认高度 400rpx,可通过 --td-slider-bar-height 自定义。垂直模式下,组件在 attached 阶段通过 injectPageScroll 劫持当前页面的 onPageScroll,记录 scrollTop,用于拖动过程中把页面滚动偏移叠加到游标定位上(见 slider.js)。坐标换算统一走 getPagePosition:垂直取 pageY、水平取 pageX(见 slider.js)。WXSS 中 .t-slider--vertical 会把轨道、游标、边界值与刻度全部切换到垂直布局(见 slider.wxss)。
五、Slider Props 完整参数表
| 名称 | 类型 | 默认值 | 描述 | 必传 |
|---|---|---|---|---|
| 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 | 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 | 0.30.0 起支持。滑块风格,可选项:default / capsule |
N |
| value | Number / Array | 0 | 滑块值。TS 类型:SliderValue(number | Array<number>) |
N |
| default-value | Number / Array | undefined | 滑块值(非受控属性)。TS 类型:SliderValue |
N |
| vertical | Boolean | false | 是否为垂直滑块(垂直默认高度 400rpx,可用 --td-slider-bar-height 调整) |
N |
对照 props.js,min/max/step/range/vertical/theme 等均在组件属性中注册,其中 theme 默认值为 'default'。value 为受控属性:源码中 controlledProps = <a href="https://link.gitcode.com/i/37ffb29841756b71bf841193cb925d7b" target="_blank">{ key: 'value', event: 'change' }](见 [slider.js),当父组件通过 bind:change 收到新值并回写 value 时,observers.value 触发 handlePropsChange 完成同步(见 slider.js)。
步长与小数处理
stepValue 是数值吸附的核心(见 slider.js):
stepValue(value) {
const { step, min, max } = this.properties;
const decimal = String(step).indexOf('.') > -1
? String(step).length - String(step).indexOf('.') - 1
: 0;
const closestStep = trimSingleValue(
Number((Math.round(value / Number(step)) * Number(step)).toFixed(decimal)),
Number(min), Number(max)
);
return closestStep;
}
它先按 Math.round(value / step) * step 吸附到最近的步进值,再根据 step 的小数位数用 toFixed 修正浮点误差,最后经 trimSingleValue 裁剪进 [min, max]。因此即使 step 为 0.5、min 为 0,也不会出现 0.30000000000000004 这类精度问题。
六、Slider Events
| 名称 | 参数 | 描述 |
|---|---|---|
| change | (value: SliderValue) |
滑块值变化时触发 |
| dragend | (value: SliderValue, e: TouchEvent) |
结束拖动时触发 |
| dragstart | (e: TouchEvent) |
开始拖动时触发 |
事件触发链路:triggerValue 中先比较 this.preval === value 做去重,再通过 this._trigger('change', { value: trimValue(value, this.properties) }) 抛出事件(见 slider.js)。dragstart 在 onTouchStart 触发,dragend 在 onTouchEnd 触发并携带当前 _value(见 slider.js)。
七、Slider External Classes 外部样式类
| 类名 | 描述 |
|---|---|
| t-class | 根节点样式类 |
| t-class-bar | 滑道底部样式类 |
| t-class-bar-active | 滑道激活态样式类 |
| t-class-bar-disabled | 滑道禁用态样式类 |
| t-class-cursor | 游标样式类 |
这五个外部样式类在源码中注册于 externalClasses 数组(见 slider.js),WXML 中分别挂到根节点、滑道({{prefix}}-class-bar)、激活条({{prefix}}-class-bar-active)与游标({{prefix}}-class-cursor)上,页面可通过 t-class-bar="my-bar" 这类写法局部覆写样式。
八、FAQ:hidden 包裹下的重新渲染
当 slider 外层使用 hidden 包裹时,隐藏期间组件的滑道布局信息(maxRange、initialLeft、initialRight)测量不到;因此 hidden = false 后需要重新调用 init 方法才能正常渲染。t-popup / t-dialog 等场景同理。
<t-slider id="slider" />
const $slider = this.selectComponent('#slider');
$slider.init();
init 的内部实现(见 slider.js):
- 通过
getRect(this, '#sliderLine')(common/utils.js 中基于createSelectorQuery().boundingClientRect的 Promise 封装)测量滑道; - 根据
vertical取bottom - top或right - left得到maxRange; - 胶囊主题下对
maxRange与端点做游标半径补偿; - 写入
__inited = true并通过this.bus.emit('initial')触发等待中的renderLine与handleMark(observers中用this.bus.on('initial', ...)注册了回调)。
组件还会在 attached 时先调用一次 init(见 slider.js),init 内部通过 __inited 保证幂等——所以对已经初始化过的实例重复调用不会产生副作用。
九、CSS Variables 自定义变量
组件提供以下 CSS 变量用于定制外观(默认值见 slider.wxss 中各 var(--td-slider-*) 的回退值):
| 名称 | 默认值 | 描述 |
|---|---|---|
| --td-slider-active-color | @brand-color | 激活态颜色 |
| --td-slider-bar-height | 8rpx | 滑道高度;vertical 为 true 时默认 400rpx |
| --td-slider-bar-width | 8rpx | 滑道宽度;vertical 为 true 时有效 |
| --td-slider-capsule-bar-color | @bg-color-component | 胶囊滑道背景色 |
| --td-slider-capsule-bar-heihgt | 48rpx | 胶囊滑道高度 |
| --td-slider-capsule-bar-width | 48rpx | 胶囊滑道宽度;vertical 为 true 时有效 |
| --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 | 数值文案颜色 |
源码在 wxss 中同时提供了三级回退链,例如激活色
var(--td-slider-active-color, var(--td-brand-color, var(--td-primary-color-7, #0052d9))),即优先使用业务覆盖的--td-slider-active-color,其次回退到 TDesign 全局品牌色变量,最后兜底为#0052d9(见 slider.wxss)。
十、源码结构速览
组件实现位于 miniprogram/packageChatTool/components/tdesign-miniprogram/slider/ 目录,核心文件:
- slider.js:组件主体,包含初始化、坐标换算、步进吸附、刻度渲染与事件派发;
- slider.wxml:单游标 / 双游标两套模板,含无障碍(aria)语义;
- slider.wxss:全部样式与 CSS 变量定义;
- slider.wxs:
${value}占位符替换逻辑; - props.js / props.d.ts:属性注册与类型声明;
- tool.js:
trimSingleValue/trimValue数值裁剪工具; - slider.json:组件配置(
styleIsolation: apply-shared)。
组件名 t-slider 由 common/config.js 中的 prefix = "t" 拼接而成,同时作为 classPrefix 注入模板类名(如 t-slider__bar、t-slider__dot)。无障碍方面,游标节点带有 aria-role="slider"、aria-valuemax/min/now/text 等属性,数值变化时还会通过 toggleA11yTips 短暂显示 2 秒的屏幕阅读器提示(见 slider.js)。
十一、常见问题排查
- 滑块无法拖动:先确认未设置
disabled;其次检查页面是否存在hidden包裹,如有则参考第八节在显示后调用$slider.init()。 - 数值不吸附档位:确认
step为期望步长,且min与max的差值是step的整数倍;小数步长由stepValue的toFixed逻辑兜底。 - 双游标区间倒置:组件内置
trimValue会自动交换为[小值, 大值],父组件只需按e.detail.value回写即可。 - 垂直滑块高度不符预期:通过
--td-slider-bar-height覆盖默认 400rpx,注意同时保证页面滚动劫持(injectPageScroll)不被其他逻辑覆盖。