外观
ActionSheet 操作菜单
约 2848 字大约 9 分钟
2025-10-31
本组件用于从底部弹出一个操作菜单,供用户选择并返回结果。
本组件功能类似于uni的uni.showActionSheetAPI,配置更加灵活,所有平台都表现一致。
普通使用
最基础的用法,展示一个简单的操作菜单,包含多个选项。用户可以点击任一选项执行相应操作。
<template>
<un-page>
<un-action-sheet
:show="show"
@close="close"
@select="select"
:actions="actions"
></un-action-sheet>
<un-button type="primary" @click="handleClick">打开操作菜单</un-button>
</un-page>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import type { UnActionSheetAction, UnActionSheetSelectEvent } from '@/uni_modules/uview-unix'
const show = ref(false)
const actions: UnActionSheetAction[] = [
{ name: '选项1', color: '#2979ff' },
{ name: '选项2', color: '#2979ff' },
{ name: '选项3', color: '#2979ff', subname: '描述文本' }
]
const handleClick = () => {
show.value = true
}
const select = (event: UnActionSheetSelectEvent) => {
show.value = false
uni.showToast({
title: `已选择:${event.index}`,
icon: 'none'
})
}
</script>设置状态
展示如何为操作菜单中的选项设置不同状态,包括正常状态、加载状态和禁用状态,以提供更丰富的交互体验。
<template>
<un-page>
<un-action-sheet
:show="show"
@close="close"
@select="select"
:actions="actions"
></un-action-sheet>
<un-button type="primary" @click="handleClick">打开状态菜单</un-button>
</un-page>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import type { UnActionSheetAction, UnActionSheetSelectEvent } from '@/uni_modules/uview-unix'
const show = ref(false)
const actions: UnActionSheetAction[] = [
{ name: '选项1', color: '#2979ff' },
{ loading: true, name: '加载中...' },
{ name: '选项被禁用', disabled: true, color: '#c8c9cc' }
]
const handleClick = () => {
show.value = true
}
const select = (event: UnActionSheetSelectEvent) => {
show.value = false
uni.showToast({
title: `已选择:${event.index}`,
icon: 'none'
})
}
const close = () => {
show.value = false
}
</script>显示取消按钮
在操作菜单底部显示一个取消按钮,允许用户取消操作而不选择任何选项。点击遮罩层也可以关闭菜单。
<template>
<un-page>
<un-action-sheet
:show="show"
@close="close"
@select="select"
:actions="actions"
cancelText="取消"
></un-action-sheet>
<un-button type="primary" @click="handleClick">打开带取消按钮菜单</un-button>
</un-page>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import type { UnActionSheetAction, UnActionSheetSelectEvent } from '@/uni_modules/uview-unix'
const show = ref(false)
const actions: UnActionSheetAction[] = [
{ name: '选项1', color: '#2979ff' },
{ name: '选项2', color: '#2979ff' },
{ name: '选项3', color: '#2979ff' }
]
const handleClick = () => {
show.value = true
}
const select = (event: UnActionSheetSelectEvent) => {
show.value = false
uni.showToast({
title: `已选择:${event.index}`,
icon: 'none'
})
}
const close = () => {
show.value = false
}
</script>描述内容
在操作菜单中添加标题和描述文本,为用户提供更多上下文信息,帮助他们更好地理解每个选项的用途。
<template>
<un-page>
<un-action-sheet
:show="show"
@close="close"
@select="select"
:actions="actions"
description="请选择您需要的操作,每个选项都有不同的功能"
title="操作提示"
></un-action-sheet>
<un-button type="primary" @click="handleClick">打开带描述菜单</un-button>
</un-page>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import type { UnActionSheetAction, UnActionSheetSelectEvent } from '@/uni_modules/uview-unix'
const show = ref(false)
const actions: UnActionSheetAction[] = [
{ name: '选项1', color: '#2979ff' },
{ name: '选项2', color: '#2979ff' },
{ name: '选项3', color: '#2979ff' }
]
const handleClick = () => {
show.value = true
}
const select = (event: UnActionSheetSelectEvent) => {
show.value = false
uni.showToast({
title: `已选择:${event.index}`,
icon: 'none'
})
}
const close = () => {
show.value = false
}
</script>显示标题
显示带有标题的操作菜单,并设置圆角样式,使界面更加美观。同时展示如何使用插槽自定义内容区域。
<template>
<un-page>
<un-action-sheet
:show="show"
@close="close"
@select="select"
:actions="actions"
title="操作提示"
>
<view class="custom-content">
<text class="title">操作提示</text>
<text class="desc">这是一段通过slot传入的内容,您可以在此自定义操作面板</text>
<un-button type="primary" size="small" @click="close">确定</un-button>
</view>
</un-action-sheet>
<un-button type="primary" @click="handleClick">打开带标题菜单</un-button>
</un-page>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import type { UnActionSheetAction, UnActionSheetSelectEvent } from '@/uni_modules/uview-unix'
const show = ref(false)
const actions: UnActionSheetAction[] = [
{ name: '选项1', color: '#2979ff' },
{ name: '选项2', color: '#2979ff' },
{ name: '选项3', color: '#2979ff' }
]
const handleClick = () => {
show.value = true
}
const select = (event: UnActionSheetSelectEvent) => {
show.value = false
uni.showToast({
title: `已选择:${event.index}`,
icon: 'none'
})
}
const close = () => {
show.value = false
}
</script>
<style lang="scss" scoped>
.custom-content {
padding: 20px;
display: flex;
flex-direction: column;
align-items: center;
.title {
font-size: 18px;
font-weight: bold;
margin-bottom: 10px;
color: #303133;
}
.desc {
font-size: 14px;
color: #909399;
margin-bottom: 20px;
text-align: center;
line-height: 1.5;
}
}
</style>微信开放能力
展示如何在操作菜单中集成微信开放能力,例如获取用户信息。此功能仅在微信小程序环境中可用,其他平台会显示提示信息。
<template>
<un-page>
<un-action-sheet
:show="show"
@close="close"
@select="select"
:actions="actions"
title="微信开放能力"
@getuserinfo="getuserinfo"
></un-action-sheet>
<un-button type="primary" @click="handleClick">打开微信能力菜单</un-button>
</un-page>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import type { UnActionSheetAction, UnActionSheetSelectEvent } from '@/uni_modules/uview-unix'
const show = ref(false)
const actions: UnActionSheetAction[] = [
{ name: '获取用户信息', openType: 'getUserInfo', color: '#ccc' }
]
const handleClick = () => {
show.value = true
}
const select = (event: UnActionSheetSelectEvent) => {
show.value = false
uni.showToast({
title: `已选择:${event.index}`,
icon: 'none'
})
}
const close = () => {
show.value = false
}
const getuserinfo = (res: any) => {
// 处理用户信息获取
}
</script>超出滚动
当选项数量较多时,可以通过设置高度使操作菜单内容区域可滚动
<template>
<un-page>
<un-action-sheet
:show="show"
@close="close"
@select="select"
:actions="actions"
title="超出滚动"
height="300"
></un-action-sheet>
<un-button type="primary" @click="handleClick">打开滚动菜单</un-button>
</un-page>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import type { UnActionSheetAction, UnActionSheetSelectEvent } from '@/uni_modules/uview-unix'
const show = ref(false)
const actions: UnActionSheetAction[] = [
{ name: '拍照', color: '#2979ff', subname: '使用相机拍摄' },
{ name: '从相册选择', color: '#2979ff', subname: '从手机相册选择' },
{ name: '录制视频', color: '#2979ff', subname: '录制一段视频' },
{ name: '语音输入', color: '#2979ff', subname: '使用语音输入' },
{ name: '文件选择', color: '#2979ff', subname: '从文件系统选择' },
{ name: '位置信息', color: '#2979ff', subname: '获取当前位置' },
{ name: '联系人', color: '#2979ff', subname: '选择联系人' },
{ name: '更多选项', color: '#2979ff', subname: '查看更多选项' }
]
const handleClick = () => {
show.value = true
}
const select = (event: UnActionSheetSelectEvent) => {
show.value = false
uni.showToast({
title: `已选择:${event.index}`,
icon: 'none'
})
}
const close = () => {
show.value = false
}
</script>使用 JavaScript 打开
展示如何通过编程方式调用组件的open方法来打开操作菜单,而不是通过v-model绑定。这种方式更加灵活,可以在需要时动态配置选项。
<template>
<un-page>
<un-action-sheet
ref="actionSheetRef"
:show="show"
@close="close"
@select="select"
:actions="actions"
></un-action-sheet>
<un-button type="primary" @click="handleClick">使用JS打开菜单</un-button>
</un-page>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import type { UnActionSheetAction, UnActionSheetSelectEvent, UnActionSheetOptions, UnActionSheetComponentPublicInstance } from '@/uni_modules/uview-unix'
const show = ref(false)
const actions: UnActionSheetAction[] = [
{ name: '选项1', color: '#2979ff' },
{ name: '选项2', color: '#2979ff' },
{ name: '选项3', color: '#2979ff', subname: '描述文本' }
]
const actionSheetRef = ref<UnActionSheetComponentPublicInstance | null>(null)
const handleClick = () => {
const config: UnActionSheetOptions = {
actions: actions,
closeOnClickOverlay: true,
}
actionSheetRef.value?.open(config)
}
const select = (event: UnActionSheetSelectEvent) => {
show.value = false
uni.showToast({
title: `已选择:${event.index}`,
icon: 'none'
})
}
const close = () => {
show.value = false
}
</script>API
Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| show | 是否展示 | Boolean | false |
| title | 设置标题 | string | - |
| titleStyle | 自定义样式弹窗标题样式 | object | string | - |
| closeable | 是否显示关闭图标 | Boolean | false |
| description | 选项上方的描述信息 | string | - |
| actions | 按钮的文字数组 | UnActionSheetAction[] | [ ] |
| cancelText | 取消按钮的文字 | string | - |
| closeOnClickAction | 点击菜单项时是否关闭弹窗 | Boolean | true |
| safeAreaInsetBottom | 是否开启底部安全区适配 | Boolean | true |
| openType | 小程序的打开方式 | string | - |
| closeOnClickOverlay | 点击遮罩是否允许关闭 | Boolean | true |
| height | 设置高度,默认不限制,超出后自动滚动 | string | number | - |
| round | 圆角值 | string | number | 10 |
| lang | 指定返回用户信息的语言 | string | en |
| sessionFrom | 会话来源(仅微信小程序有效) | string | - |
| sendMessageTitle | 会话内消息卡片标题 | string | - |
| sendMessagePath | 会话内消息卡片点击跳转小程序路径 | string | - |
| sendMessageImg | 会话内消息卡片图片 | string | - |
| showMessageCard | 是否显示会内消息卡片 | Boolean | false |
| appParameter | 打开 APP 时传递的参数 | string | - |
| customStyle | 自定义样式 | string | object | {} |
Events
| 事件名 | 说明 | 类型 |
|---|---|---|
| select | 点击列表项时触发 | Function |
| close | 点击取消按钮时触发 | Function |
| getuserinfo | 获取用户信息回调 | Function |
| contact | 客服消息回调 | Function |
| getphonenumber | 获取用户手机号回调 | Function |
| chooseavatar | 选择头像回调 | Function |
| error | 使用开放能力时发生错误的回调 | Function |
| launchapp | 打开 APP 成功的回调 | Function |
| opensetting | 打开授权设置页后回调 | Function |
Slot
| 名称 | 说明 |
|---|---|
| trigger | 自定义触发 |
| default | 自定义触发 |
Scss 变量
关于组件 SCSS 变量的用法,请参考 组件 SCSS 变量用法。
| 变量名 | 默认值 | 说明 |
|---|---|---|
| $un-action-sheet-description-color | $text-color-muted | 描述文本的颜色 |
| $un-action-sheet-description-font-size | $text-sm | 描述文本的字体大小 |
| $un-action-sheet-description-text-align | center | 描述文本的对齐方式 |
| $un-action-sheet-description-margin | 18px 15px | 描述文本的外边距 |
| $un-action-sheet-item-padding | 15px | 列表项的内边距 |
| $un-action-sheet-name-font-size | $text-lg | 列表项名称的字体大小 |
| $un-action-sheet-name-color | $text-color | 列表项名称的颜色 |
| $un-action-sheet-name-text-align | center | 列表项名称的对齐方式 |
| $un-action-sheet-subname-font-size | $text-base | 列表项描述文本的字体大小 |
| $un-action-sheet-subname-color | $text-color-muted | 列表项描述文本的颜色 |
| $un-action-sheet-subname-text-align | center | 列表项描述文本的对齐方式 |
| $un-action-sheet-subname-margin-top | 10px | 列表项描述文本的上边距 |
| $un-action-sheet-cancel-font-size | $text-base | 取消按钮的字体大小 |
| $un-action-sheet-cancel-color | $text-color | 取消按钮的颜色 |
| $un-action-sheet-cancel-text-align | center | 取消按钮的对齐方式 |
| $un-action-sheet-cancel-padding | 15px | 取消按钮的内边距 |
| $un-action-sheet-button-font-weight | 400 | 按钮的字体粗细 |
| $un-action-sheet-button-font-size | $text-base | 按钮的字体大小 |
| $un-action-sheet-button-color | $text-color | 按钮的颜色 |
| $un-action-sheet-button-line-height | 22px | 按钮的行高 |
数据类型
/**
* 操作菜单项类型
* 用于定义操作菜单中的单个选项
*/
type UnActionSheetAction = {
name: string; // 菜单项名称
subname?: string; // 菜单项描述文本
disabled?: boolean; // 是否禁用当前项,默认false
loading?: boolean; // 是否显示加载状态,默认false
fontSize?: string | number; // 字体大小
openType?: string; // 小程序开放能力
color?: string; // 字体颜色
}
/**
* 操作菜单错误类型
* 用于表示操作菜单失败时的错误信息
*/
type UnActionSheetFail = {
errCode: number; // 错误代码
errSubject: string; // 错误主题
errMsg: string; // 错误信息
}
/**
* 操作菜单选择事件类型
* 用于表示选择菜单项时的事件参数
*/
type UnActionSheetSelectEvent = {
index: number; // 选中项的索引
item: UnActionSheetAction; // 选中的菜单项对象
}
/**
* 操作菜单配置选项类型
* 用于配置操作菜单的显示和行为
*/
type UnActionSheetOptions = {
title?: string; // 操作菜单标题
titleStyle?: object; // 弹窗标题样式
description?: string; // 选项上方的描述信息
actions: UnActionSheetAction[]; // 菜单项数组
cancelText?: string; // 取消按钮的文字
closeable?: boolean; // 是否显示关闭图标,默认false
closeOnClickAction?: boolean; // 点击菜单项时是否关闭弹窗,默认true
safeAreaInsetBottom?: boolean; // 处理底部安全区,默认true
openType?: string; // 小程序的打开方式
closeOnClickOverlay?: boolean; // 点击遮罩是否允许关闭,默认true
round?: string | number; // 圆角值,默认10
height?: string | number; // 高度
lang?: string; // 指定返回用户信息的语言,默认'en'
sessionFrom?: string; // 会话来源,openType="contact"时有效
sendMessageTitle?: string; // 会话内消息卡片标题,openType="contact"时有效
sendMessagePath?: string; // 会话内消息卡片点击跳转小程序路径,openType="contact"时有效
sendMessageImg?: string; // 会话内消息卡片图片,openType="contact"时有效
showMessageCard?: boolean; // 是否显示会内消息卡片,openType="contact"时有效,默认false
appParameter?: string; // 打开APP时,向APP传递的参数,openType=launchApp时有效
success?: () => void; // 打开成功后的回调
cancel?: () => void; // 关闭或取消后的回调
fail?: (result: UnActionSheetFail) => void; // 失败后的回调
}