xtf-linkui

Appearance

xtf-checkbox ​

组件说明 ​

xtf-checkbox 是复选框组件，用于在多个选项中进行多选。支持方形/圆形指示器、多种变体（默认、柔和、卡片、按钮等）、半选状态、自定义图标、勾选动画和变更拦截，适用于表单多选、协议确认和偏好设置等场景。

基础用法 ​

1. 最简示例 ​

通过 label 设置文字，v-model 绑定选中状态：

vue
<template>
  <xtf-checkbox v-model="agreed" label="我已阅读并同意用户协议" />
</template>

<script>
export default {
  data() {
    return {
      agreed: false
    }
  }
}
</script>

2. 复选框组 ​

配合 xtf-checkbox-group 实现多选组，通过 name 标识选项值：

vue
<template>
  <xtf-cell-group title="兴趣爱好">
    <xtf-checkbox-group v-model="hobbies" direction="column">
      <xtf-checkbox name="reading" label="阅读" />
      <xtf-checkbox name="music" label="音乐" />
      <xtf-checkbox name="sports" label="运动" />
      <xtf-checkbox name="travel" label="旅行" />
    </xtf-checkbox-group>
  </xtf-cell-group>
</template>

<script>
export default {
  data() {
    return {
      hobbies: ['reading', 'music']
    }
  }
}
</script>

3. 形状与变体 ​

通过 shape 切换方形/圆形，通过 variant 切换视觉风格：

vue
<template>
  <view style="display: flex; flex-direction: column; gap: 20rpx">
    <xtf-text level="caption" color="secondary">方形（默认）</xtf-text>
    <xtf-checkbox-group v-model="selected" direction="row" :gap="24">
      <xtf-checkbox name="a" label="选项A" shape="square" />
      <xtf-checkbox name="b" label="选项B" shape="square" />
    </xtf-checkbox-group>

    <xtf-text level="caption" color="secondary">圆形</xtf-text>
    <xtf-checkbox-group v-model="selected2" direction="row" :gap="24">
      <xtf-checkbox name="a" label="选项A" shape="circle" />
      <xtf-checkbox name="b" label="选项B" shape="circle" />
    </xtf-checkbox-group>

    <xtf-text level="caption" color="secondary">按钮变体</xtf-text>
    <xtf-checkbox-group v-model="selected3" direction="row" :gap="16" variant="button">
      <xtf-checkbox name="apple" label="苹果" />
      <xtf-checkbox name="banana" label="香蕉" />
      <xtf-checkbox name="orange" label="橙子" />
    </xtf-checkbox-group>
  </view>
</template>

<script>
export default {
  data() {
    return {
      selected: ['a'],
      selected2: ['a'],
      selected3: ['apple']
    }
  }
}
</script>

4. 半选与禁用 ​

通过 indeterminate 设置半选状态，通过 disabled 禁用交互：

vue
<template>
  <view style="display: flex; flex-direction: column; gap: 20rpx">
    <xtf-checkbox label="半选状态" :indeterminate="true" />
    <xtf-checkbox label="禁用未选" disabled />
    <xtf-checkbox label="禁用已选" disabled checked />
  </view>
</template>

5. 主题色与自定义值 ​

通过 theme 切换主题色，通过 trueValue / falseValue 自定义选中/未选值：

vue
<template>
  <view style="display: flex; flex-direction: column; gap: 20rpx">
    <xtf-checkbox-group v-model="colors" direction="row" :gap="24">
      <xtf-checkbox name="1" label="主要" theme="primary" />
      <xtf-checkbox name="2" label="成功" theme="success" />
      <xtf-checkbox name="3" label="警告" theme="warning" />
      <xtf-checkbox name="4" label="危险" theme="danger" />
    </xtf-checkbox-group>

    <xtf-checkbox v-model="status" label="启用通知" :true-value="'on'" :false-value="'off'" />
    <xtf-text level="caption">当前值：{{ status }}</xtf-text>
  </view>
</template>

<script>
export default {
  data() {
    return {
      colors: ['1'],
      status: 'off'
    }
  }
}
</script>

