ListItemActions 组件使用指南

📋 组件概述

组件名称: ListItemActions 文件路径: src/components/list/ListItemActions/index.vue 用途: 列表项的操作按钮组件，支持查看、收藏、删除三种操作

---

✨ 功能特性

1. 按钮类型

按钮	说明	依赖属性
查看	查看文件/产品详情	viewable
收藏	切换收藏状态	collectable
删除	删除列表项	deletable

2. 内置功能

• ✅ 权限检查: 自动检查登录权限（通过 usePermission）
• ✅ 埋点上报: 权限通过后自动发送查看埋点（通过 useEventTracking）
• ✅ 状态管理: 收藏按钮根据 collected 状态切换样式

---

🎯 使用方法

基础用法

<template>
  <ListItemActions
    :viewable="true"
    :collectable="true"
    :deletable="false"
    :collected="item.collected"
    :item-id="item.id"
    @view="handleView"
    @collect="handleCollect"
    @delete="handleDelete"
  />
</template>

<script setup>
const handleView = () => {
  // 权限检查通过后自动触发
  // 不需要手动检查登录状态
  console.log('查看文件')
}

const handleCollect = () => {
  // 收藏状态由组件内部管理
  // 父组件可以监听 collectChanged 事件
  console.log('切换收藏')
}

const handleDelete = () => {
  // 触发删除操作
  console.log('删除项目')
}
</script>

---

📝 Props 说明

属性	类型	默认值	说明
viewable	Boolean	true	是否显示查看按钮
collectable	Boolean	false	是否显示收藏按钮
deletable	Boolean	false	是否显示删除按钮
collected	Boolean	false	是否已收藏（影响收藏按钮样式）
itemId	String	''	关联对象 ID，用于埋点上报

使用示例

<!-- 只显示查看和删除 -->
<ListItemActions
  :viewable="true"
  :deletable="true"
  :item-id="doc123"
  @view="onView"
  @delete="onDelete"
/>

<!-- 三个按钮都显示 -->
<ListItemActions
  :viewable="true"
  :collectable="true"
  :deletable="true"
  :collected="true"
  :item-id="product456"
  @view="onView"
  @collect="onCollect"
  @delete="onDelete"
/>

---

📤 事件说明

@view

触发时机: 权限检查通过后

注意: 如果用户未登录，会先显示登录弹框，登录成功后才会触发此事件

<script setup>
const handleView = (itemData) => {
  console.log('执行查看逻辑:', itemData)
  // 这里调用实际的文件打开逻辑
}
</script>

<template>
  <ListItemActions @view="handleView" />
</template>

@collect

触发时机: 点击收藏按钮时立即触发

<script setup>
const handleCollect = () => {
  // 切换收藏状态
  // 实际的收藏状态由 collected 属性控制
}
</script>

<template>
  <ListItemActions @collect="handleCollect" />
</template>

@delete

触发时机: 点击删除按钮时立即触发

<script setup>
const handleDelete = () => {
  // 执行删除操作
  // 调用删除 API 等
}
</script>

<template>
  <ListItemActions @delete="handleDelete" />
</template>

---

🔐 权限和埋点流程

查看按钮完整流程

用户点击"查看"按钮
    ↓
组件内部: requireAction('view_material', callback)
    ↓
┌─ 未登录 ──────────────────────────────┐
│                                         │
│  1. 检查登录状态                  │
│  2. 显示登录弹框                  │
│  3. ❌ 不发送埋点               │
│  4. ❌ 不触发 @view 事件           │
│                                         │
└─────────────────────────────────────────┘
    ↓
┌─ 已登录 ──────────────────────────────┐
│                                         │
│  1. 权限检查通过                  │
│ 2. ✅ 发送埋点 (trackFileRead)    │
│ 3. ✅ 触发 @view 事件          │
│                                         │
└─────────────────────────────────────────┘
    ↓
父组件收到 @view 事件
    ↓
执行实际业务逻辑（打开文件等）

权限配置

权限配置位于 src/config/permissions.js：

export const ACTION_PERMISSIONS = {
  view_material: {
    permission_type: PermissionType.LOGIN,
    options: {
      content: '请先登录后查看资料',
      confirmText: '去登录'
    }
  }
  }
}

埋点配置

埋点配置位于 src/composables/useEventTracking.js：

• 事件类型: READ_FILE
• 上报时机: 权限检查通过后立即上报
• 上报数据: { type: 'READ_FILE', object_id: itemId }

---

🎨 样式说明

TailwindCSS 类名

类名	作用
flex justify-end gap-[24rpx]	右对齐，24rpx 间距
flex items-center	垂直居中
text-blue-600	蓝色文字（查看按钮）
text-red-500	红色文字（删除按钮）
text-red-500 / text-gray-400	收藏按钮动态颜色
text-[24rpx]	字体大小

自定义样式

如果需要覆盖默认样式，可以在父组件中使用：

<template>
  <ListItemActions
    class="custom-actions"
    @view="handleView"
  />
</template>

<style scoped>
.custom-actions :deep(.text-blue-600) {
  color: #custom-color;
}
</style>

---

⚠️ 注意事项

1. 权限检查是自动的

不需要手动检查登录状态，组件内部已处理：

<!-- ❌ 错误：手动检查权限 -->
<script setup>
import { usePermission } from '@/composables/usePermission'

const { isLoggedIn } = usePermission()

const handleView = () => {
  if (!isLoggedIn()) {
    showToast('请先登录')
    return
  }
  // 继续逻辑
}
</script>

<!-- ✅ 正确：让组件处理 -->
<script setup>
const handleView = () => {
  // 直接执行，权限检查在组件内部
}
</script>

2. 埋点需要 itemId

如果不上报埋点，确保传递了 item-id 属性：

<!-- ❌ 缺少 itemId，埋点不会上报 -->
<ListItemActions @view="handleView" />

<!-- ✅ 正确：提供 itemId -->
<ListItemActions :item-id="'123456'" @view="handleView" />

3. 父组件的 @view 事件参数

@view 事件目前不传递参数，如果需要文件信息，请：

1. 在父组件中维护数据对象引用
2. 或者扩展组件支持传递完整 item 数据

<!-- 父组件示例 -->
<script setup>
const currentItem = ref(null)

const handleView = () => {
  // currentItem 已在组件内部设置
  console.log('查看:', currentItem.value)
}
</script>

<template>
  <ListItemActions @view="handleView" />
</template>

---

🔧 扩展组件

添加新的按钮类型

如果需要添加新的操作按钮（如"分享"、"下载"等）：

1. 在 props 中添加新的控制属性
2. 在模板中添加按钮 UI
3. 添加对应的 emit 和 handler

// 示例：添加分享按钮
const props = defineProps({
  // ... 现有属性
  shareable: {
    type: Boolean,
    default: false
  }
})

const emit = defineEmits({
  // ... 现有事件
  share: null
})

const handleShare = () => {
  emit('share')
}

---

📚 相关文件

• 权限配置: src/config/permissions.js
• 权限 Composable: src/composables/usePermission.js
• 埋点 Composable: src/composables/useEventTracking.js
• 收藏操作: src/composables/useCollectOperation.js