Composables 参考文档

本文档列出项目中所有 Composables 的详细说明。

项目中的 Composables

Composable	用途	文档
useSectionList	分组列表管理	详情
useFileOperation	文件下载、预览、打开	详情
useListItemClick	统一的列表点击处理	详情
useCollectOperation	收藏操作	详情
useEventTracking	事件埋点	详情
useGo	增强导航	详情
usePlanPermission	计划书权限检查	详情

---

useSectionList

位置：src/composables/useSectionList.js

功能：分组列表管理

用途：处理分组数据的展开/收起、过滤等逻辑

示例：

import { useSectionList } from '@/composables/useSectionList'

const { sections, toggleSection, isExpanded } = useSectionList(data)

---

useFileOperation

位置：src/composables/useFileOperation.js

功能：文件操作（下载、预览、打开）

用途：统一的文件操作逻辑，支持多种文件类型

示例：

import { useFileOperation } from '@/composables/useFileOperation'

const { downloadFile, previewFile, openFile } = useFileOperation()

// 下载文件
await downloadFile(file)

// 预览文件
await previewFile(file)

---

useListItemClick

位置：src/composables/useListItemClick.js

功能：统一的列表点击处理

用途：处理列表项的点击事件，包含权限检查和埋点

示例：

import { useListItemClick } from '@/composables/useListItemClick'

const { handleItemClick } = useListItemClick()

// 处理点击
await handleItemClick(item, () => {
  // 点击后的操作
})

---

useCollectOperation

位置：src/composables/useCollectOperation.js

功能：收藏/取消收藏操作

用途：处理收藏状态切换和 API 调用

示例：

import { useCollectOperation } from '@/composables/useCollectOperation'

const { isCollected, toggleCollect } = useCollectOperation(metaId)

// 切换收藏状态
await toggleCollect()

---

useEventTracking

位置：src/composables/useEventTracking.js

功能：事件埋点

用途：统一的事件埋点功能，支持多种埋点类型

事件类型：

• READ_FILE - 阅读素材

示例：

import { useEventTracking } from '@/composables/useEventTracking'

const { trackEvent, trackFileRead } = useEventTracking()

// 追踪阅读事件
await trackFileRead('file-id-123')

// 追踪自定义事件
await trackEvent('CUSTOM_EVENT', 'object-id', {
  title: '文档标题',
  category: '分类'
})

---

useGo

位置：src/hooks/useGo.js

功能：增强导航

用途：自动路径补全和便捷导航方法

示例：

import { useGo } from '@/hooks/useGo'

const go = useGo()

// 导航到页面
go('/pages/detail/index')

// 带参数导航
go('/pages/product-detail/index', { id: 123 })

// 返回
go.back()

---

usePlanPermission

位置：src/composables/usePlanPermission.js

功能：计划书权限检查

用途：检查用户是否有权限操作计划书

示例：

import { usePlanPermission } from '@/composables/usePlanPermission'

const { checkPlanPermission } = usePlanPermission()

// 检查权限后执行操作
await checkPlanPermission(() => {
  // 有权限后的操作
})

---

抽取原则

第 3 次出现原则

当相同代码模式出现 3 次时，必须抽取为 Composable。

示例：

// ❌ BAD - 在多个组件中重复
const handleClick = async () => {
  if (!isLoggedIn()) {
    Taro.showToast({ title: '请先登录', icon: 'none' })
    return
  }
  // ... 业务逻辑
}

// ✅ GOOD - 抽取为 Composable
const { requireLogin } = usePermission()
await requireLogin(() => {
  // ... 业务逻辑
})

---

创建新的 Composable

命名规范

• 使用 use 前缀
• 使用驼峰命名
• 名称应描述功能

示例：

• ✅ useUserData
• ✅ useFormValidation
• ❌ userData
• ❌ validation

基本结构

/**
 * 使用 XXX 功能
 *
 * @description 功能描述
 * @returns {Object} 返回值描述
 */
export function useXxx() {
  // 响应式状态
  const state = ref(null)

  // 方法
  const method = () => {
    // ...
  }

  // 返回公共 API
  return {
    state,
    method
  }
}

使用示例

// 在组件中使用
import { useXxx } from '@/composables/useXxx'

const { state, method } = useXxx()

---

相关文档

• 组件参考 - 可复用组件
• 最佳实践 - 代码复用原则