Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Slider 滑块
拖动滑块在一个数值区间里选一个值,或者选一段范围。适合音量、价格区间这类不需要精确输入的数值。
引入
import { NsSlider } from '@ns/ui'
基础用法
用 v-model 绑定一个数字,默认范围是 0 到 100。可以拖动按钮,也可以直接点轨道。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSlider } from '@ns/ui'
const value = ref(30)
</script>
<template>
<NsSlider v-model="value" />
<p style="margin-top: 12px">绑定值:{{ value }}</p>
</template>
范围(min、max)
min、max 是取值范围,默认 0 到 100,可以是负数或小数。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSlider } from '@ns/ui'
const temperature = ref(-5)
</script>
<template>
<NsSlider v-model="temperature" :min="-20" :max="40" show-input />
<p style="margin-top: 12px">温度:{{ temperature }}°C(-20 到 40)</p>
</template>
禁用
disabled 禁用后轨道变淡,不能拖动、点击,也不能用键盘操作;带输入框时输入框也一起禁用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSlider, NsSpace } from '@ns/ui'
const value = ref(40)
const range = ref<[number, number]>([20, 60])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSlider v-model="value" disabled />
<NsSlider v-model="range" range disabled />
<NsSlider v-model="value" show-input disabled />
</NsSpace>
</template>
步长和间断点
step 是每一步的大小,从 min 开始算:min 是 1、step 是 2 时,能取到的值是 1、3、5……。show-stops 在每一步的位置画一个小圆点。步长可以是小数。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSlider } from '@ns/ui'
const ten = ref(30)
const odd = ref(5)
const decimal = ref(0.3)
</script>
<template>
<div class="rows">
<span class="row-label">step 10,显示间断点:{{ ten }}</span>
<NsSlider v-model="ten" :step="10" show-stops />
<span class="row-label">1 到 11,step 2:{{ odd }}</span>
<NsSlider v-model="odd" :min="1" :max="11" :step="2" show-stops />
<span class="row-label">0 到 1,step 0.1:{{ decimal }}</span>
<NsSlider v-model="decimal" :min="0" :max="1" :step="0.1" />
</div>
</template>
<style scoped>
.rows {
display: grid;
grid-template-columns: 180px 1fr;
align-items: center;
gap: var(--ns-spacing-2) var(--ns-spacing-4);
}
.row-label {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
范围选择
加上 range 以后有两个按钮,绑定值是 [小值, 大值]。一个按钮可以拖过另一个,发出来的数组始终是从小到大排好的。拖动过程中每变一次触发 update:modelValue,松手(或点击轨道、按键、改输入框)后值有变化才触发一次 change。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSlider } from '@ns/ui'
const value = ref<[number, number]>([20, 60])
const changed = ref<number | [number, number]>()
const handleChange = (next: number | [number, number]) => {
changed.value = next
}
</script>
<template>
<NsSlider v-model="value" range @change="handleChange" />
<p style="margin-top: 12px">
拖动中(v-model):{{ value }},松手后(change):{{ changed ?? '还没有触发' }}
</p>
</template>
带输入框
show-input 在滑块右边显示数字输入框,和滑块互相联动。范围模式下是两个输入框,分别对应小值和大值。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSlider, NsSpace } from '@ns/ui'
const single = ref(30)
const range = ref<[number, number]>([20, 60])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSlider v-model="single" show-input />
<NsSlider v-model="range" range show-input />
</NsSpace>
</template>
不同尺寸
size 可选 large、default、small:整体高度 40、32、24px(和同尺寸的输入框一样高),滑块直径 20、16、12px,轨道粗 6、4、4px,标记文字 16、14、12px。show-input 的输入框用同一个尺寸。
不写 size 时按“NsFormItem > NsForm > NsConfigProvider”的顺序取,都没有时是 default。放进表单时,滑块和输入框的高度正好占满表单项的一行。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSlider } from '@ns/ui'
const value = ref(30)
const range = ref<[number, number]>([20, 60])
</script>
<template>
<div class="rows">
<span class="row-label">large</span>
<NsSlider v-model="value" size="large" show-input />
<span class="row-label">default</span>
<NsSlider v-model="value" show-input />
<span class="row-label">small</span>
<NsSlider v-model="value" size="small" show-input />
<span class="row-label">large</span>
<NsSlider v-model="range" size="large" range />
<span class="row-label">default</span>
<NsSlider v-model="range" range />
<span class="row-label">small</span>
<NsSlider v-model="range" size="small" range />
</div>
</template>
<style scoped>
.rows {
display: grid;
grid-template-columns: 56px 1fr;
align-items: center;
gap: var(--ns-spacing-2) var(--ns-spacing-3);
}
.row-label {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
标记
marks 是一个对象,键是数值,值是显示在轨道下面的文字。标记只是标注位置,不影响能取到哪些值;超出 min 到 max 范围的标记不显示(下面的 120 就不显示)。范围模式也能加标记。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSlider, NsSpace } from '@ns/ui'
const value = ref(30)
const range = ref<[number, number]>([8, 18])
const marks = {
0: '0°C',
37: '37°C',
100: '100°C',
120: '120°C'
}
const hours = { 0: '0 点', 6: '6 点', 12: '12 点', 18: '18 点', 24: '24 点' }
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSlider v-model="value" :marks="marks" />
<NsSlider v-model="range" range :min="0" :max="24" :marks="hours" show-stops :step="6" />
</NsSpace>
</template>
竖向
加上 vertical 变成竖向,从下往上是从小到大。height 是整个组件的高度,默认 200px。竖向时输入框在轨道下面,占用的高度算在 height 里。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSlider, NsSpace } from '@ns/ui'
const single = ref(30)
const range = ref<[number, number]>([20, 60])
const withInput = ref(30)
const small = ref(50)
</script>
<template>
<NsSpace wrap size="large">
<NsSlider v-model="single" vertical height="180px" />
<NsSlider v-model="range" vertical range height="180px" />
<NsSlider v-model="withInput" vertical show-input height="240px" />
<NsSlider v-model="small" vertical size="small" show-stops :step="10" height="180px" />
</NsSpace>
</template>
在表单里使用
放在 NsFormItem 里时,发出 change(一次操作结束、值有变化)时触发 change 规则,拖动过程中不校验。规则里的 min、max 对数字按数值比较;范围模式的值是数组,要写 validator。不需要校验时设 :validate-event="false"。
校验不通过时表单项下面显示错误信息,滑块本身的颜色不变。把下面的滑块拖到 18 以下看看:
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsSlider } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const model = reactive({ age: 20, budget: [100, 900] as [number, number] })
const rules: Record<string, FormRule[]> = {
age: [{ min: 18, message: '需要年满 18 岁', trigger: 'change' }],
budget: [
{
validator: (_rule, value) => {
const [low, high] = value as [number, number]
return high - low >= 200
},
message: '预算区间至少 200',
trigger: 'change'
}
]
}
</script>
<template>
<NsForm :model="model" :rules="rules" @submit.prevent>
<NsFormItem label="年龄" prop="age">
<NsSlider v-model="model.age" show-input />
</NsFormItem>
<NsFormItem label="预算" prop="budget">
<NsSlider v-model="model.budget" range :max="1000" :step="50" />
</NsFormItem>
</NsForm>
</template>
读取当前值
组件的 ref 上有 firstValue、secondValue,是两个按钮各自的值(sliderRef 是根元素)。范围模式下第一个按钮拖到第二个后面时,firstValue 会比 secondValue 大,发出的绑定值仍然是排好序的。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSlider } from '@ns/ui'
const sliderRef = ref<InstanceType<typeof NsSlider>>()
const range = ref<[number, number]>([20, 60])
const result = ref('')
const read = () => {
result.value = `firstValue:${sliderRef.value?.firstValue},secondValue:${sliderRef.value?.secondValue}`
}
</script>
<template>
<NsSlider ref="sliderRef" v-model="range" range />
<div style="margin-top: 12px">
<NsButton @click="read">读取两个按钮的值</NsButton>
</div>
<p style="margin-top: 12px">{{ result || '把左边的按钮拖到右边按钮的后面,再点按钮读取' }}</p>
</template>
键盘操作
用 Tab 键聚焦到按钮上以后(范围模式下两个按钮各自聚焦):
| 按键 | 作用 |
|---|---|
→ ↑ | 加一个步长 |
← ↓ | 减一个步长 |
Home | 跳到最小值 |
End | 跳到不超过最大值的最后一个步长点 |
再走一步就超出范围时停在原地,不会跳到边界值。用鼠标拖完以后焦点留在按钮上,可以接着用方向键微调。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | number | [number, number] | - | 绑定值,支持 v-model。范围模式下是 [小值, 大值]。没传时普通模式按 min 显示,范围模式按 [min, max] 显示 |
| min | number | 0 | 最小值 |
| max | number | 100 | 最大值 |
| step | number | 1 | 步长,从 min 开始算。小于等于 0 时按 1 处理 |
| disabled | boolean | false | 是否禁用 |
| showInput | boolean | false | 是否显示数字输入框 |
| showStops | boolean | false | 是否在每一步的位置显示间断点 |
| range | boolean | false | 是否是范围选择 |
| vertical | boolean | false | 是否竖向 |
| marks | Record<number, string> | - | 标记,键是数值,值是文字 |
| height | string | '200px' | 竖向时整个组件的高度,只在 vertical 时有用 |
| size | 'large' | 'default' | 'small' | - | 尺寸:整体高 40 / 32 / 24px,滑块 20 / 16 / 12px,轨道 6 / 4 / 4px,输入框跟着变。不写时跟随 FormItem、Form、ConfigProvider,都没有时是 default |
| validateEvent | boolean | true | 发出 change 时是否触发所在表单项的校验(拖动过程中不校验) |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: number | [number, number]) | 值变化时触发,拖动过程中每变一次就触发一次,v-model 用的就是它 |
| change | (value: number | [number, number]) | 一次操作结束、并且值有变化时触发:拖动松开、点击轨道、按键、改输入框 |
实例属性
通过组件的 ref 读取。
| 属性 | 类型 | 说明 |
|---|---|---|
| sliderRef | HTMLElement | undefined | 组件的根元素 |
| firstValue | number | 第一个按钮当前的值 |
| secondValue | number | 第二个按钮当前的值,只在范围模式下有意义。它不一定比 firstValue 大 |
类型
import type { SliderProps, SliderSize } from '@ns/ui'
/** 滑块的尺寸 */
type SliderSize = 'large' | 'default' | 'small'
interface SliderProps {
modelValue?: number | [number, number]
min?: number
max?: number
step?: number
disabled?: boolean
showInput?: boolean
showStops?: boolean
range?: boolean
vertical?: boolean
marks?: Record<number, string>
height?: string
/** 发出 change 时是否触发所在表单项的校验,默认 true */
validateEvent?: boolean
/** 尺寸。不写时跟随所在的 FormItem、Form、ConfigProvider,都没有时是 'default' */
size?: SliderSize
}
另外还导出了 SliderEmits。
注意事项
范围模式下绑定值要声明成元组:
ref<[number, number]>([20, 60])。写成ref([20, 60])会被推断成number[],类型检查通不过。要实时跟着拖动变化用
update:modelValue(或v-model);只关心最终结果、比如松手后才发请求,用change。绑定值超出
min到max时,显示会被限制在范围内,但组件不会主动改绑定值,要等用户操作后才发出新值。值的小数位数取
step、min、max三者里小数位最多的那个。max小于等于min时按钮停在起点,值固定按min处理,操作不会有效果。show-stops是每个步长画一个点,步长相对范围很小时点会很密(例如 0 到 100、步长 1 会画 99 个)。横向时组件宽度是 100%,要放在有宽度的容器里。带标记时组件下方会多留 20px(large 是 22px)给标记文字。
轨道两端各缩进半个滑块(large、default、small 分别是 10、8、6px,竖向是上下两端),拖到最小、最大值时滑块不会超出组件,放进表单不会贴住标签。
show-input的输入框跟着size变:默认尺寸下是 32px 高的default输入框(以前固定是 24px 高的small),要和以前一样矮,写size="small"。输入框用的是
NsInputNumber,不显示加减按钮,输入的值会被限制在范围内;范围模式下小值的输入框不能超过大值,大值的不能小于小值。组件没有插槽,按钮上也没有显示当前值的提示。
优化点
[ ] 支持格式化 Tooltip(拖动时在按钮上方显示当前值)
[ ] 支持自定义滑块
[ ] 支持范围拖拽模式(拖中间的色条整体平移)
[ ] 按键再走一步会超出范围时,直接停到边界值
[ ] 暴露
focus、blur方法