uView Next
4.1.6

外观

ActionSheet 操作菜单

约 2481 字大约 8 分钟

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是否展示Booleanfalse
title设置标题string-
titleStyle自定义样式弹窗标题样式object | string-
closeable是否显示关闭图标Booleanfalse
description选项上方的描述信息string-
actions按钮的文字数组UnActionSheetAction[][ ]
cancelText取消按钮的文字string-
closeOnClickAction点击菜单项时是否关闭弹窗Booleantrue
safeAreaInsetBottom是否开启底部安全区适配Booleantrue
openType小程序的打开方式string-
closeOnClickOverlay点击遮罩是否允许关闭Booleantrue
height设置高度，默认不限制，超出后自动滚动string | number-
round圆角值string | number10
lang指定返回用户信息的语言stringen
sessionFrom会话来源（仅微信小程序有效）string-
sendMessageTitle会话内消息卡片标题string-
sendMessagePath会话内消息卡片点击跳转小程序路径string-
sendMessageImg会话内消息卡片图片string-
showMessageCard是否显示会内消息卡片Booleanfalse
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自定义触发

数据类型

/**
 * 操作菜单项类型
 * 用于定义操作菜单中的单个选项
 */
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; // 失败后的回调
}

Copyright © 2026 uView Next