xtf-linkui

Appearance

xtf-select ​

组件说明 ​

xtf-select 是统一下拉选择组件，适用于表单、筛选和远程数据选择。支持单选、多选、搜索、树结构、分组、虚拟滚动、Datacom 与远程分页。

基础用法 ​

1. 单选 ​

vue
<template>
  <xtf-select v-model="value" label="类目" :options="options" clearable @change="changed" />
</template>
<script>
export default {
  data() {
    return {
      value: '',
      options: [
        { label: '数码', value: 'digital' },
        { label: '家居', value: 'home' }
      ]
    }
  },
  methods: {
    changed(v) {
      console.log(v)
    }
  }
}
</script>

2. 多选与搜索 ​

vue
<template>
  <xtf-select v-model="values" :options="options" multiple searchable :max="2" @confirm="confirm" />
</template>
<script>
export default {
  data() {
    return {
      values: [],
      options: [
        { label: '商城', value: 'mall' },
        { label: '门店', value: 'store' }
      ]
    }
  },
  methods: {
    confirm(p) {
      console.log(p.options)
    }
  }
}
</script>

3. 自定义选项插槽 ​

vue
<template>
  <xtf-select v-model="value" :options="options">
    <template #option="{ option, selected }">
      <view>
        <text>{{ option.label }}</text>
<text>{{ selected ? ' 已选' : option.desc }}</text></view>
</template>

  </xtf-select>
</template>
<script>
export default {
  data() {
    return { value: '', options: [{ label: '标准服务', value: 'normal', desc: '48 小时响应' }] }
  }
}
</script>

4. 树选择 ​

vue
<template>
  <xtf-select
    v-model="values"
    :options="options"
    tree
    multiple
    show-path
    default-expand-all
    :tree-check-strictly="false"
  />
</template>
<script>
export default {
  data() {
    return {
      values: [],
      options: [{ label: '技术部', value: 'tech', children: [{ label: '前端组', value: 'web' }] }]
    }
  }
}
</script>

全部属性 ​

属性类型默认值作用描述适用范围
value / modelValueString | Number | Boolean | Array | Object''/undefined当前选择值双向绑定
label / placeholder / titleString''字段文案展示
options / localdataArray[]/undefined普通或本地数据数据源
collection / field / where / orderby / action / pageSize / getcount / loadtimeString | Number | Boolean | Object-Datacom 查询配置uniCloud Datacom
rememberSelection / storageKeyBoolean/Stringtrue/'xtf-select-last-selected-value'缓存集合选择Datacom
valueKey / labelKey / descKeyString'value'/'label'/'desc'字段映射自定义数据
size / disabled / readonly / clearable / clear / requiredString | Boolean''/false/false/false/undefined/false字段状态表单
multiple / searchable / max / showToolbar / separatorBoolean | String | Numberfalse/false/0/true/' / '多选和搜索多选
selectedOption / returnObjectObject | Array/Booleannull/false预缓存选项、返回对象远程回显
remote / remoteMethod / remoteImmediate / searchLoading / searchDebounceBoolean/Function/Boolean/Boolean/String | Numberfalse/null/false/false/0(payload)=>Promise<Array|{options,total}> 远程搜索远程
filterMethodFunctionnull(option,keyword)=>Boolean本地搜索
searchPlaceholder / confirmText / cancelText / emptyText / emptyTips / messageString''文案展示
formatString''{field} 模板格式数据回显
defItem / maxVisibleTagsString | Number0/2默认第几项、最多标签数展示
infiniteScroll / remotePage / remotePageSize / remoteTotal / loadingMore / finishedBoolean | String | Numberfalse/1/20/0/false/false外部远程分页状态分页
groupKeyString'children'分组子项字段分组
mode / placement / autoPlacementString/Boolean'popup'/'bottom-start'/falsepopup/center/dropdown 与下拉位置面板
maxDropdownHeight / maxVisibleOptions / optionHeightString | Number560/6/88面板尺寸布局
showHandle / showCancel / showIndicatorIcon / arrowIcon / clearIconBoolean | Stringtrue/true/true/'expand_more'/'ri-close-line'面板和图标展示
triggerCustomClass / panelCustomClass / dropdownCustomClass / customClassString''类名样式
triggerCustomStyle / panelCustomStyle / dropdownCustomStyle / customStyleString | Object''样式样式
virtualScroll / virtualItemHeight / virtualThresholdBoolean/String | Number/String | Numberfalse/88/100虚拟列表大数据
tree / childrenKey / defaultExpandAll / showPath / treeCheckStrictlyBoolean | Stringfalse/'children'/false/false/true树选择树数据
loadChildrenFunctionnull(option)=>Promise<Array>懒加载树
disabledValues / disableBranchSelect / pathSeparatorArray/Boolean/String[]/false/' / '禁用值、禁选分支、路径分隔树数据

