TDesign 小程序 Slider 滑动选择器完全指南:引入、配置、事件与样式定制

原创2026-10-14 11:19:331,861 阅读
文章标签:UI组件设计系统小程序前端移动开发跨平台

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 的核心是将触摸坐标换算为数值,理解这一过程有助于排查定位异常:

  1. init() 通过 getRect('#sliderLine') 拿到滑道的 left/right/top/bottom,计算出可滑动范围 maxRange 与初始边界 initialLeft/initialRight(胶囊主题下会扣除游标半宽与 6rpx 边框);
  2. 单游标点击/拖动时,getSingleChangeValue 将 pageX - initialLeft - offset 除以 maxRange 再乘以 (max - min),得到目标值后经 stepValue 步长校准并钳制边界;
  3. 双游标点击滑道时,onLineTap 比较点击位置与左右游标的距离,决定移动哪个游标;拖动时 onTouchMoveLeft/onTouchMoveRight 分别换算左右游标的值;
  4. 垂直模式下统一改用 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() 方法重新计算滑道尺寸。

登录后查看全文
tdesign-miniprogram