通过本地数据或 datacom 数据渲染单选、多选选项
本 Component 是 uni ext component,需下载插件:uni-data-checkbox
uni-data-checkbox 是符合datacom规范的一组组件,适用于平铺展示枚举类候选项的场景。
给组件传入一组数据,它可以生成多种展示候选的方案,包括单选radio、多选checkbox、并排radio-button、竖排列表、横排tag等多种形态。
因为平铺了所有候选项,所以它不适合候选项非常多的场景。
datacom 规范和 external class 配合使用,既可以简化数据绑定,也可以通过样式类定制选项外观。
组件支持:
default、list、button、tag 四种展示模式。覆盖了常见的平铺候选UI样式。组件负责:根据候选数据渲染选项、维护选中状态、处理禁用与 min/max 约束、回写 v-model 并派发 change,同时提供默认的浅色与暗黑样式。
使用者负责:提供候选数据(localdata 或 uniCloud collection)、绑定当前值、按需通过 external class 定制选项外观、在业务侧处理 change 事件。
通过 localdata 提供候选数据(localdata是相对于uniCloud云端数据的本地数据概念),使用 v-model 绑定当前值。
以下代码,简单的传入一组数据,即可渲染好候选内容。如果没有 uni-data-checkbox组件,开发者需要在template里写大量代码,包括checkbox-group、label、v-for等。
<template>
<uni-data-checkbox v-model="value" :localdata="options" />
</template>
<script setup>
const value = ref(0)
const options = [
{ text: '男', value: 0 },
{ text: '女', value: 1 },
{ text: '未知', value: 2 }
]
</script>
单选模式下,v-model 为字符串或数字;多选模式下,v-model 为数组。
localdata 中的每一项支持以下字段:
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| text | String | - | 选项显示文字 |
| value | String / Number | - | 选项值,用于 v-model 和事件回传 |
| disabled | Boolean | false | 是否禁用当前项 |
| disable | Boolean | false | disabled 的兼容写法 |
| selected | Boolean | false | 多选模式下的初始选中状态。绑定值为非空数组时,以 v-model 为准 |
<script setup lang="ts">
const values = ref(['basketball'])
const options = [
{ text: '足球', value: 'football' },
{ text: '篮球', value: 'basketball' },
{ text: '游泳', value: 'swimming', disabled: true }
]
</script>
<template>
<uni-data-checkbox v-model="values" :localdata="options" multiple />
</template>
数据字段不是 text、value 时,通过 map 指定文字字段和值字段。
<script setup lang="ts">
const values = ref(['pop'])
const options = [
{ name: '流行', code: 'pop' },
{ name: '摇滚', code: 'rock' },
{ name: '爵士', code: 'jazz' }
]
const fieldMap = { text: 'name', value: 'code' }
</script>
<template>
<uni-data-checkbox
v-model="values"
:localdata="options"
:map="fieldMap"
mode="tag"
multiple
/>
</template>
map 只映射文字和值字段。disabled、disable、selected 字段名保持不变。
默认是单选模式,选择新选项后替换当前值。
<uni-data-checkbox v-model="value" :localdata="options" />
设置 multiple 后启用多选,绑定值必须为数组。
<uni-data-checkbox v-model="values" :localdata="options" multiple />
const values = ref([0, 2])
多选模式可通过 min、max 限制最少和最多选择数量。
<uni-data-checkbox
v-model="values"
:localdata="options"
multiple
:min="1"
:max="3"
/>
min 时,当前已选项不可继续取消。max 时,未选项不可继续选择。min、max 仅在 multiple 为 true 时生效。通过 mode 切换展示方式:
default:默认平铺模式,显示单选或复选控件,适用于表单选项、问卷。list:纵向列表模式,适用于设置项、单列选择。button:分段按钮模式,适用于少量选项、视图切换。tag:标签模式,适用于标签筛选、偏好选择。<uni-data-checkbox v-model="value" :localdata="options" />
<uni-data-checkbox v-model="value" :localdata="options" mode="list" />
<uni-data-checkbox v-model="value" :localdata="options" mode="button" />
<uni-data-checkbox v-model="values" :localdata="options" mode="tag" multiple />
icon="right" 时不显示左侧单选或复选控件,选中标记显示在选项右侧。该写法通常与 list 模式配合使用。
<uni-data-checkbox
v-model="value"
:localdata="options"
mode="list"
icon="right"
/>
通过组件的 disabled 禁用全部选项:
<uni-data-checkbox v-model="value" :localdata="options" disabled />
通过数据项的 disabled 或 disable 禁用指定选项:
const options = [
{ text: '可用选项', value: 'available' },
{ text: '不可用选项', value: 'unavailable', disabled: true }
]
禁用项不会更新 v-model,也不会触发 change。
将组件放在 uni-forms-item 中,并将 v-model 绑定到对应表单字段。
<template>
<uni-forms ref="formRef" v-model="formData" :rules="rules">
<uni-forms-item name="hobbies" label="兴趣">
<uni-data-checkbox
v-model="formData.hobbies"
:localdata="hobbyOptions"
multiple
/>
</uni-forms-item>
</uni-forms>
</template>
<script setup lang="ts">
const formRef = ref<any>(null)
const formData = ref({ hobbies: [] as string[] })
const hobbyOptions = [
{ text: '阅读', value: 'reading' },
{ text: '运动', value: 'sports' },
{ text: '音乐', value: 'music' }
]
const rules = {
hobbies: {
rules: [{ required: true, errorMessage: '请选择兴趣' }]
}
}
</script>
不传 localdata,并设置 collection 后,组件从 uniCloud 云数据库加载候选数据。
<template>
<uni-data-checkbox
v-model="cityCode"
collection="opendb-city-china"
field="code as value, name as text"
where="eq(type, 2)"
orderby="code asc"
:page-size="50"
empty-text="暂无城市数据"
/>
</template>
<script setup lang="ts">
const cityCode = ref('110000')
</script>
云端查询返回的数据需要包含 text、value 字段,也可以通过 field 设置别名,或结合 map 使用自定义字段。
使用云端数据前,需要:
只使用 localdata 时不需要关联 uniCloud 服务空间。localdata 与 collection 同时设置时,优先使用本地数据。
数据格式与查询参数参见 datacom 组件规范 和 uniCloud Datacom API。
使用树形或分组查询时,应确保最终返回的数据仍是组件可平铺展示的候选项数组。
推荐使用 v-model 接收当前值,通过 change 获取值和完整数据项。
<template>
<uni-data-checkbox
v-model="value"
:localdata="options"
@update:modelValue="onUpdate"
@change="onChange"
/>
</template>
<script setup lang="ts">
function onUpdate(value : any) {
console.log('当前值', value)
}
function onChange(event : any) {
console.log('当前值', event.detail.value)
console.log('当前数据', event.detail.data)
}
</script>
单选模式的 event.detail.data 为当前数据项,多选模式为已选数据项数组。
组件通过 external class 开放选项样式。样式类写在使用组件的页面中。
<uni-data-checkbox
v-model="values"
:localdata="options"
multiple
label-class="choice-label"
text-class="choice-text"
checkbox-class="choice-control"
label-selected-class="choice-label-selected"
text-selected-class="choice-text-selected"
checkbox-selected-class="choice-control-selected"
/>
.choice-label {
margin-right: 16px;
}
.choice-text {
font-size: 15px;
}
.choice-text-selected {
color: #007aff;
}
@media (prefers-color-scheme: dark) {
.choice-text-selected {
color: #91caff;
}
}
组件提供浅色和暗黑模式默认样式。自定义颜色时,应同时为浅色和暗黑模式设置合适的文字、背景和状态颜色,并检查默认、选中、禁用三种状态。
value 和 v-model 设置不同的值。需要双向绑定时使用 v-model。value 类型一致;多选数组中的每一项也必须与对应 value 类型一致。例如数字 1 与字符串 '1' 是不同的值。value 应在候选数据中保持唯一,否则选中状态和事件数据可能不明确。multiple 为 true 时,绑定值应始终使用数组,包括没有选中项时的空数组 []。selected: true 时,空数组会按 selected 初始化;需要保持空选状态时,不要设置该字段。0 <= min <= max,并确保初始值数量符合限制。localdata 使用响应式数组时,更新选项文字、禁用状态或字段映射会同步刷新展示。| 名称 | 类型 | 描述 | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| mode | string | |||||||||||
| ||||||||||||
| multiple | boolean | |||||||||||
| ||||||||||||
| value | Array | string | number | |||||||||||
| modelValue | Array | string | number | |||||||||||
| localdata | Array | |||||||||||
| min | string | number | |||||||||||
| max | string | number | |||||||||||
| icon | string | |||||||||||
| ||||||||||||
| emptyText | string | |||||||||||
| map | object | |||||||||||
| disabled | boolean | |||||||||||
| labelClass | string(string.ClassString) | |||||||||||
| textClass | string(string.ClassString) | |||||||||||
| checkboxClass | string(string.ClassString) | |||||||||||
| labelSelectedClass | string(string.ClassString) | |||||||||||
| textSelectedClass | string(string.ClassString) | |||||||||||
| checkboxSelectedClass | string(string.ClassString) | |||||||||||
| iconClass | string(string.ClassString) | |||||||||||
| emptyTextClass | string(string.ClassString) | |||||||||||
| collection | string | |||||||||||
| options | object | Array | |||||||||||
| action | string | |||||||||||
| field | string | |||||||||||
| where | string | object | |||||||||||
| orderby | string | |||||||||||
| pageData | string | |||||||||||
| ||||||||||||
| pageCurrent | number | |||||||||||
| pageSize | number | |||||||||||
| getcount | boolean | string | |||||||||||
| gettree | boolean | string | |||||||||||
| gettreepath | boolean | string | |||||||||||
| startwith | string | |||||||||||
| limitlevel | number | |||||||||||
| groupby | string | |||||||||||
| groupField | string | |||||||||||
| distinct | boolean | string | |||||||||||
| manual | boolean | |||||||||||
| @change | Function | 用户选择变化时触发 | ||||||||||
| @update:modelValue | Event | 用户选择变化时更新绑定值 | ||||||||||
示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见
示例
<template>
<view>
<view class="intro">
<text class="page-title">uni-data-checkbox 数据选择器</text>
<text class="page-desc">使用本地数据完成单选、多选、选择约束和多种展示模式,并通过 external class 调整选项样式。</text>
</view>
<view class="group-header">
<text class="group-title">基础用法</text>
</view>
<view class="section">
<text class="section-title">单选与事件</text>
<text class="section-desc">数字 0 作为有效默认值,同时监听 modelValue 和 change。</text>
<uni-data-checkbox
v-model="sexValue"
:localdata="sex"
label-class="demo-inline-label"
label-selected-class="test-zero-selected"
@update:modelValue="onUpdate"
@change="onChange"
/>
<view class="result-block">
<text class="result-text">当前值:{{ sexValue }}</text>
<text class="event-text">最近事件:{{ latestEvent }}</text>
</view>
</view>
<view class="section">
<text class="section-title">多选与事件</text>
<text class="section-desc">支持数组模型和默认选中项。</text>
<uni-data-checkbox
v-model="sexMultiValue"
:localdata="hobby"
multiple
label-class="demo-inline-label"
text-class="test-dynamic-text"
@update:modelValue="onMultiUpdate"
@change="onMultiChange"
/>
<view class="result-block">
<text class="result-text">当前值:{{ JSON.stringify(sexMultiValue) }}</text>
<text class="event-text">最近事件:{{ latestMultiEvent }}</text>
</view>
</view>
<view class="section">
<text class="section-title">选择数量限制</text>
<text class="section-desc">最多选择 3 项,数据中的 disable 可单独禁用选项。</text>
<uni-data-checkbox
v-model="sexMultiMaxValue"
:localdata="hobbyMore"
:max="3"
multiple
label-class="demo-inline-label"
/>
<text class="result-text result-standalone">当前值:{{ JSON.stringify(sexMultiMaxValue) }}</text>
</view>
<view class="group-header">
<text class="group-title">展示模式</text>
</view>
<view class="section">
<text class="section-title">Button 模式</text>
<uni-data-checkbox v-model="buttonValue" mode="button" :localdata="buttonOptions" />
<text class="result-text result-standalone">当前值:{{ buttonValue }}</text>
</view>
<view class="section">
<text class="section-title">Tag 模式与字段映射</text>
<text class="section-desc">使用 map 映射 name/code 字段,并限制选择 1 至 3 项。</text>
<uni-data-checkbox
v-model="tagValue"
mode="tag"
multiple
:localdata="mappedOptions"
:map="mappedFields"
:min="1"
:max="3"
label-class="demo-tag-label"
text-class="demo-tag-text test-map-text"
/>
<text class="result-text result-standalone">当前值:{{ JSON.stringify(tagValue) }}</text>
</view>
<view class="section">
<text class="section-title">List 模式与图标位置</text>
<text class="subsection-title">默认图标</text>
<view class="list-frame">
<uni-data-checkbox
v-model="listValue"
mode="list"
:localdata="hobby"
label-class="demo-list-label"
text-class="demo-list-text"
label-selected-class="demo-list-selected"
icon-class="demo-right-icon"
/>
</view>
<text class="subsection-title subsection-spaced">右侧对勾</text>
<view class="list-frame">
<uni-data-checkbox
v-model="listRightValue"
mode="list"
icon="right"
:localdata="hobby"
label-class="demo-list-label"
text-class="demo-list-text"
label-selected-class="demo-list-selected"
icon-class="demo-right-icon"
/>
</view>
<text class="subsection-title subsection-spaced">左右对齐</text>
<view class="list-frame">
<uni-data-checkbox
v-model="listAlignValue"
mode="list"
:localdata="alignOptions"
label-class="demo-list-label demo-list-align"
text-class="demo-list-text-align"
label-selected-class="demo-list-selected"
text-selected-class="demo-list-text-selected"
/>
</view>
</view>
<view class="group-header">
<text class="group-title">状态与样式</text>
</view>
<view class="section section-last">
<text class="section-title">禁用状态与外部样式</text>
<text class="section-desc">组合全局 disabled、数据项 disabled、min/max 与 external class。</text>
<uni-data-checkbox
v-model="disabledValues"
multiple
:localdata="disabledOptions"
:min="1"
:max="2"
disabled
empty-text="暂无可选数据"
empty-text-class="demo-empty-text"
label-class="demo-inline-label"
label-selected-class="test-default-selected"
/>
<text class="result-text result-standalone">当前值:{{ JSON.stringify(disabledValues) }}</text>
</view>
</view>
</template>
<script setup lang="ts">
const sex = [
{ text: '男', value: 0 },
{ text: '女', value: 1 },
{ text: '未知', value: 2 }
]
const hobby = reactive([
{ text: '足球', value: 0 },
{ text: '篮球', value: 1 },
{ text: '游泳', value: 2 }
])
const buttonOptions = [
{ text: '选项一', value: 'normal' },
{ text: '选项二', value: 'other' },
{ text: '选项三', value: 'third' }
]
const mappedOptions = [
{ name: '流行', code: 'pop', label: 'POP', id: 'p' },
{ name: '摇滚', code: 'rock', label: 'ROCK', id: 'r' },
{ name: '爵士', code: 'jazz', label: 'JAZZ', id: 'j' },
{ name: '蓝调', code: 'blues', label: 'BLUES', id: 'b' },
{ name: '古典', code: 'classic', label: 'CLASSIC', id: 'c' }
]
const disabledOptions = [
{ text: '固定选中', value: 'fixed', selected: true },
{ text: '不可用', value: 'unavailable', disabled: true },
{ text: '普通选项', value: 'available' }
]
const sexValue = ref(0)
const sexMultiValue = ref([1])
const sexMultiMaxValue = ref([])
const hobbyMore = [
{ text: '足球', value: 0 },
{ text: '篮球', value: 1 },
{ text: '游泳', value: 2 },
{ text: '乒乓球', value: 3 },
{ text: '羽毛球', value: 4 },
{ text: '网球', value: 5, disable: true }
]
const buttonValue = ref('normal')
const tagValue = ref(['pop'])
const listValue = ref(1)
const listRightValue = ref(1)
const alignOptions = [
{ text: '50毫秒', value: 50 },
{ text: '200毫秒', value: 200 },
{ text: '400毫秒', value: 400 }
]
const listAlignValue = ref(200)
const disabledValues = ref([])
const mappedFields = reactive({ text: 'name', value: 'code' })
const latestEvent = ref('未触发')
const latestMultiEvent = ref('未触发')
const onUpdate = (event) => {
latestEvent.value = 'update:modelValue:' + JSON.stringify(event)
console.log('onUpdate:', event)
}
const onChange = (event) => {
latestEvent.value = 'change:' + JSON.stringify(event.detail.value)
console.log('onChange:', event)
}
const onMultiUpdate = (event) => {
latestMultiEvent.value = 'update:modelValue:' + JSON.stringify(event)
console.log('onMultiUpdate:', event)
}
const onMultiChange = (event) => {
latestMultiEvent.value = 'change:' + JSON.stringify(event.detail.value)
console.log('onMultiChange:', event)
}
const clearDisabledValues = () => {
disabledValues.value = []
}
const updateFirstHobby = () => {
hobby[0].text = '足球(已更新)'
}
const useAlternateMap = () => {
mappedFields.text = 'label'
mappedFields.value = 'id'
}
defineExpose({
clearDisabledValues,
updateFirstHobby,
useAlternateMap
})
</script>
<style>
page {
--background-color: #f5f5f5;
--active-background-color: #f8f8f8;
--text-color: #333333;
--tips-color: #0958d9;
--tips-background-color: #e6f4ff;
--content-background-color: #ffffff;
--secondary-text-color: #657180;
--input-border-color: #dcdfe6;
--divider-color: #e5e5e5;
--data-checkbox-demo-error-color: #dd524d;
background-color: var(--background-color);
}
.intro {
padding: 18px 16px;
background-color: var(--content-background-color, #ffffff);
}
.page-title {
font-size: 20px;
font-weight: bold;
color: var(--text-color, #222222);
}
.page-desc {
margin-top: 8px;
font-size: 14px;
line-height: 21px;
color: var(--secondary-text-color, #657180);
}
.group-header {
padding: 18px 16px 6px;
}
.group-title {
font-size: 14px;
font-weight: bold;
color: var(--secondary-text-color, #657180);
}
.section {
padding: 16px;
margin-top: 10px;
background-color: var(--content-background-color, #ffffff);
}
.section-last {
padding-bottom: 32px;
}
.section-title {
margin-bottom: 12px;
font-size: 16px;
font-weight: bold;
color: var(--text-color, #333333);
}
.section-desc {
margin-top: -4px;
margin-bottom: 12px;
font-size: 13px;
line-height: 20px;
color: var(--secondary-text-color, #657180);
}
.subsection-title {
margin-bottom: 8px;
font-size: 13px;
font-weight: bold;
color: var(--secondary-text-color, #657180);
}
.subsection-spaced {
margin-top: 18px;
}
.result-block,
.result-standalone {
margin-top: 10px;
}
.result-block {
flex-direction: column;
}
.result-text,
.event-text {
font-size: 13px;
line-height: 20px;
color: var(--secondary-text-color, #657180);
}
.event-text {
margin-top: 2px;
}
.list-frame {
border-width: 1px;
border-style: solid;
border-color: var(--divider-color, #e2e5e9);
border-radius: 6px;
overflow: hidden;
}
.demo-inline-label {
margin-right: 20px;
margin-bottom: 8px;
}
.demo-tag-label {
margin-right: 8px;
margin-bottom: 8px;
border-radius: 6px;
}
.demo-tag-text {
font-size: 14px;
}
.demo-list-label {
padding-left: 12px;
padding-right: 12px;
}
.demo-list-text {
flex: 1;
}
.demo-list-align {
justify-content: space-between;
}
.demo-list-text-align {
flex: 1;
text-align: right;
}
.demo-list-selected {
background-color: var(--active-background-color, #f2f7ff);
}
.demo-list-text-selected {
color: var(--tips-color, #007aff);
}
.demo-right-icon {
width: 7px;
height: 13px;
}
.demo-empty-text {
color: var(--data-checkbox-demo-error-color, #dd524d);
}
@media (prefers-color-scheme: dark) {
page {
--background-color: #1a1a1a;
--active-background-color: #3b3b3b;
--text-color: #ffffff;
--tips-color: #91caff;
--tips-background-color: #0b1b3a;
--content-background-color: #2d2d2d;
--secondary-text-color: rgba(255, 255, 255, 0.65);
--input-border-color: rgba(255, 255, 255, 0.18);
--divider-color: rgba(255, 255, 255, 0.12);
--data-checkbox-demo-error-color: #ff7875;
}
}
</style>