miniprogram-demo 中的 TDesign Slider 滑动选择器组件:配置、源码原理与实战

原创2026-10-14 17:03:031,917 阅读
文章标签:示例工程小程序前端

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):

  1. 通过 getRect(this, '#sliderLine')(common/utils.js 中基于 createSelectorQuery().boundingClientRect 的 Promise 封装)测量滑道;
  2. 根据 vertical 取 bottom - top 或 right - left 得到 maxRange;
  3. 胶囊主题下对 maxRange 与端点做游标半径补偿;
  4. 写入 __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)不被其他逻辑覆盖。
登录后查看全文
miniprogram-demo