企业官网建设流程全解析

• 前端
• UI组件
• 移动开发

cube-ui 是滴滴开源的基于 Vue 2 的移动端 UI 组件库，本文围绕其 Checkbox 复选框组件（cube-checkbox）展开，覆盖从基础用法、option配置对象、图标位置与形状定制，到禁用态、点击事件处理和源码级实现原理的完整链路。读完本文，你将能熟练使用单复选框的多种数据绑定方式，并理解v-model在复选框场景下的真实取值逻辑，可直接将其运用到表单、协议确认、选项筛选等移动端业务场景中。

组件概述

cube-checkbox是 cube-ui 提供的基础表单组件，官方文档对其定位为：复选框，可设置其状态、传入特殊 class 以及复选框图标位置（见 中文文档）。

与原生<input type="checkbox">相比，cube-ui 的复选框通过v-model直接与业务数据双向绑定，并支持：

• 通过option配置对象携带label/value/disabled元数据；
• 通过position、shape、hollowStyle快速切换图标位置、形状与镂空样式；
• 通过插槽（slot）自由定制标签区域内容；
• 与cube-checkbox-group组合实现多选组、横向布局与min/max数量约束。

组件源码位于 src/components/checkbox/checkbox.vue，模块化注册入口为 src/modules/checkbox/index.js（通过Vue.component注册为全局组件），完整可运行示例见 example/pages/checkbox.vue。

基本用法：v-model 双向绑定

官方文档给出的最小示例：

<cube-checkbox v-model="checked"> Checkbox </cube-checkbox>

如果选中了，则checked的值就为true；取消选中则恢复为false。

在源码层面，v-model依赖组件对外暴露的valueprop 与input事件。value的类型声明为[Boolean, String]，checkValue计算属性同时承担取值与赋值两个职责（src/components/checkbox/checkbox.vue）：

checkValue: { get () { if (this.isInGroup) { return this.$parent.value.indexOf(this.computedOption.value) > -1 } else { return Boolean(this.value) } }, set (newValue) { const value = this.computedOption.value const emitValue = value && newValue ? value : newValue this.$emit(EVENT_INPUT, emitValue) ... } }

从中可以看出两个关键实现细节：

1. 渲染时：组件根元素会根据选中状态动态挂上cube-checkbox_checkedclass，未选中时是普通cube-checkbox，选中后是cube-checkbox cube-checkbox_checked，这一行为被 test/unit/specs/checkbox.spec.js 的should render correct contents用例直接断言。
2. 点击切换时：点击内部的透明<input type="checkbox">（opacity: 0铺满整个区域，见 checkbox.vue），checkValue的 setter 触发input事件，把更新后的值同步回父级v-model。should toggle v-model value测试用例验证了从true切到false的完整链路。

复选框图标样式：position、shape 与 hollowStyle

官方文档展示了样式定制的组合用法：

<cube-checkbox v-model="checked" position="right" shape="square" :hollow-style="true"> Styled Checkbox </cube-checkbox>

三个 prop 各自的作用如下：

• position="right"：复选框图标显示在文字右侧。源码中根节点会根据position渲染data-pos属性（left/right），Sticky 样式通过&[data-pos="right"]将图标绝对定位到右侧并给标签留出外边距（checkbox.vue）。
• shape="square"：图标形状由圆形切换为方形。实现上通过isSquare计算属性选择不同的图标字体类名：方形用cubeic-square-border/cubeic-square-right，圆形用cubeic-round-border/cubeic-right。
• :hollow-style="true"：显示镂空样式。官方文档特别说明：即使shape不是square，只要设置了hollowStyle，表现的也是方形的——因为isSquare的判断条件是this.shape === 'square' || this.hollowStyle。

镂空样式在 CSS 上通过.cube-checkbox-hollow覆盖图标内部结构实现：图标内部用::before生成一个居中的小色块（currentColor），选中时色块与描边同时呈现主题色，未选中时则淡出（checkbox.vue）。

通过 option 配置对象绑定业务值

官方文档的"改变 model 的值"示例展示了option的典型用法：

<cube-checkbox v-model="checked" :option="option" />

export default { data() { return { checked: false, option: { label: 'Option Checkbox', value: 'optionValue', disabled: false } } } }

文档明确说明了其取值行为：当复选框选中的时候，checked的值就是'optionValue'；当未选中的时候，checked的值就是false。因此官方特别提醒：在单个复选框的场景下，最好不要设置option（否则选中后绑定的值会从布尔值变成字符串，反而带来额外的判断成本）。

option的子配置项如下：

| 参数 | 说明 | 类型 | | - | - | - | | label | 复选框显示文字 | String | | value | 复选框的值 | String/Number | | disabled | 复选框是否被禁用 | Boolean |

源码中的 option 归一化逻辑

computedOption计算属性（checkbox.vue）负责把各种形态的option统一成标准对象：

