cube-ui Toolbar 工具栏组件完全指南：actions 操作项与 moreActions 双层展开实战-平芜编程栈

前端
UI组件
移动开发

【免费下载链接】cube-ui

:large_orange_diamond: A fantastic mobile ui lib implement by Vue

项目地址：https://gitcode.com/gh_mirrors/cu/cube-ui

cube-ui 的 Toolbar（工具栏）组件（1.9.0 新增）用于在移动端页面底部组合展示一组操作按钮，支持普通按钮操作与复选框操作混排，并通过moreActions将工具栏扩展为可展开/收起的双层结构。本文基于 Toolbar 官方文档与仓库源码，完整讲解其配置项、事件与底层实现，帮助你直接在业务页面中落地使用。

组件定位：一个固定在底部的操作聚合栏

从 toolbar.vue 的样式代码可以看到，.cube-toolbar采用position: fixed固定在视口底部（左右各留 10px 边距、底部留 10px 间距，z-index: 2），并调用safe-area-mixin(padding-bottom, bottom)适配 iPhone X 等设备的底部安全区。它适合承载"完成订单""确认提交""更多操作"这类高频底部动作，一个工具栏即可组合多个按钮，也可混入复选框操作。

组件层级上，cube-toolbar由cube-toolbar-item（内部再组合cube-button与cube-checkbox）构成，源码参见 toolbar.vue 与 toolbar-item.vue。

基础使用：用 actions 定义一组操作

最简用法是把每个操作项作为对象传入actions数组，并在@click中统一处理点击：

<cube-toolbar :actions="actions" @click="clickHandler"></cube-toolbar>

export default { data() { return { money: 10, actions: [ { text: '完成订单', action: 'showText' }, { text: '打车来接', checked: false, type: 'checkbox' }, { text: '一口价<span class="orange">10元</span>', action: 'moreMoney' } ] } }, methods: { showText(item) { this.$createToast({ type: 'correct', txt: 'clicked ' + item.text, time: 1000 }).show() }, moreMoney(item) { this.money += 10 item.text = '一口价<span class="orange">' + this.money + '元</span>' }, clickHandler(item) { if (item.action) { thisitem.action } } } }

.orange color: #fc9153

关键点说明：

每个操作项的text支持 HTML 字符串（文档明确标注 "support html string"），示例中通过<span class="orange">10元</span>高亮价格文案，配合上述 stylus 将价格渲染为品牌橙色#fc9153。从 toolbar-item.vue 的实现可见，非 checkbox 类型的文本会走<span v-html="action.text">渲染，因此 HTML 标签会被真正解析，而不是以纯文本输出。
action字段只是你自定义的"指令名"，并不会被组件直接调用。官方推荐的模式是在clickHandler中读取item.action，再调用组件外部对应名称的方法（如thisitem.action），这样操作项与业务逻辑解耦，新增操作只需加一条配置。
点击事件会回传当前操作项对象item，因此你可以在回调中直接读取或修改item的字段（如moreMoney中累加金额并重写item.text），实现动态文案。

完整可运行的示例页面位于 example/pages/toolbar.vue，其中还用switch-option演示了动态开关moreActions的写法。

更多操作：moreActions 展开双层工具栏

当传入moreActions时，工具栏会自动在基本操作右侧追加一个"更多"按钮（cubeic-more图标），点击后在上方展开第二层操作列表，形成可展开/收起的双层工具栏：

<cube-toolbar :actions="actions" :more-actions="moreActions" @click="clickHandler"></cube-toolbar>

export default { data() { return { money: 10, actions: [ { text: '完成订单', action: 'showText' }, { text: '打车来接', checked: false, type: 'checkbox' }, { text: '一口价<span class="orange">10元</span>', action: 'moreMoney' } ], moreActions: [ { text: '操作a', action: 'showText' }, { text: '操作b', action: 'showText' }, { text: '操作c', icon: 'cubeic-right', action: 'showText' } ] } }, methods: { showText(item) { this.$createToast({ type: 'correct', txt: 'clicked ' + item.text, time: 1000 }).show() }, moreMoney(item) { this.money += 10 item.text = '一口价<span class="orange">' + this.money + '元</span>' }, clickHandler(item) { if (item.action) { thisitem.action } } } }

.orange color: #fc9153

注意moreActions中的操作项结构与actions完全一致，同样支持text（可含 HTML）、action指令、icon（如示例中的cubeic-right）以及 checkbox 类型。

Props 配置说明

官方文档给出两个顶层 Props：

| 参数 | 说明 | 类型 | 默认值 | 示例 | | - | - | - | - | - | | actions | 定义一组操作 | Array | [] |[{ text: '完成订单' }]| | moreActions | 定义更多的一组操作 | Array | [] |[{ text: '完成订单' }]|

