xtf-picker

组件说明

xtf-picker 是滚轮选择器，适用于日期、时段和级联地区选择。支持弹窗、常驻、静态多列、级联、循环滚动与 pickerManager 服务模式。

---

基础用法

1. 单列弹窗

<template>
  <xtf-picker v-model="value" label="优先级" :columns="columns" @confirm="confirm" />
</template>
<script>
export default {
  data() {
    return {
      value: 'normal',
      columns: [
        { label: '普通', value: 'normal' },
        { label: '紧急', value: 'urgent' }
      ]
    }
  },
  methods: {
    confirm(p) {
      console.log(p.value)
    }
  }
}
</script>

2. 多列常驻

<template>
  <xtf-picker
    v-model="date"
    mode="inline"
    :columns="columns"
    :column-titles="['年', '月']"
    @change="changed"
  />
</template>
<script>
export default {
  data() {
    return {
      date: [2026, 8],
      columns: [
        [{ label: '2026年', value: 2026 }],
        [
          { label: '8月', value: 8 },
          { label: '9月', value: 9 }
        ]
      ]
    }
  },
  methods: {
    changed(v) {
      console.log(v)
    }
  }
}
</script>

3. 级联与循环

<template>
  <xtf-picker
    v-model="area"
    mode="inline"
    :columns="areas"
    :column-titles="['区域', '城市']"
    loop
    theme-preset="aurora"
  />
</template>
<script>
export default {
  data() {
    return {
      area: ['east', 'sh'],
      areas: [{ label: '华东', value: 'east', children: [{ label: '上海', value: 'sh' }] }]
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
service	Boolean	false	作为 pickerManager 服务宿主	页面挂载一个
value	String | Number | Boolean | Array	''	当前值	v-model
mode	String	'popup'	popup/inline	展示模式
label / placeholder / title	String	''	字段、占位、面板标题	文案
displayMode / themePreset	String	'flat'/'default'	flat/layered/spread/spotlight/carousel/ticker、主题预设	视觉
columns	Array	[]	单列、多列或级联数据	见下表
valueKey / labelKey / childrenKey	String	'value'/'label'/'children'	数据字段映射	自定义数据
columnTitles / columnWidths / columnGap	Array/Array | String/String | Number	[]/[]/16	列标题、宽度与列间距；间距数字按 rpx 处理	多列
columnHeight / wheelItemHeight / overscanCount / wheelPerspective / wheelCurve	String | Number	400/88/6/1000/1	滚轮尺寸、缓冲、透视和曲率	滚轮效果
motionActiveScale / motionScaleMin / motionOpacityMin / motionOpacityStep / motionOffsetStep / motionBlurStep / motionTransitionDuration	String | Number	1/0.985/0.38/0.22/0/0/90	选项动效参数	视觉微调
snapDuration / momentumThreshold / cascadeDelay	String | Number	180/1.1/34	吸附、惯性、级联延迟	手感
loop / showPreviewPath / validateOnInit	Boolean	false/true/true	循环、预览、初始校验	行为
separator / previewLabel	String	' / '/'当前选择'	路径分隔和标签	预览
displayFormatter	Function	null	({labels,value,path,options})=>String	自定义回显
size / disabled / required / message	String/Boolean/Boolean/String	''/false/false/''	字段状态	表单
confirmText / cancelText / confirmHint / emptyText	String	''	面板文案	文案
popupLayout	String	'default'	弹窗布局：default 标准标题与操作，system 居中标题、关闭图标及底部双操作	滚轮弹窗
popupCustomClass / wheelCustomClass / columnCustomClass / frameCustomClass / optionCustomClass / activeOptionCustomClass	String	''	局部类名	样式
popupCustomStyle / wheelCustomStyle / columnCustomStyle / columnHeadStyle / frameCustomStyle / optionCustomStyle / activeOptionCustomStyle / optionTextStyle / activeOptionTextStyle / maskTopStyle / maskBottomStyle / customStyle	String | Object	''	局部样式	样式
customClass	String	''	根字段类名	样式

columns 节点字段

字段	类型	默认值	说明
value / label	Any/String	-	值和显示文本
children	Array	[]	级联子节点
disabled	Boolean	false	禁止选择

---

事件

事件名称	触发时机	回调参数	参数说明
input / change	选择值提交或 inline 改变	(value)	单值或路径数组
confirm	弹窗确认	({ value,path,labels,options })	完整选择结果
cancel	取消或遮罩关闭	({ source,value,path,labels,options })	取消结果
update:selected	inline 滚轮更新	({ source,value,path,labels,options })	当前选择详情
update:validated	初始/数据变更后校正值	({ source,value })	校正结果

事件使用示例

<template>
  <xtf-picker v-model="value" :columns="columns" @confirm="confirm" @cancel="cancel" />
</template>
<script>
export default {
  data() {
    return { value: 'a', columns: [{ label: 'A', value: 'a' }] }
  },
  methods: {
    confirm(p) {
      console.log(p.labels)
    },
    cancel(p) {
      console.log(p.source)
    }
  }
}
</script>

---

方法

1. open(options) / close() - 控制实例弹窗

非服务模式下，open(options) 会忽略 options 并打开当前实例；服务模式下会将 options 交给 pickerManager。

this.$refs.picker.open()
this.$refs.picker.close()

2. pickerManager.popup(options) - 服务模式弹出

需在页面放置 <xtf-picker service />。

import { pickerManager } from '@/uni_modules/xtf-linkui'
pickerManager
  .popup({ title: '选择时段', columns: [{ label: '上午', value: 'am' }] })
  .then((payload) => console.log(payload.value))

---

插槽

组件源码未声明插槽；弹窗、滚轮列、选项和遮罩的定制均通过对应 *CustomClass、*CustomStyle 属性完成。

---

主题说明

• 字段使用 --xtf-input-bg、--xtf-input-border、--xtf-input-placeholder。
• 文本继承 --xtf-color-text，必填标记使用 --xtf-color-danger。
• default/slate/aurora/sunrise 为组件内置滚轮主题预设。

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