TDesign Uniapp Slider 滑动选择器组件完全指南:从引入配置到源码原理
TDesign Uniapp Slider 滑动选择器组件完全指南:从引入配置到源码原理
本指南以 TDesign Uniapp 组件库中的 Slider(滑动选择器)组件为主题,系统讲解其在 @tdesign/uniapp 中的引入方式、全部 Props/Events 配置、单游标/双游标/带刻度/胶囊/垂直等形态的实战用法,并结合 packages/uniapp-components/slider 目录下的源码(slider.vue、props.ts、tool.js、slider.less 等)剖析受控值同步、边界值裁剪、label 占位符渲染等底层实现。读完本文,你将能在 Uniapp 项目中快速集成并深度定制 <t-slider />,也能在遇到渲染异常时定位到根因。
一、组件定位与使用场景
Slider 用于"选择横轴上的数值、区间、档位",是典型的表单类(spline: form)交互组件。它在 tdesign-miniprogram 仓库中同时存在两套实现:
- 小程序版:位于 packages/components/slider,对应 npm 包
tdesign-miniprogram; - Uniapp 版:位于 packages/uniapp-components/slider,对应 npm 包
@tdesign/uniapp,采用 Vue 单文件组件(.vue)实现,支持 Vue2 / Vue3 及 H5、微信小程序、支付宝小程序、App 等多端。
本文以 Uniapp 版为准展开。
二、引入组件
推荐使用 easycom 模式引入组件,配置后无需手动 import 即可直接在模板中使用 <t-slider />。easycom 完整配置步骤见 Uniapp 快速开始,核心是在 pages.json 中添加如下配置:
{
"easycom": {
"custom": {
"^t-(.*)": "@tdesign/uniapp/$1/$1.vue"
}
}
}
配置完成后,模板中直接书写即可:
<t-slider :default-value="23" :step="0.1" @change="handleChange" />
如需手动引入,在 <script> 中导入组件并注册:
import TSlider from '@tdesign/uniapp/slider/slider.vue';
export default {
components: {
TSlider,
},
// ...
};
注意:
@tdesign/uniapp只提供按需导入方式,不支持全量导入(全量导入在小程序端存在兼容性问题),详见 快速开始 中的说明。
实际组件的演示样例位于 packages/uniapp-components/slider/_example,其中 base、range、label、step、disabled、capsule、vertical、max 各场景均提供可直接运行的 index.vue。
三、组件类型与基础用法
1. 单游标滑块
最基本形态,默认 range=false、value 为数字:
<view class="wrapper">
<t-slider :default-value="23" :step="0.1" @change="handleChange" />
</view>
methods: {
handleChange(e) {
console.log(e.value);
},
},
示例参考 base/index.vue。step 支持小数(如 0.1),组件内部会按步长对滑动结果取整。
2. 双游标滑块(区间选择)
通过 range 属性开启,value 变为长度为 2 的数组 [start, end]:
<t-slider range :default-value="[35, 65]" @dragstart="onDragstart" @dragend="onDragend" />
示例参考 range/index.vue。
3. 带数值滑动选择器
通过 label 属性在游标上方显示当前值,支持 Boolean / String / Function 三种形态(详见下文 API 章节):
<t-slider :value="value" label="${value}" @change="handleChange" />
<t-slider show-extreme-value label="${value}" :default-value="[40, 60]" range />
data() {
return { value: 35 };
},
methods: {
handleChange(e) {
this.value = e.value;
},
},
示例参考 label/index.vue。当 label="${value}" 时,组件会把占位符 ${value} 替换为当前滑块值渲染。
4. 带刻度滑动选择器
通过 marks 属性渲染刻度标记,配合 step 使用:
<t-slider :default-value="60" :marks="marks" :step="20" @change="handleChange" />
<t-slider range :default-value="[20, 60]" :marks="marks" :step="20" />
data() {
return {
marks: {
0: '0',
20: '20',
40: '40',
60: '60',
80: '80',
100: '100',
},
};
},
示例参考 step/index.vue。marks 支持数组形式(如 [0, 10, 40, 200])与对象形式(如 { 5: '5¥', 10: '10%' },键为数值、值为刻度描述文本)两种写法。
5. 自定义取值范围
通过 min / max 调整滑块范围,step 控制档位,刻度也随之对齐:
<t-slider :default-value="30" :min="20" :max="100" :step="20" :marks="marks" @change="handleChange" />
示例参考 max/index.vue。
四、组件状态:禁用
设置 disabled 后滑块不可交互,游标与滑道均呈现禁用态配色:
<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 />
示例参考 disabled/index.vue。从源码看,禁用态下所有触摸事件(onSingleLineTap、onTouchMoveLeft、onTouchMoveRight、onLineTap 等)都会在入口处直接 return,确保游标不可拖动、滑道不可点击,见 slider.vue 中相关事件处理逻辑。
五、特殊样式:胶囊型滑块
通过 theme="capsule" 将滑块切换为胶囊形态,滑道更宽、游标更大:
<t-slider :default-value="30" theme="capsule" />
<t-slider :default-value="[40, 60]" range theme="capsule" />
<t-slider :default-value="[40, 60]" range label="${value}" theme="capsule" />
<t-slider :default-value="60" :marks="marks" :step="20" theme="capsule" />
<t-slider :default-value="[20, 80]" range :marks="marks" :step="20" theme="capsule" />
示例参考 capsule/index.vue。胶囊态在样式层由 slider.less 中的 &--capsule 系列规则实现(滑道高度 48rpx、激活线高度 36rpx、带 6rpx 边框),在交互层则对应 valueToPosition 中 halfBlock = blockSize / 2 的偏移补偿逻辑。
六、垂直状态
vertical 属性将滑块旋转为垂直方向,默认高度为 400rpx,可通过覆盖 CSS 变量 --td-slider-bar-height 自定义高度:
<!-- 单游标垂直滑块 -->
<t-slider vertical :value="singlevalue" label="${singlevalue}" @change="handleSingleChange" />
<!-- 带刻度的双游标垂直滑块 -->
<t-slider vertical range :default-value="[20, 60]" :marks="marks" :step="20" />
<!-- 胶囊型垂直滑块 -->
<t-slider vertical :value="capsuleValue" label="${capsuleValue}" theme="capsule" @change="handleCapsuleChange" />
<!-- 带刻度的胶囊型垂直滑块 -->
<t-slider vertical :default-value="[20, 80]" range :marks="marks" :step="20" theme="capsule" />
示例参考 vertical/index.vue。垂直态的样式由 slider.less 中的 .@{slider}--vertical 规则实现:--td-slider-bar-height: 400rpx 为默认高度,滑道宽度改为由 --td-slider-bar-width 控制。交互层面,slider.vue 的 getPagePosition 会在垂直模式下取触摸点的 clientY 而非 clientX 来计算位置。
七、API 详解
Slider Props
下表完整继承自组件文档,并结合 props.ts 与 type.ts 补充说明:
| 名称 | 类型 | 默认值 | 描述 | 必传 |
|---|---|---|---|---|
| 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 | N |
| value | Number / Array | 0 | 滑块值。支持语法糖 v-model:value。TS 类型:SliderValue,type SliderValue = number | Array<number> |
N |
| default-value | Number / Array | 0 | 滑块值。非受控属性。TS 类型:SliderValue |
N |
| vertical | Boolean | false | 是否是垂直的滑块(渲染垂直滑块时,默认高度为 400rpx,可通过修改 --td-slider-bar-height 来自定义高度) |
N |
补充说明:
label占位符渲染机制:当label为字符串且包含${value}时,组件会将其替换为当前值。从 computed.js 的getValue(label, value)实现可见:匹配${value}正则后执行label.replace(REGEXP, value);当label === 'true'(即模板中直接传布尔true的场景)时直接返回当前值作为默认文案。label为函数时,slider.vue 中的getLabelByValue会以label(value, position)的形式调用,其中position取start或end分别对应范围滑块的起点与终点。- 受控与非受控:
value为受控属性(支持v-model:value语法糖),default-value为非受控属性(仅初始化时生效)。组件在mounted阶段通过coalesce(value, defaultValue, 0)决定初始值,见 slider.vue。 marks的解析:在 slider.vue 的handleMark中,数组形式的marks被转换为刻度位置列表(scaleArray),对象形式则以Object.keys(marks)作为刻度数值、以键值为刻度描述文本(scaleTextArray),同时开启isScale渲染刻度。
Slider Events
| 名称 | 参数 | 描述 |
|---|---|---|
| change | (context: { value: SliderValue }) |
滑块值变化时触发 |
| dragend | (context: { value: SliderValue, e: TouchEvent }) |
结束拖动时触发 |
| dragstart | (context: { e: TouchEvent }) |
开始拖动时触发 |
事件触发链路说明:拖动过程中 onTouchMoveLeft / onTouchMoveRight / onSingleLineTap / onLineTap 等处理函数最终都会调用 triggerValue,由其完成值裁剪后触发 change 事件并同步受控值;onTouchStart 触发 dragstart,onTouchEnd 触发 dragend(携带 { e, value: this.innerValue }),实现细节见 slider.vue。
Slider External Classes
外部样式类用于从组件外部局部覆写样式:
| 类名 | 描述 |
|---|---|
| t-class | 根节点样式类 |
| t-class-bar | 滑道底部样式类 |
| t-class-bar-active | 滑道激活态样式类 |
| t-class-bar-disabled | 滑道禁用态样式类 |
| t-class-cursor | 游标样式类 |
这些外部类在 slider.vue 的 externalClasses 配置中声明,并由 instantiationDecorator.js 的 getExternalClasses 统一转换为组件 props 注入。
CSS Variables
组件提供下列 CSS 变量,可用于自定义样式(完整列表继承自组件文档,并可在 slider.less 中找到对应的 var(--td-xxx, 默认值) 取值声明):
| 名称 | 默认值 | 描述 |
|---|---|---|
| --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 | - |
注意:文档原文中的 --td-slider-capsule-bar-heihgt、--td-slider-capsule-line-heihgt 为项目既有拼写(heihgt),实际生效变量名以此为准。
八、源码原理深析
1. 受控值同步与 v-model 支持
组件通过 uniComponent 包装(见 instantiationDecorator.js 的 uniComponent),并声明了受控属性:
controlledProps: [
{
key: 'value',
event: 'change',
},
],
这意味着:当 change 事件触发时,组件内部 _trigger 会同时 $emit('change', ...) 与 $emit('update:value', ...),前者供事件监听、后者供 v-model:value 语法糖回写。开发者既可以使用 v-model:value 双向绑定,也可以监听 @change 后手动更新数据(示例 label/index.vue 即采用后者)。
2. 边界值与步长裁剪
所有来自拖动或点击的新值都会经 tool.js 处理:
trimSingleValue将单个值钳制在[min, max]区间内;trimValue在range模式下对数组两个元素分别裁剪,若出现value[0] > value[1]的交叉情况则自动交换为[value[1], value[0]];- 步长对齐由 slider.vue 的
stepValue完成:Math.round(value / step) * step,并通过toFixed处理小数精度,支持step为小数(如0.1)。
3. 点击滑道 vs 拖动游标
组件在滑道上同时监听点击与触摸事件:onSingleLineTap(单游标)与 onLineTap(双游标)处理"点击滑道跳转";onTouchStart/Move/End 处理"拖动游标"。双游标模式下 onLineTap 会通过 getRect 分别测量左右游标与点击点的距离,哪个更近就移动哪个游标。需要理解的是,滑块值最终由"触摸点相对滑道起点的偏移量 ÷ 滑道总长 × 值域跨度"换算得到,水平与垂直模式分别使用 clientX / clientY(见 getPagePosition)。
九、FAQ:hidden 包裹导致渲染异常
当 slider 外层使用 hidden 包裹时,组件初始化的尺寸测量(init 会通过 getRect 获取 #sliderLine 的宽高)会拿到 0 值,导致滑道、游标位置计算错误而无法正常渲染。此时需要在 hidden = false 之后,重新调用组件的 init 方法(在 t-popup / t-dialog 中同理):
<t-slider id="slider" />
const $slider = this.selectComponent('#slider');
$slider.init();
从源码看,init() 方法(slider.vue)会执行 getInitialInfo() 完成 #sliderLine 的布局测量、计算 maxRange 与 initialLeft / initialRight,再通过内部 bus 触发 initial 事件重绘刻度与激活线。由于 __inited 标记在首次初始化后为 true,需注意在隐藏场景下组件尺寸尚未就绪时的时序问题;文档建议的"重新调用 init"正是为此准备的补救手段。
十、小结
TDesign Uniapp 的 Slider 组件以一套 .vue 实现覆盖了单游标、双游标区间、数值气泡、刻度档位、胶囊主题、垂直方向、禁用态等完整形态,并通过 v-model:value 受控机制与 change 事件保持了数据流的一致性。结合本指南的 Props / Events / 外部样式类 / CSS 变量四个维度的 API 说明,以及示例目录 packages/uniapp-components/slider/_example 中的可运行样例,即可在业务中快速实现"数值选择、区间筛选、档位切换"等典型交互;若遇到 hidden 或弹层容器内的渲染问题,优先调用组件 init 方法重新测量即可。