企业官网建设流程全解析

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

ActionSheet（操作列表）是 cube-ui 中基于create-api实现的弹出层组件，用于在移动端页面底部展示一组可点击的操作项，并提供默认列表与 Picker 两种可切换的视觉样式。本文以 ActionSheet 官方文档 为主体，结合 组件源码、模块注册代码 与 单元测试，完整讲解其 API 调用方式、全部配置项、事件与实例方法，并深入解析其基于cube-popup与混入（mixin）的底层实现。读完本文，你将能在自己的 Vue 项目中熟练使用this.$createActionSheet(...)快速搭建操作列表，并能够按需定制其对齐方式、高亮项与国际化文案。

组件概览：两种样式与 API 式调用

ActionSheet操作列表提供了两种常见的样式：默认的列表样式（顶部标题 + 纵向操作项 + 底部取消按钮），以及 Picker 风格样式（标题居中、取消按钮悬浮于右上角），同时支持对每一项内容进行 HTML、对齐方向与自定义 class 的灵活控制。

与 cube-ui 的Toast、Dialog、Picker等组件一致，ActionSheet基于create-api实现，因此在使用之前，请确保自己了解过 create-api 模块。create-api会在Vue.prototype上增加一个名为$create{camelize(Component.name)}的方法（此处即$createActionSheet），调用后组件实例会被附加到body元素之下，并额外获得show()、hide()与remove()等方法。

从 模块注册代码 可以看到，ActionSheet.install内部同时完成了三件事：注册全局组件、安装国际化（Locale.install）、以及通过 api.js 中的createAPI(Vue, ActionSheet, ['select', 'cancel'], true)注册 API——其中['select', 'cancel']声明了组件对外抛出的事件名，最后一个参数true表示该组件为单例模式。因此，无论你是使用组件标签还是 API 调用，都需要先通过Vue.use(ActionSheet)完成注册。

快速上手：安装与注册

在入口文件中按如下方式引入并注册（也可以从 src/index.js 看到ActionSheet已随 cube-ui 主包一并导出）：

import Vue from 'vue' import { ActionSheet, Style } from 'cube-ui' Vue.use(Style) // 引入基础样式 Vue.use(ActionSheet) // 注册组件与 $createActionSheet API

注册完成后，即可在任意组件内通过模板标签或this.$createActionSheet(config).show()两种方式使用。API 式调用是官方推荐的主用法，配置对象中除events中声明的事件（onSelect、onCancel）会被转换为事件回调外，其余键值都会作为 props 传递给组件。

三种典型使用场景

1. 基本用法

配置标题title与数据列表data即可展示一个最基础的操作列表。注意data中每项的核心字段是content，它是一段 HTML 字符串，除此之外每项还可以配置自定义class与对齐方向align（可选值left、right，不配置时默认居中）。

<cube-button @click="showDefault">操作列表</cube-button>

export default { methods: { showDefault() { this.$createActionSheet({ title: '我是标题~~~', data: [ { content: '<em>align - center</em>', class: 'cube-foo' }, { content: 'align - left', align: 'left' }, { content: 'align - right', align: 'right' } ], onSelect: (item, index) => { this.$createToast({ txt: `Clicked ${item.content}`, time: 1000 }).show() } }).show() } } }

从 组件模板 可以看到，每个操作项通过v-for="(item, index) in data"渲染，item.content使用v-html输出（这就是content支持 HTML 字符串的原因），同时通过:data-align="item.align"与:class="[item.class || '', index === active ? 'cube-action-sheet-item_active' : '']"分别绑定对齐方向、自定义 class 与高亮状态。对齐方向最终由样式表中的&[data-align="left"] { text-align: left }与&[data-align="right"] { text-align: right }规则生效（源码样式）。

2. 高亮设置

通过设置active属性（Number，值为数据项的索引）来控制高亮的是第几个选项，高亮的项会应用cube-action-sheet-item_active类，其文字颜色由主题变量$action-sheet-active-color决定：

<cube-button @click="showActive">ActionSheet - active</cube-button>

