SwipeAction 滑动单元格

17:06

说明

滑动单元格容器：内容区默认贴左显示，操作按钮绝对定位在右侧，左滑内容区即露出按钮。手指拖动跟手（拖动期间过渡时长为 0），松手后按位移是否超过「按钮总宽 / 4」决定展开还是回弹，展开位移等于按钮总宽（btn-width × options.length）。

通过 options 可配置多个按钮（文字、背景色、文字色），show 属性或 ref 的 open/close 方法可受控开关，disabled 禁止滑动，vibrateShort 在展开时触发一次轻震，index 用于在 click/open/close 事件里区分是哪一个单元格。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

左滑内容区域显示删除按钮，点击按钮触发 click 事件。

查看源码

<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>

多个按钮

options 数组配置多个按钮，可设置不同颜色和文字。

查看源码

<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=true 时禁止滑动操作。

查看源码

<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>

可控模式

通过 show 属性或 ref 调用 open/close 方法控制开关。

查看源码

<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

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
index	标识符，点击时候用于区分点击了哪一个	number | string	''	-
btnWidth	按钮宽度，单位px（默认90）	number | string	90	-
disabled	是否禁止滑动（默认false）	boolean	false	-
show	打开或者关闭组件（默认false）	boolean	false	-
bgColor	整个组件背景颜色	string	''	-
vibrateShort	是否使手机发生短促震动（默认false）	boolean	false	-
options	数组形式，可以配置背景颜色和文字	SwipeActionOption[]	-	-

Events

事件名	说明	回调参数	版本
click	点击按钮时触发	index: number | string, btnIndex: number	-
close	组件关闭时触发	index: number | string	-
content-click	点击内容时触发	index: number | string	-
open	组件打开时触发	index: number | string	-

Slots

插槽名	说明	版本
default	滑动内容区域	-

注意事项

1. 展开位移等于按钮总宽：btn-width × options.length，其中 btn-width 默认 90px，内部按像素换算（getPxNum + addUnit）。
2. 松手判定阈值是按钮总宽的 1/4：位移超过阈值即展开，否则回弹（onTouchEnd 里的 allBtnWidth / 4）。
3. 拖动期间内容区过渡时长为 0ms（跟手），松手后为 300ms，用于回弹与展开动画。
4. disabled=true 会同时屏蔽 touchstart/touchmove/touchend 与 open()：既不能滑，也无法用 show 或 ref.open() 打开。
5. show 变化经 watch 驱动 open/close，onMounted 时若 show 已为 true 会直接展开。
6. open/close 事件只在状态真正翻转时派发一次（isOpen 守卫），重复打开或关闭不会重复触发。
7. 点击内容区在展开状态下会先收起，并派发 content-click；按钮点击用 @click.stop 阻止冒泡，避免误触内容区的收起逻辑。
8. vibrateShort 只在「由关到开」那一次触发轻震，且依赖设备/系统支持震动。
9. 按钮宽度统一取 btn-width；options[].style.backgroundColor 只作用于按钮背景，style.color 作用于按钮文字，未配置时文字默认白色。
10. 根节点背景色默认取主题 $u.color.bgWhite，可被 bg-color 覆盖；内容层背景固定 $u-bg-white 且 z-index:1，始终盖在右侧按钮之上。