全部属性 ​

属性类型默认值作用描述适用范围
valueanyundefined绑定值（Vue 2）双向绑定
modelValueanyundefined绑定值（Vue 3）双向绑定
nameString | Number | Boolean''在 xtf-checkbox-group 中的标识值分组标识
labelString''文字标签显示文字
descriptionString''描述文字补充说明
checkedBooleanfalse是否选中（非受控模式）选中状态
trueValueanytrue选中时的值自定义选中值
falseValueanyfalse未选时的值自定义未选值
indeterminateBooleanfalse是否半选状态全选/半选
shapeString'square'形状：'square' / 'circle'切换形状
labelClickableBooleantrue点击文字是否触发切换文字交互
disabledBooleanfalse是否禁用禁用交互
themeString''主题色：'primary' / 'success' / 'warning' / 'danger' / 'info'切换主题色
colorString''自定义选中颜色；activeColor 存在时优先使用 activeColor自定义色
activeColorString''选中时颜色自定义选中色
sizeString''尺寸：'sm' / 'md' / 'lg'控制大小
variantString''变体：'default' / 'soft' / 'card' / 'button' / 'tile' / 'solid' / 'glass' / 'minimal'切换视觉风格
checkAnimationString''勾选动画：'none' / 'scale' / 'fade' / 'bounce' / 'flip' / 'pulse' / 'slide'切换动画
iconSizeString | Number''指示器图标大小自定义图标大小
checkedIconString''选中时图标名或图片地址自定义选中图标
uncheckedIconString''未选时图标名或图片地址自定义未选图标
indeterminateIconString''半选时图标名或图片地址自定义半选图标
iconPositionString'left'图标位置：'left' / 'right'切换图标位置
alignString'center'对齐方式：'center' / 'start'对齐方式
blockBooleanfalse是否占满整行块级布局
borderedBooleanfalse是否显示边框边框显示
beforeChangeFunctionnull变更拦截函数，返回 false 阻止变更变更拦截
customClassString''自定义类名样式覆盖
customStyleString | Object''自定义样式动态样式覆盖

事件 ​

事件名称触发时机回调参数参数说明
change选中状态变更时触发(value)新的值（由 trueValue / falseValue 决定）
inputVue 2 双向绑定更新(value)新的值
update:modelValueVue 3 双向绑定更新(value)新的值
update:value值更新(value)新的值

事件使用示例 ​

vue
<template>
  <xtf-checkbox v-model="enabled" label="接收消息通知" @input="onInput" @change="onChange" />
</template>

<script>
export default {
  data() {
    return { enabled: false }
  },
  methods: {
    onInput(value) {
      console.log('绑定值更新', value)
    },
    onChange(value) {
      uni.showToast({ title: value ? '已开启' : '已关闭', icon: 'none' })
    }
  }
}
</script>

插槽 ​

插槽名作用域参数说明
默认插槽无替换 label 文本。
description无替换 description 辅助说明。
icon{ checked, indeterminate, disabled }替换复选框指示器。
vue
<template>
  <xtf-checkbox v-model="enabled">
    <template #icon="{ checked }">
      <xtf-icon :name="checked ? 'check_circle' : 'radio_button_unchecked'" size="sm" />
    </template>
    <xtf-text level="body" text="使用自定义标签" />
    <template #description>
      <xtf-text level="caption" color="secondary" text="该设置可随时关闭" />
    </template>
  </xtf-checkbox>
</template>

<script>
export default {
  data() {
    return { enabled: true }
  }
}
</script>

主题说明 ​

  • 选中颜色使用 --xtf-checkbox-color，默认取主题色映射（primary 对应 var(--xtf-color-primary) 等）
  • 勾选标记颜色使用 --xtf-checkbox-tick，默认 #ffffff
  • 图标尺寸使用 --xtf-checkbox-icon-size、--xtf-checkbox-glyph-size、--xtf-checkbox-image-size
  • 动画类型通过 checkAnimation 属性控制，默认 'scale'

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

MIT Licensed

Copyright © 2026 xtf-linkui