Slider 滑块 - Vant 4
Slider 滑块
介绍
滑动输入条，用于在给定的范围内选择一个值。
引入
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
js
import { createApp } from'vue'; import { Slider } from'vant'; const app = createApp(); app.use(Slider);🎯 代码演示
🎪 基础用法
通过 v-model 绑定滑块的当前值，用户可以拖动滑块来选择数值。
html
<template>
<van-slider v-model="value" @change="onChange" />
</template>
<script>
import { ref } from 'vue';
import { showToast } from 'vant';
export default {
setup() {
const value = ref(50);
const onChange = (value) => {
showToast(`当前值：${value}`);
};
return {
value,
onChange,
};
},
};
</script>🎭 双滑块
添加 range 属性就可以开启双滑块模式，确保 value 的值是一个数组，适用于选择范围的场景。
html
<template>
<van-slider v-model="value" range @change="onChange" />
</template>
<script>
import { ref } from 'vue';
import { showToast } from 'vant';
export default {
setup() {
// 双滑块模式时，值必须是数组
const value = ref([10, 50]);
const onChange = (value) => {
showToast(`当前范围：${value[0]} - ${value[1]}`);
};
return {
value,
onChange,
};
},
};
</script>📏 指定选择范围
通过 min 和 max 属性来设置滑块的最小值和最大值。
html
<template>
<van-slider v-model="value" :min="-50" :max="50" />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(10);
return {
value,
};
},
};
</script>🚫 禁用
通过 disabled 属性来禁用滑块，禁用状态下滑块不可拖动。
html
<template>
<van-slider v-model="value" disabled />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(50);
return {
value,
};
},
};
</script>📐 指定步长
通过 step 属性来设置滑块的步长，滑块只能选择步长的整数倍值。
html
<template>
<van-slider v-model="value" :step="10" />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(50);
return {
value,
};
},
};
</script>🎨 自定义样式
通过 bar-height 设置进度条高度，通过 active-color 设置进度条激活态颜色。
html
<template>
<van-slider
v-model="value"
:bar-height="4"
active-color="#ee0a24"
/>
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(50);
return {
value,
};
},
};
</script>🎛️ 自定义按钮
通过 button 插槽可以自定义滑块按钮的样式和内容。
html
<template>
<van-slider v-model="value">
<template #button>
<div class="custom-button">{{ value }}</div>
</template>
</van-slider>
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(50);
return {
value,
};
},
};
</script>
<style>
.custom-button {
width: 26px;
color: #fff;
font-size: 10px;
line-height: 18px;
text-align: center;
background-color: #ee0a24;
border-radius: 100px;
}
</style>📱 垂直方向
设置 vertical 属性后，滑块会垂直展示，且高度为 100% 父元素高度。
html
<template>
<div style="height: 150px; padding-left: 30px;">
<van-slider v-model="value" vertical @change="onChange" />
<van-slider
v-model="value2"
range
vertical
style="margin-left: 100px;"
@change="onChange"
/>
</div>
</template>
<script>
import { ref } from 'vue';
import { showToast } from 'vant';
export default {
setup() {
const value = ref(50);
const value2 = ref([10, 50]);
const onChange = (value) => {
showToast(`当前值：${value}`);
};
return {
value,
value2,
onChange,
};
},
};
</script>📋 API
🎛️ Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 📊 当前进度百分比，在双滑块模式下为数组格式 | *number | [number, number]* |
| max | 📈 最大值 | *number | string* |
| min | 📉 最小值 | *number | string* |
| step | 📐 步长 | *number | string* |
| bar-height | 📏 进度条高度，默认单位为 px | *number | string* |
| button-size | 📐 滑块按钮大小，默认单位为 px | *number | string* |
| active-color | 🎨 进度条激活态颜色 | string | #1989fa |
| inactive-color | 🎨 进度条非激活态颜色 | string | #e5e5e5 |
| range | 🎭 是否开启双滑块模式 | boolean | false |
| reverse | 🔄 是否将进度条反转 | boolean | false |
| disabled | 🚫 是否禁用滑块 | boolean | false |
| readonly | 👁️ 是否为只读状态，只读状态下无法修改滑块的值 | boolean | false |
| vertical | 📱 是否垂直展示 | boolean | false |
🎪 Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| update:model-value | 🔄 进度变化时实时触发 | value: number |
| change | ✅ 进度变化且结束拖动后触发 | value: number |
| drag-start | 🚀 开始拖动时触发 | event: TouchEvent |
| drag-end | 🏁 结束拖动时触发 | event: TouchEvent |
🎭 Slots
| 名称 | 说明 | 参数 |
|---|---|---|
| button | 🎛️ 自定义滑块按钮 | { value: number, dragging: boolean } |
| left-button | ⬅️ 自定义左侧滑块按钮（双滑块模式下） | { value: number, dragging: boolean, dragIndex?: number } |
| right-button | ➡️ 自定义右侧滑块按钮（双滑块模式下） | { value: number, dragging: boolean, dragIndex?: number } |
📘 类型定义
组件导出以下类型定义，方便在 TypeScript 项目中使用：
ts
import type { SliderProps } from 'vant';🎨 主题定制
🎭 样式变量
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-slider-active-background | var(--van-primary-color) | 🎨 激活状态背景色 |
| --van-slider-inactive-background | var(--van-gray-3) | 🎨 非激活状态背景色 |
| --van-slider-disabled-opacity | var(--van-disabled-opacity) | 👻 禁用状态透明度 |
| --van-slider-bar-height | 2px | 📏 进度条高度 |
| --van-slider-button-width | 24px | 📐 滑块按钮宽度 |
| --van-slider-button-height | 24px | 📐 滑块按钮高度 |
| --van-slider-button-radius | 50% | 🔘 滑块按钮圆角 |
| --van-slider-button-background | var(--van-white) | 🎨 滑块按钮背景色 |
| --van-slider-button-shadow | 0 1px 2px rgba(0, 0, 0, 0.5) | 🌟 滑块按钮阴影 |
📚 相关文档
🎛️ 表单组件
- Field 输入框 - 📝 用于输入文本信息
- Stepper 步进器 - 🔢 用于数值的精确调节
- Rate 评分 - ⭐ 用于评分选择
- Switch 开关 - 🔘 用于开关状态切换
📊 展示组件
- Progress 进度条 - 📈 用于展示进度状态
- Circle 环形进度条 - 🔄 用于展示环形进度
🎨 反馈组件
- Toast 轻提示 - 💬 用于操作反馈提示
- Dialog 弹出框 - 💬 用于重要信息确认
🔧 工具组件
- ConfigProvider 全局配置 - ⚙️ 用于全局配置定制