ActionSheet

17:06

Description

An action sheet that pops up from the bottom on top of ux-popup. Options are described by the list array and support a subText description, a disabled state and per-item colors; a tips hint can be added on top and the bottom cancel button can be turned off. Tapping an option emits click(index) and closes the sheet by default; set asyncClose to keep it open and close it yourself. When list is empty the default slot takes over for custom content.

Compatibility

Platform	Support
App	✅ Supported (tips falls back to 13px when fontSize is omitted; App mis-parses font-size:auto, which collapses the title)
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Configure options via list; click triggers click event.

View source

<template>
    <ux-button @click="show = true">打开操作菜单</ux-button>
    <ux-action-sheet v-model="show" :list="list" @click="onItemClick"></ux-action-sheet>
</template>

<script setup lang="uts">
import type { ActionSheetItem } from '@/uni_modules/uview-pro-x';

const show = ref<boolean>(false);

const list: ActionSheetItem[] = [
    { text: '拍照' },
    { text: '从相册选择' },
    { text: '取消' }
];

function onItemClick(index: number): void {
    uni.showToast({ title: '点击了: ' + index, icon: 'none' });
}
</script>

Tips

Set top tip text via the tips prop.

View source

<template>
    <ux-button @click="show = true">打开操作菜单</ux-button>
    <ux-action-sheet v-model="show" :list="list" :tips="{ text: '选择操作方式' }" @click="onItemClick"></ux-action-sheet>
</template>

<script setup lang="uts">
import type { ActionSheetItem } from '@/uni_modules/uview-pro-x';

const show = ref<boolean>(false);

const list: ActionSheetItem[] = [
    { text: '拍照' },
    { text: '从相册选择' },
    { text: '取消' }
];

function onItemClick(index: number): void {
    uni.showToast({ title: '点击了: ' + index, icon: 'none' });
}
</script>

Sub Text

List items can set subText for description.

View source

<template>
    <ux-button @click="show = true">打开操作菜单</ux-button>
    <ux-action-sheet v-model="show" :list="list" @click="onItemClick"></ux-action-sheet>
</template>

<script setup lang="uts">
import type { ActionSheetItem } from '@/uni_modules/uview-pro-x';

const show = ref<boolean>(false);

const list: ActionSheetItem[] = [
    { text: '拍照', subText: '拍摄一张新照片' },
    { text: '从相册选择', subText: '从手机相册中选择' }
];

function onItemClick(index: number): void {
    uni.showToast({ title: '点击了: ' + index, icon: 'none' });
}
</script>

Disabled Item

Set disabled=true on list item to disable click.

View source

<template>
    <ux-button @click="show = true">打开操作菜单</ux-button>
    <ux-action-sheet v-model="show" :list="list" @click="onItemClick"></ux-action-sheet>
</template>

<script setup lang="uts">
import type { ActionSheetItem } from '@/uni_modules/uview-pro-x';

const show = ref<boolean>(false);

const list: ActionSheetItem[] = [
    { text: '编辑' },
    { text: '删除', disabled: true },
    { text: '分享' }
];

function onItemClick(index: number): void {
    uni.showToast({ title: '点击了: ' + index, icon: 'none' });
}
</script>

No Cancel Button

cancel-btn=false hides the bottom cancel button.

View source

<template>
    <ux-button @click="show = true">打开操作菜单</ux-button>
    <ux-action-sheet v-model="show" :list="list" :cancel-btn="false" @click="onItemClick"></ux-action-sheet>
</template>

<script setup lang="uts">
import type { ActionSheetItem } from '@/uni_modules/uview-pro-x';

const show = ref<boolean>(false);

const list: ActionSheetItem[] = [
    { text: '拍照' },
    { text: '从相册选择' }
];

function onItemClick(index: number): void {
    uni.showToast({ title: '点击了: ' + index, icon: 'none' });
}
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom style for the root node	UTSJSONObject	-	-
customClass	Custom class for the root node	string	''	-
maskCloseAble	Whether the sheet can be closed by tapping the mask	boolean	true	-
list	Option list; each item supports text / subText / disabled / color / fontSize	ActionSheetItem[]	-	-
tips	Top hint supporting text / color / fontSize	ActionSheetTips	-	-
cancelBtn	Whether to show the bottom cancel button	boolean	true	-
safeAreaInsetBottom	Whether to apply bottom safe-area inset	boolean	true	-
modelValue	Controls sheet visibility (v-model)	boolean	false	-
borderRadius	Sheet corner radius, in px	string | number	0	-
zIndex	Stacking z-index	string | number	0	-
cancelText	Cancel button text; falls back to the built-in text when omitted	string	''	-
color	Option text color	string	''	-
fontSize	Option text size, in px	string | number	'16px'	-
asyncClose	Whether tapping an option only emits click and lets the caller close the sheet	boolean	false	-

Events

Event	Description	Params	Version
click	Emitted when an option is tapped; index is the option index	index: number	-
close	Emitted when the cancel button is tapped	-	-

Slots

Slot	Description	Version
default	Custom content shown when list is empty	-

Notes

1. tips is usually passed as a partial object (e.g. only text): when fontSize is missing the component falls back to 13px. If you pass fontSize yourself, App mis-parses font-size:auto and collapses the title, so pass a value with a unit (e.g. 13px).
2. asyncClose defaults to false: tapping an option emits click(index) and closes the sheet at the same time. Set it to true to emit only click and write v-model back yourself (e.g. to await a second confirmation).
3. An option with disabled: true swallows the tap: no click is emitted and its text is greyed out (via lightColor).
4. When list is non-empty it renders from list; only when list is empty (length === 0) does the default slot render. The two never appear together.
5. The cancel button text comes from cancel-text, falling back to the built-in text when omitted; cancel-btn=false hides both the cancel button and the 6px divider above it.
6. Tapping the cancel button only closes the sheet and emits close; it does not emit click (no index is passed).
7. The component is built on ux-popup (mode="bottom", length="auto"); tap-to-close on the mask is controlled by maskCloseAble, which is on by default.