源码 toolbar.vue 中actions类型为Array，默认返回[]；moreActions类型为Array且未声明默认值（传undefined即表示不启用更多操作，见示例页面的:more-actions="more ? moreActions : undefined"写法）。

actions 子配置项

每个操作项支持以下字段：

| 参数 | 说明 | 类型 | 可选值 | 默认值 | | - | - | - | - | - | | type | 类型，包括 button 和 checkbox | String | button/checkbox | button | | text | 文案，支持写入 HTML | String | - | '' | | checked | 当为 checkbox 类型时，checkbox 的初始状态 | Boolean | true/false | false |

结合 Toolbar.d.ts 的类型定义，完整操作项还包含action（自定义指令名）与icon（图标类名，如cubeic-right）两个可选字段：

interface IActions { type?: 'button' | 'checkbox' text?: string checked?: boolean action?: string icon?: string }

checked的实现细节：在 toolbar-item.vue 中，checkbox 类型通过v-model="action.checked"双向绑定，因此你可以在@click回调里读取操作项的checked字段判断勾选状态，也可以外部改写该字段来控制勾选。

事件说明

| 事件名 | 说明 | 参数 | | - | - | - | | click | 点击某一项触发 | 该项 item 的值 | | more-click | 当有更多操作时，点击更多按钮时触发 | 更多操作是否处于显示状态 |

click：点击基本操作项或更多面板中的操作项都会触发，参数是被点击操作项对象。
more-click：仅当存在moreActions时，点击末尾的"更多"按钮触发，参数为true/false表示更多面板当前是展开还是收起。

源码原理：$cubeMore 标记与双层渲染

深入 toolbar.vue 可以看到组件内部的核心逻辑：

computed: { basicActions() { const basicActions = this.actions.slice() this.moreActions && basicActions.push({ icon: 'cubeic-more', $cubeMore: true }) return basicActions } }, methods: { itemClick(action) { if (action.$cubeMore) { this.showMore = !this.showMore this.$emit(EVENT_MORE_CLICK, this.showMore) } else { this.$emit(EVENT_CLICK, action) } } }

要点解析：

basicActions计算属性：复制actions后，若存在moreActions，则在其末尾追加一个内部标记对象{ icon: 'cubeic-more', $cubeMore: true }，这就是渲染在基本操作栏右侧的"更多"按钮。由于$cubeMore是组件内部专用字段，你的业务操作项不会误触发更多逻辑。
itemClick事件分发：所有操作项（基本与更多）共用同一个点击入口，通过判断action.$cubeMore分流——更多按钮切换showMore并触发more-click；其余操作触发click。
模板渲染：模板中moreActions对应的<ul class="cube-toolbar-group-more">使用v-if="moreActions"挂载、v-show="showMore"控制展开收起；第二层面板与基本操作栏之间保留10px间距，并通过cube-toolbar-down伪元素绘制了指向"更多"按钮的小箭头（见 toolbar.vue 样式），展开状态下方还会展示一个小三角，视觉上明确指示面板归属。

按需引入与组件注册

Toolbar 与 Button、Checkbox 绑定注册：src/modules/toolbar/index.js 中定义：

Toolbar.install = function (Vue) { Vue.component(Button.name, Button) Vue.component(Checkbox.name, Checkbox) Vue.component(Toolbar.name, Toolbar) } Toolbar.Button = Button Toolbar.Checkbox = Checkbox

即通过Vue.use(Toolbar)按需注册时，会一并注册其内部依赖的cube-button与cube-checkbox，避免组件内部引用未注册组件；同时暴露Toolbar.Button、Toolbar.Checkbox供二次开发。仓库的构建产物见 lib/toolbar/index.js，对应样式为 lib/toolbar/style.css。

测试验证：渲染与事件行为

单元测试 test/unit/specs/toolbar.spec.js 覆盖了以下关键行为，可作为你理解组件契约的权威参照：

基础渲染：仅传actions时渲染 1 个.cube-toolbar-group，每个操作项生成一个.cube-toolbar-item；button 类型断言.cube-btn文本，checkbox 类型断言.cube-checkbox-label文本。
更多操作渲染：传入moreActions时渲染 2 个.cube-toolbar-group，第二组操作数 = 基本操作数 + 1（末尾的更多按钮）。
事件触发：点击基本操作项触发一次click且参数为该操作项对象；点击末尾更多按钮触发一次more-click且参数为true（展开状态）。

小结

cube-ui Toolbar 以"配置驱动"的方式封装了底部操作栏：actions负责一组操作（button/checkbox 混排、文本支持 HTML），moreActions自动追加"更多"按钮形成双层展开结构；事件侧通过click回传操作项对象、more-click回传展开状态，配合action指令分发模式即可快速接入业务逻辑。若需查看更多组件组合用法，可参考 example/pages/toolbar.vue 与 Toolbar 中文文档。