uView Next
4.0.105

外观

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是否展示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自定义触发

Scss 变量

关于组件 SCSS 变量的用法，请参考 组件 SCSS 变量用法。

变量名默认值说明
$un-action-sheet-description-color$text-color-muted描述文本的颜色
$un-action-sheet-description-font-size$text-sm描述文本的字体大小
$un-action-sheet-description-text-aligncenter描述文本的对齐方式
$un-action-sheet-description-margin18px 15px描述文本的外边距
$un-action-sheet-item-padding15px列表项的内边距
$un-action-sheet-name-font-size$text-lg列表项名称的字体大小
$un-action-sheet-name-color$text-color列表项名称的颜色
$un-action-sheet-name-text-aligncenter列表项名称的对齐方式
$un-action-sheet-subname-font-size$text-base列表项描述文本的字体大小
$un-action-sheet-subname-color$text-color-muted列表项描述文本的颜色
$un-action-sheet-subname-text-aligncenter列表项描述文本的对齐方式
$un-action-sheet-subname-margin-top10px列表项描述文本的上边距
$un-action-sheet-cancel-font-size$text-base取消按钮的字体大小
$un-action-sheet-cancel-color$text-color取消按钮的颜色
$un-action-sheet-cancel-text-aligncenter取消按钮的对齐方式
$un-action-sheet-cancel-padding15px取消按钮的内边距
$un-action-sheet-button-font-weight400按钮的字体粗细
$un-action-sheet-button-font-size$text-base按钮的字体大小
$un-action-sheet-button-color$text-color按钮的颜色
$un-action-sheet-button-line-height22px按钮的行高

数据类型

/**
 * 操作菜单项类型
 * 用于定义操作菜单中的单个选项
 */
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