export default { methods: { showActive() { this.$createActionSheet({ title: '我是标题~~~', active: 0, data: [ { content: '舒适型' }, { content: '七座商务' }, { content: '豪华型' } ], onSelect: (item, index) => { this.$createToast({ txt: `Clicked ${item.content}`, type: 'correct', time: 1000 }).show() }, onCancel: () => { this.$createToast({ txt: `Clicked canceled`, type: 'warn', time: 1000 }).show() } }).show() } } }

3. Picker 样式设定

pickerStyle属性（Boolean）决定是否使用 Picker 样式。开启后，组件根节点会追加cube-action-sheet_picker类：标题区域变高、列表与取消按钮之间的 6px 间隔区高度变为 0、取消按钮脱离文档流position: absolute悬浮于面板右上角，视觉上与 Picker 选择器的头部布局保持一致（详见 Picker 样式源码）。

<cube-button @click="showPickerStyle">ActionSheet - picker style</cube-button>

export default { methods: { showPickerStyle() { this.$createActionSheet({ title: '我是标题~~~', pickerStyle: true, data: [ { content: '舒适型' }, { content: '七座商务' }, { content: '豪华型' } ], onSelect: (item, index) => { this.$createToast({ txt: `Clicked ${item.content}`, type: 'correct', time: 1000 }).show() }, onCancel: () => { this.$createToast({ txt: `Clicked canceled`, type: 'warn', time: 1000 }).show() } }).show() } } }

以上三个示例的完整可运行版本见 example/pages/action-sheet.vue，其中通过cube-button-group组织了三个触发按钮，并在onSelect/onCancel回调里使用$createToast给出交互反馈。

Props 配置详解

ActionSheet的全部配置项如下表（对应 组件 props 定义）：

| 参数 | 说明 | 类型 | 可选值 | 默认值 | | - | - | - | - | - | | title | 组件的标题 | String | - | '' | | cancelTxt^1.9.9| 取消文案 | String | - | '取消' | | data | 需要展示的数据列表 | Array | - | [] | | active | 高亮第几个选项 | Number | - | -1 | | pickerStyle | Picker 样式 | Boolean | true/false | false | | visible^1.8.1| 显示状态，是否可见。v-model绑定值 | Boolean | true/false | false | | maskClosable^1.9.6| 点击蒙层是否隐藏 | Boolean | true/false | true | | zIndex^1.9.6| 样式 z-index 的值 | Number | - | 100 |

补充说明（来自源码实现）：

• cancelTxt与国际化：组件并未直接以'取消'作为 prop 默认值，而是通过 localeMixin 与计算属性_cancelTxt实现：return this.cancelTxt || this.$t('cancel')（源码）。cancel文案在 zh-CN.js 与 en-US.js 中分别定义为'取消'与'Cancel'，因此未显式传入cancelTxt时会随全局语言环境自动切换。
• visible与v-model：该 prop 来自 visibilityMixin，混入中以visible为model.prop、toggle为model.event声明了 v-model 支持，并用内部数据isVisible承接显示状态，避免外部未绑定响应式属性时切换失效。
• maskClosable与zIndex：这两个 prop 由 popupMixin 提供（zIndex默认 100、maskClosable默认 false），组件内部对maskClosable显式覆盖为默认true。点击蒙层时的行为见maskClick()：this.maskClosable && this.cancel()（源码），即只有允许蒙层关闭时才会触发隐藏与cancel事件。

data子配置项

data数组中的每一项支持以下子字段：

| 参数 | 说明 | 类型 | 可选值 | 默认值 | | - | - | - | - | - | | content | 展示的内容 | String | 任意 HTML 字符串 | '' | | align | 内容对齐方向 | String | left/right | '' | | class | 自定义 class | String | - | '' |

• content通过v-html渲染，因此可以直接内嵌标签、图标甚至带样式的富文本；
• align不传时默认居中；传'left'/'right'时对应项文本左/右对齐；
• class会被合并到该项li的 class 列表中，可用于覆盖字号、颜色等局部样式。

