TDesign Uniapp Slider 滑动选择器实战指南:Props、事件与样式定制全解析

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

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 的核心交互链路:

  1. 初始化测量:init() 与 getInitialInfo() 通过 getRect(this, '#sliderLine') 获取滑道实际尺寸,计算出可滑动范围 maxRange 与左右边界 initialLeft/initialRight(slider.vue)。
  2. 位置转数值:valueToPosition 将值按 (value - min) / (max - min) * maxRange 线性映射为像素位置;convertPosToValue 反向将触摸位置换算为值。
  3. 步长取整:stepValue 支持小数步长——先按小数点位数做四舍五入取整,再钳制到 <a href="https://link.gitcode.com/i/d9d04e9d25d4e69cdffd6123b9cd9597" target="_blank">min, max] 区间([slider.vue)。
  4. 点击与拖拽:点击滑道(onLineTap/onSingleLineTap)会计算触摸点距左右游标的距离,就近移动游标;拖拽通过 touchmove 持续触发 change。
  5. 无障碍支持:游标节点带有 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 目录下的各类示例页面。

登录后查看全文
tdesign-miniprogram