options 每项支持的字段 ​

字段类型默认值说明
value,label,desc,disabled,disableAny/String/String/Boolean/Boolean-值、标题、描述、禁用
children,lazyArray/Boolean[]/false分组或树子项、懒加载标识

事件 ​

事件名称回调参数说明
input / update:modelValue / update:value / change(value)提交选择值时依次触发。
confirm({ value, option?, options })单选含 option，多选含 options。
clear / open / close无清空、打开面板、关闭面板时触发。
reach-max(draft: Array)多选草稿达到 max 时触发。
search(keyword: String)搜索防抖结束后触发。
load-more无开启 infiniteScroll 且滚动到底时触发。
remote-page-change({ page, pageSize, keyword, total, hasMore, reason, internal, options })内置远程请求完成或外部远程分页请求时触发。
error(error)Datacom、远程请求、懒加载或缓存操作失败时触发。

事件使用示例 ​

vue
<template>
  <xtf-select
    v-model="value"
    :options="options"
    searchable
    @search="search"
    @change="changed"
    @clear="cleared"
  />
</template>
<script>
export default {
  data() {
    return { value: '', options: [{ label: 'A', value: 'a' }] }
  },
  methods: {
    search(k) {
      console.log('search', k)
    },
    changed(v) {
      console.log('change', v)
    },
    cleared() {
      console.log('clear')
    }
  }
}
</script>

方法 ​

1. query() - 手动触发 Datacom 查询 ​

仅在 collection 数据源下可用，返回 Promise<Array>。

js
this.$refs.select.query().then((rows) => console.log(rows))

插槽 ​

插槽名作用域参数说明
tagoption、index、label、close替换多选已选标签；调用 close() 移除该选项。
toolbarkeyword、selected-options、draft-value位于多选且非树形面板的工具栏，内置全选和反选之后。
optionoption、index、selected、keyword、label、desc替换每个选项的主体内容。
footerkeyword、selected-options、draft-value面板底部区域；仅提供插槽时渲染。

option 插槽示例 ​

vue
<template>
  <xtf-select v-model="value" :options="options" @change="changed">
    <template #option="{ option, selected, desc }">
      <view class="option-row">
        <text>{{ option.label }}</text>
        <text>{{ selected ? '已选' : desc }}</text>
      </view>
    </template>
  </xtf-select>
</template>
<script>
export default {
  data() {
    return { value: '', options: [{ label: '标准服务', value: 'normal', desc: '48 小时响应' }] }
  },
  methods: {
    changed(value) {
      console.log('change', value)
    }
  }
}
</script>

主题说明 ​

  • 触发器使用 --xtf-input-bg、--xtf-input-border 和 --xtf-color-primary。
  • 面板使用 --xtf-color-surface，选中项使用 --xtf-color-primary-soft。
  • 在 xtf-config-provider 或主题配置中覆盖变量即可全局定制。

MIT Licensed

Copyright © 2026 xtf-linkui