xtf-slider

组件说明

xtf-slider 是数值与范围选择控件，适用于音量、预算、阈值和进度配置。支持单值/双滑块、垂直方向、刻度、气泡、格式化及主题预设。

---

基础用法

1. 单值双向绑定

<template><xtf-slider v-model="value" show-value unit="%" @change="changed" /></template>
<script>
export default {
  data() {
    return { value: 40 }
  },
  methods: {
    changed(value) {
      console.log('change', value)
    }
  }
}
</script>

2. 范围与刻度

<template>
  <xtf-slider
    v-model="range"
    range
    :step="5"
    :marks="marks"
    mark-clickable
    show-bubble
    @change="changed"
  />
</template>
<script>
export default {
  data() {
    return { range: [20, 80], marks: [0, 25, 50, 75, 100] }
  },
  methods: {
    changed(value) {
      console.log('range', value)
    }
  }
}
</script>

3. 垂直气泡

<template>
  <view style="height: 360rpx">
    <xtf-slider
      v-model="value"
      vertical
      theme="success"
      show-value
      show-bubble
      bubble-visible-mode="drag"
  /></view>
</template>
<script>
export default {
  data() {
    return { value: 60 }
  }
}
</script>

4. 格式化与视觉变体

<template>
  <xtf-slider
    v-model="temperature"
    :min="-10"
    :max="20"
    variant="glow"
    theme="info"
    title="冷藏温度"
    :format="format"
    :bubble-format="bubble"
    value-placement="both"
    show-bubble
  />
</template>
<script>
export default {
  data() {
    return { temperature: 4 }
  },
  methods: {
    format(v) {
      return v + ' °C'
    },
    bubble(v) {
      return v + '°'
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
modelValue	String | Number | Array	undefined	受控值	v-model
value	String | Number | Array	0	非 modelValue 模式的值	单向传值
range	Boolean	false	双滑块范围模式	值为 [min,max]
vertical	Boolean	false	垂直轨道	垂直控制
min / max / step	String | Number	0 / 100 / 1	数值边界与步长	数值约束
name	String	''	原生 slider 名称	表单
size	String	''	sm/md/lg 尺寸	尺寸控制
theme	String	'primary'	primary/success/warning/danger/info	主题色
variant	String	'default'	default/glass/glow/neon 样式	视觉变体
preset	String	''	内置预设	neon-pulse 等
disabled / readonly	Boolean	false / false	禁用或只读	状态控制
showValue / showBubble / showRange	Boolean	false / false / false	显示数值、气泡、两端标签	信息展示
bubbleVisibleMode	String	'auto'	auto/always/drag	气泡显示
title / desc / note / unit	String	''	标题、说明、备注和单位	文案
marks	Array	[]	刻度数组	见下表
markClickable	Boolean	false	点击刻度更新值	刻度交互
minLabel / maxLabel	String	''	两端标签	showRange
backgroundColor / trackColor	String	'' / ''	轨道颜色	颜色定制
activeColor / color / progressColor	String	''	进度颜色，按该优先级解析	颜色定制
progressGradient	String | Array	''	进度渐变	渐变进度
progressStartColor / progressEndColor	String	''	渐变起止色	渐变进度
progressGradientAngle	String | Number	90	渐变角度	渐变进度
blockColor	String	''	拇指颜色	外观
blockSize / thumbSize	String | Number	'' / ''	拇指尺寸	外观
hideThumb / dragAnywhere	Boolean	false / true	隐藏拇指、允许轨道任意位置拖动	交互
valuePlacement	String	'auto'	auto/top/meta/both/none	数值位置
bubbleGap	String | Number	10	气泡间距	气泡
bubbleStyle	String	'pill'	pill/indicator	气泡
bubbleUsePopover	Boolean	false	是否将内置数值气泡替换为 xtf-popover 锚定浮层；默认保持原气泡兼容。	需要复用 Popover 的位置与动画能力时。
bubblePopoverPlacement	String	''	Popover 气泡位置；为空时横向 Slider 使用 top，垂直 Slider 使用 right。	需要指定数值浮泡位置时。
bubblePopoverAnimation	String	'scale'	Popover 气泡动画：none/fade/scale/zoom/slide-up/slide-down/slide-left/slide-right。	调整数值浮泡的显示与隐藏节奏。
bubblePopoverGap	String | Number	40	Popover 浮泡与拇指锚点的间距，数字按 rpx 处理；默认比内置 bubbleGap 更大。	需要增加或缩小 Popover 浮泡与滑动轨道的距离时。
trackHeight / width	String | Number	10 / ''	轨道高度、容器宽度	布局
trackRadius / progressRadius	String | Number	''	轨道和进度圆角	外观
progressRadiusTopLeft / progressRadiusTopRight / progressRadiusBottomRight / progressRadiusBottomLeft	String | Number	''	进度四角圆角	精细外观
format	Function	null	(value: Number) => String	数值文本
bubbleFormat	Function	null	(value: Number) => String	气泡文本
customClass / customStyle	String / String | Object	'' / ''	根节点样式覆盖	样式定制

marks 每项支持的字段

字段	类型	默认值	说明
value	Number	-	刻度数值
label	String	value + unit	刻度文案

---

事件

事件名称	触发时机	回调参数	参数说明
input / update:modelValue / update:value	值实时更新	(value: Number | Array)	当前单值或范围值
changing	拖动过程中	(value: Number | Array)	实时值
change	拖动结束、原生 change 或点击刻度	(value: Number | Array)	最终值

事件使用示例

<template><xtf-slider v-model="value" @changing="changing" @change="changed" /></template>
<script>
export default {
  data() {
    return { value: 20 }
  },
  methods: {
    changing(v) {
      console.log('changing', v)
    },
    changed(v) {
      uni.showToast({ title: '已设为 ' + v, icon: 'none' })
    }
  }
}
</script>

---

插槽

插槽名	作用域参数	说明
thumb-left	无	仅 range 为真时，插入在左侧内置滑块之后。
thumb-right	无	仅 range 为真时，插入在右侧内置滑块之后。

范围滑块插槽示例

<template>
  <xtf-slider v-model="range" range :min="0" :max="100" @change="changed">
    <template #thumb-left><view class="range-thumb-marker">起</view></template>
    <template #thumb-right><view class="range-thumb-marker">止</view></template>
  </xtf-slider>
</template>
<script>
export default {
  data() {
    return { range: [20, 80] }
  },
  methods: {
    changed(value) {
      console.log('range', value)
    }
  }
}
</script>

---

主题说明

• 强调色使用 --xtf-slider-accent，由 theme 映射到 --xtf-color-*。
• 轨道默认使用 --xtf-color-surface-muted，拇指边框使用 --xtf-color-surface。
• CSS 变量 --xtf-slider-track-height、--xtf-slider-thumb-size 控制核心尺寸。
• glass、glow、neon 变体分别提供玻璃、发光和深色霓虹效果。

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关变量。