SwipeAction

17:06

Description

A swipe cell container: the content sits flush left by default, the action buttons are absolutely positioned on the right, and swiping the content left reveals them. The drag follows your finger (the transition duration is 0 while dragging); on release, whether the displacement exceeds "total button width / 4" decides between opening and springing back, and the open displacement equals the total button width (btn-width × options.length).

options configures multiple buttons (text, background color, text color); the show prop or the ref open/close methods give controlled open/close; disabled disables swiping; vibrateShort fires one short vibration when opening; and index tells which cell a click/open/close event came from.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Swipe left on content to reveal delete button; click triggers click event.

View source

<template>
    <ux-swipe-action :options="options" @click="onBtnClick">
        <view class="content">
            <text>左滑试试</text>
        </view>
    </ux-swipe-action>
</template>

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

const options: SwipeActionOption[] = [
    {
        text: '删除',
        style: { backgroundColor: '#fa3534' }
    }
];

function onBtnClick(index: number | string, btnIndex: number): void {
    uni.showToast({ title: '点击了第' + btnIndex + '个按钮', icon: 'none' });
}
</script>

<style scoped>
.content {
    padding: 15px;
    background-color: #ffffff;
}
</style>

Multiple Buttons

Configure multiple buttons via options array with custom colors and text.

View source

<template>
    <ux-swipe-action :options="options" @click="onBtnClick">
        <view class="content">
            <text>左滑出现多个按钮</text>
        </view>
    </ux-swipe-action>
</template>

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

const options: SwipeActionOption[] = [
    {
        text: '收藏',
        style: { backgroundColor: '#ff9900' }
    },
    {
        text: '删除',
        style: { backgroundColor: '#fa3534' }
    }
];

function onBtnClick(index: number | string, btnIndex: number): void {
    uni.showToast({ title: '点击了第' + btnIndex + '个按钮', icon: 'none' });
}
</script>

<style scoped>
.content {
    padding: 15px;
    background-color: #ffffff;
}
</style>

Disabled

When disabled=true, swipe is disabled.

View source

<template>
    <ux-swipe-action :options="options" :disabled="true">
        <view class="content">
            <text>已禁用滑动</text>
        </view>
    </ux-swipe-action>
</template>

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

const options: SwipeActionOption[] = [
    {
        text: '删除',
        style: { backgroundColor: '#fa3534' }
    }
];
</script>

<style scoped>
.content {
    padding: 15px;
    background-color: #ffffff;
}
</style>

Controllable

Control open/close via show prop or ref open/close methods.

View source

<template>
    <ux-swipe-action ref="swipeRef" :options="options" :show="show" @open="onOpen" @close="onClose">
        <view class="content">
            <text>点击按钮展开/收起</text>
        </view>
    </ux-swipe-action>
    <ux-button size="small" @click="toggle">{{ show ? '收起' : '展开' }}</ux-button>
</template>

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

const options: SwipeActionOption[] = [
    {
        text: '删除',
        style: { backgroundColor: '#fa3534' }
    }
];

const show = ref<boolean>(false);
const swipeRef = ref<any>(null);

function toggle(): void {
    show.value = !show.value;
}

function onOpen(index: number | string): void {
    console.log('open', index);
}

function onClose(index: number | string): void {
    console.log('close', index);
}
</script>

<style scoped>
.content {
    padding: 15px;
    background-color: #ffffff;
}
</style>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom style for the root node	UTSJSONObject	-	-
customClass	Custom class for the root node	string	''	-
index	Identifier used to tell which cell was clicked	number | string	''	-
btnWidth	Button width, in px (default 90)	number | string	90	-
disabled	Whether to disable swiping (default false)	boolean	false	-
show	Whether to open or close the component (default false)	boolean	false	-
bgColor	Background color of the whole component	string	''	-
vibrateShort	Whether to trigger a short device vibration (default false)	boolean	false	-
options	Array form; each entry configures background color and text	SwipeActionOption[]	-	-

Events

Event	Description	Params	Version
click	Fired when a button is tapped	index: number | string, btnIndex: number	-
close	Fired when the component closes	index: number | string	-
content-click	Fired when the content is tapped	index: number | string	-
open	Fired when the component opens	index: number | string	-

Slots

Slot	Description	Version
default	The swipeable content area	-

Notes

1. The open displacement equals the total button width: btn-width × options.length, where btn-width defaults to 90px and is converted to pixels internally (getPxNum + addUnit).
2. The release threshold is one quarter of the total button width: if the displacement exceeds it the cell opens, otherwise it springs back (allBtnWidth / 4 in onTouchEnd).
3. While dragging, the content transition duration is 0ms (following the finger); after release it is 300ms for the spring-back and open animations.
4. disabled=true blocks both touchstart/touchmove/touchend and open(): it can neither be swiped nor opened via show or ref.open().
5. Changes to show drive open/close through a watch, and onMounted opens directly if show is already true.
6. The open/close events fire once only when the state actually flips (guarded by isOpen); repeatedly opening or closing does not re-trigger them.
7. Tapping the content area while open collapses it first and emits content-click; button taps use @click.stop to stop propagation so they do not accidentally trigger the content-area collapse.
8. vibrateShort fires one short vibration only on the closed-to-open transition, and it depends on device/system vibration support.
9. Every button uses btn-width for its width; options[].style.backgroundColor only affects the button background, style.color only affects the button text, and the text is white by default when unset.
10. The root background defaults to the theme's $u.color.bgWhite and can be overridden by bg-color; the content layer's background is fixed to $u-bg-white with z-index:1, so it always sits above the buttons on the right.