更新记录

0.0.1（2025-07-11）

0.0.1

平台兼容性

uni-app(4.55)

uni-app x(4.55)

q-cardFlyOut 卡片飞出组件

滑动卡片（Tinder 风格）组件，可支持 左右/上下 四个方向拖拽飞出，常用于推荐、刷卡等场景、类似于 探探 的交互风格。

快速开始

<template>
  <view class="page">
    <CardFlyOut
      :list="cards"
      :visible="3"
      :thresholdRate="0.15"
      :loadMoreOffset="4"
      width="750rpx"
      height="900rpx"
      :directions="['left', 'right']"
      @swipe="handleSwipe"
      @loadMore="getMoreCards"
      @cardClick="handleCardClick"
    >
      <!-- 默认插槽：卡片内容 -->
      <template #default="{ item, index }">
        <image :src="item.cover" mode="aspectFill" style="width: 100%; height: 100%; border-radius: 24rpx" />
      </template>

      <!-- footer 插槽：可放操作按钮等 -->
      <template #footer>
        <view class="btn-group">
          <button @click="swipeLeft">不喜欢</button>
          <button @click="swipeRight">喜欢</button>
        </view>
      </template>
    </CardFlyOut>
  </view>
</template>

<script>
import CardFlyOut from '@/components/CardFlyOut/CardFlyOut.vue';

export default {
  components: { CardFlyOut },
  data() {
    return {
      cards: [
        { id: 1, cover: 'https://example.com/img1.jpg' },
        { id: 2, cover: 'https://example.com/img2.jpg' },
        { id: 3, cover: 'https://example.com/img3.jpg' }
      ]
    };
  },
  methods: {
    handleSwipe({ direction, currentIndex, currentItem }) {
      console.log('swiped', direction, currentItem);
    },
    getMoreCards() {
      // 拉取更多数据
    },
    handleCardClick({ currentItem }) {
      // 点击当前卡片
    },
    swipeLeft() {
      // 主动触发左滑，可通过修改数据或暴露的 ref 方法实现
    },
    swipeRight() {
      // 同上
    }
  }
};
</script>

> 📌 示例仅演示基本用法，实际请按需调整样式与交互逻辑。

---

## Props

| Prop | Type | Default | 说明 |
| ---- | ---- | ------- | ---- |
| `list` | `Array` | `[]` | 卡片数据列表，对象上 **不会被组件改写**，但会在其中临时添加 `x` 与 `y` 字段以记录位移。 |
| `visible` | `Number` | `5` | 同屏渲染的卡片数量，越大越流畅但越耗性能。 |
| `thresholdRate` | `Number` | `0.1` | 触发飞出的阈值，基于屏幕宽/高的比例。 |
| `loadMoreOffset` | `Number` | `5` | 当剩余卡片数量小于此值时触发 `loadMore` 事件（分页加载）。 |
| `width` | `Number\|String` | `'100%'` | 组件宽度，支持数值（px）或百分比、rpx 等。 |
| `height` | `Number\|String` | `'100%'` | 组件高度，同上。 |
| `directions` | `Array<'left'\|'right'\|'up'\|'down'>` | `['left','right','up','down']` | 允许的滑动方向。 |

---

## Events

| 事件名 | 触发时机 | 回调参数 |
| ------ | -------- | -------- |
| `swipe` | 每次卡片成功飞出后 | `{ direction, currentIndex, currentItem }` |
| `loadMore` | 剩余卡片数量 &lt; `loadMoreOffset` 时 | 无 |
| `cardClick` | 点击当前顶部卡片时 | `{ currentIndex, currentItem }` |

---

## Slots

| Slot | 说明 |
| ---- | ---- |
| _default_ | **必填**。卡片内容，自带 `item`、`index` 两个插槽 prop。 |
| `footer` | 可选。卡片底部区域，通常放操作按钮。 |

---

## 方法

组件目前 **未暴露** 额外 API，如需主动触发滑动可考虑：
1. 直接操作 `list` 数据删除第一条。
2. 在组件基础上二次封装，通过 `ref` 调用内部方法（可自行在源码中暴露）。

---

## 样式定制

组件本身仅提供基础布局与过渡效果，大部分视觉样式请在插槽内实现，以便保持灵活性。

---

## 注意事项

1. 组件会在原始 `list` 中注入临时字段 `x`、`y`，若对此有顾虑请 deep copy 数据。
2. 请勿在 `list` 中直接使用响应式 `ref` 对象，推荐使用普通对象。
3. 若卡片内容存在交互元素（按钮、链接等）需要阻止冒泡，请自行 `@click.stop` 处理。