computedOption() { let option = this.option const label = this.label const disabled = this.disabled if (option._def_option === true) { // 未传 option：使用 label / value / disabled 三个独立 prop option = { label, value: label, disabled } } else if (typeof option === 'string') { // option 为字符串：label 和 value 均取该字符串 option = { label: option, value: option, disabled: false } } return option }

三种情况对应三种数据来源：

1. 不传option：组件内置默认值{ _def_option: true }（见 props 定义），此时退化为使用独立的label、value、disabledprop 构建配置；
2. option为字符串：如<cube-checkbox :option="'北京'">，此时label与value都等于该字符串，disabled为false——这与 Props 配置表中"如果 options 中的项为字符串，此时默认 label 和 value 的值都为该字符串的值"的描述一致；
3. option为对象：直接使用label/value/disabled三个字段。

而在checkValue的 setter 中，const emitValue = value && newValue ? value : newValue正是"选中输出option.value、未选中输出false"这一行为的实现来源。

禁用状态

官方文档示例：

<cube-checkbox v-model="checked" :option="{disabled: true}"> Disabled Checkbox </cube-checkbox>

其本质是把option.disabled设为true，组件内部通过computedOption.disabled控制：原生 input 上渲染disabled属性阻止点击，同时根节点挂载cube-checkbox_disabledclass，配合主题变量呈现禁用配色：

• 未选中禁用：图标底色为$checkbox-disabled-icon-bgc（浅灰），对勾颜色为$checkbox-disabled-icon-color；
• 选中禁用：图标底色切换为$checkbox-checked-icon-bgc，但禁用态下transition被关闭且对勾使用禁用色，视觉上区分"不可操作"状态。

相关主题变量定义在 src/common/stylus/theme/default.styl，例如选中态主色$checkbox-checked-icon-color := $color-orange（橙色）、禁用态$checkbox-disabled-icon-color := $color-light-grey-ss等，可通过主题定制整体替换。

另外，option对象也支持简写方式直接内联禁用，如:option="{disabled: true}"，与上面的对象写法等价；若在组内使用，还可以直接给<cube-checkbox disabled>传独立的disabledprop（default: false），此时会走_def_option分支被并入配置。

处理标签区域内的点击事件

当复选框标签内需要放置可点击的链接或富文本时，直接绑定点击事件会被外层label的选中逻辑拦截。官方文档给出的方案是修改样式提升链接层级：

<cube-checkbox class="with-click" v-model="checked"> Agree <a href="javascript:;" @click.stop>《xxx》</a> </cube-checkbox>

.with-click .cube-checkbox-label a position: relative z-index: 1

原理分析：cube-checkbox-input（透明原生 input）是position: absolute且z-index: 1铺满整个组件区域，天然盖在标签文字之上，所以点击标签区域实际上会命中 input 从而切换选中状态。给链接设置position: relative; z-index: 1后，链接被提升到 input 之上，点击链接即可触发链接自身的@click.stop（阻止冒泡），而点击链接以外的标签区域仍然正常切换复选框状态。

示例页面中对此样式有完整演示（example/pages/checkbox.vue），常见应用场景包括"我已阅读并同意《用户协议》"之类的协议勾选。

Props 配置总表

官方文档的完整 Props 配置如下：

| 参数 | 说明 | 类型 | 可选值 | 默认值 | | - | - | - | - | - | | option | 配置项（如果 options 中的项为字符串，此时默认 label 和 value 的值都为该字符串的值） | Boolean/String/Object | - | - | | position | 位置 | String | left/right | left | | shape | 图标形状 | String | circle/square | circle | | hollowStyle | 是否是镂空样式的 | Boolean | true/false | false |

对照源码 props 定义，可补充以下实现层面的说明：

• option声明类型为[Boolean, String, Object]，默认值为{ _def_option: true }标记"未显式配置"；表中类型列写的Boolean与默认标记对象并不冲突——Boolean用于兼容布尔形态（实际等价于未配置的默认分支）。
• position、shape均有各自默认值，且组件内未对非法值做拦截，传入可选值之外的字符串会退化为默认样式路径。
• hollowStyle与shape存在联动：设置hollowStyle为true时图标强制表现为方形。

事件

官方文档定义的事件如下：

| 事件名 | 说明 | 参数 | | - | - | - | | input | 当绑定值变化时触发 | 更新后的复选框的值（若 option 中设置了 value，且勾选复选框时，该值为 option.value；否则，该值为复选框的 v-model 值） |

input事件是v-model生效的核心。从源码看，checkValuesetter 中除input外还定义了checked/cancel-checked两个内部事件常量，但这两个事件仅在处于复选框组（cube-checkbox-group）上下文时向父级抛出，用于组件的多选值增删联动，单个复选框场景下无需关注。

与 cube-checkbox-group 的联动（拓展）

虽然本文主题是单复选框，但cube-checkbox设计上深度耦合了组场景（src/components/checkbox-group/checkbox-group.vue）：

• 组件挂载时通过this.$parent.$data._checkboxGroup判断是否处于组内（checkbox.vue）；
• 组内时checkValue.get改为判断option.value是否存在于父级value数组中，选中状态完全由父级数组驱动；
• 组内点击时不再直接透出布尔值，而是向父组件抛出checked/cancel-checked，由父组件维护数组并在min/max约束下决定是否增删（checkbox-group.vue）。

test/unit/specs/checkbox-group.spec.js 中的min & max用例验证了：min保证至少保留 1 项、max限制最多选中 3 项的行为。横排模式下（horizontal或colNum > 1），复选框之间还会自动追加border-right-1px分隔线（checkbox.vue）。

小结

cube-ui 的cube-checkbox是一个实现精巧、可组合性强的表单组件：对外只需一个v-model即可完成双向绑定，option提供了从布尔值到业务值的灵活桥接，position/shape/hollowStyle覆盖了大多数视觉定制需求，而内部通过与cube-checkbox-group的事件协作实现了复杂的多选约束逻辑。无论是简单的协议勾选，还是列表中的多选筛选，都能以极少的模板代码获得一致且可主题化的移动端交互体验。相关源码与测试均可在仓库中直接查阅验证。

• 前端
• UI组件
• 移动开发