TDesign Uniapp Slider 滑动选择器组件完全指南:从引入配置到源码原理

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

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 方法重新测量即可。

登录后查看全文
tdesign-miniprogram