事件与实例方法

事件

| 参数 | 说明 | 参数1 | 参数2 | | - | - | - | - | | cancel | 点击取消 | - | - | | select | 点击某项 | 点击项 item，即 data[index] | 点击项的索引值 index |

事件由 组件 methods 抛出：itemClick(item, index)先执行this.hide()关闭面板，再this.$emit('select', item, index)；cancel()同理，先hide()再this.$emit('cancel')。由于['select', 'cancel']已声明在createAPI的 events 参数中，API 式调用时对应的回调需写成onSelect、onCancel（而非作为 props 传入）。

实例方法

| 方法名 | 说明 | | - | - | | show | 显示 | | hide | 隐藏 |

show与hide由visibilityMixin提供，本质是切换内部isVisible状态；配合外层cube-action-sheet-fade与内层cube-action-sheet-move两个<transition>，可实现遮罩淡入淡出与面板从底部上移的联动动画（动画样式）。此外，通过createAPI实例化的实例还会被附加remove方法，调用后销毁实例并从body下移除，详见 create-api 文档。

源码原理：基于 cube-popup 的层级结构

ActionSheet本身并未自建蒙层与定位逻辑，而是直接复用了cube-popup。从 组件模板 可以看到其结构：

• 外层<cube-popup type="action-sheet" :center="false" :mask="true" :z-index="zIndex" v-show="isVisible" @mask-click="maskClick">：负责全屏蒙层、z-index 层级与点击蒙层事件；
• 面板内部包含标题h1.cube-action-sheet-title、选项列表ul.cube-action-sheet-list、间隔区div.cube-action-sheet-space（Picker 样式下高度为 0）与取消按钮div.cube-action-sheet-cancel；
• 面板通过@click.stop阻止点击冒泡，避免误触发蒙层关闭。

组件还混入了visibilityMixin（visible/show/hide）、popupMixin（zIndex/maskClosable）与localeMixin（取消文案国际化），这种"功能横向切分到 mixin、UI 复用一个通用 Popup"的设计是 cube-ui 弹出层类组件（Toast、Picker、Dialog等）的通用模式，理解它有助于你举一反三地掌握整族组件。

行为验证：来自单元测试的证据

仓库的 ActionSheet 测试用例 对上述行为给出了完整验证，可以作为理解组件契约的可靠参考：

• 渲染测试：验证标题文本、cube-action-sheet-item数量、active高亮类（cube-action-sheet-item_active）以及无data时不渲染任何选项（L19-L51）；
• Picker 样式测试：验证根节点包含cube-action-sheet_picker类，且间隔区cube-action-sheet-space高度为 0（L52-L83）；
• 事件测试：点击选项后isVisible变为 false 且select回调收到data[0]；点击取消按钮后cancel回调被调用一次（L85-L123）；
• API 测试：验证$createActionSheet创建后实例挂载于document.body、onSelect/onCancel回调生效、remove()后实例从body移除（L133-L205）。

小结与使用建议

综上，cube-uiActionSheet的核心使用要点可归纳为：

1. 先注册再调用：Vue.use(ActionSheet)后，使用this.$createActionSheet(config).show()获得挂载在body下的组件实例；
2. 善用data子配置：content支持任意 HTML，align控制对齐，class支持局部定制；
3. active控制默认高亮，pickerStyle一键切换为 Picker 风格；
4. 事件回调名为onSelect、onCancel，选择或取消后组件会自动隐藏，无需手动调用hide()；
5. 文案与视觉可通过cancelTxt覆盖取消文案，通过maskClosable、zIndex控制蒙层行为与层级，主题色则受 主题变量 中$action-sheet-*系列变量影响。

需要更深入了解 API 式组件的通用机制（如$props/$events响应式配置、single单例语义、remove()销毁时机），请继续阅读 create-api 模块文档；完整的 ActionSheet 类型定义可参考 types/components/ActionSheet.ts，便于在 TypeScript 项目中获得完善的类型提示。

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