README.md
6.4 KB
Composables 目录
本项目使用 Vue 3 Composition API 的 Composables 模式封装可复用逻辑。
📚 快速索引
| Composable | 功能描述 | 使用场景 |
|---|---|---|
usePermission |
权限检查（登录/VIP/认证） | 页面权限控制 |
useFileOperation |
文件下载、打开、预览 | 资料库、文档查看 |
useSectionList |
分组列表管理 | 设置页面、帮助中心 |
useCollectOperation |
收藏/取消收藏 | 产品收藏、资料收藏 |
usePlanSubmit |
计划书提交后处理 | 计划书功能 |
useEventTracking |
事件埋点 | 用户行为追踪 |
useListItemClick |
列表项点击处理 | 列表导航 |
useFieldDependencies |
字段依赖管理 | 表单联动 |
useFieldValueTransform |
字段值转换 | 表单数据处理 |
usePlanView |
计划书视图管理 | 计划书查看 |
详细说明
usePermission.js
功能：统一的权限检查逻辑
核心方法：
-
requireLogin(callback, options)- 检查登录权限（最常用） -
checkPermission(type, callback, options)- 通用权限检查 -
hasPermission(type)- 静默检查权限（不弹窗） -
isLoggedIn()- 获取登录状态
使用示例：
import { usePermission } from '@/composables/usePermission'
const { requireLogin } = usePermission()
// 查看资料需要登录
const viewMaterial = (item) => {
requireLogin(() => {
openDocument(item.url)
}, {
content: '请先登录后查看完整资料',
confirmText: '立即登录'
})
}
useFileOperation.js
功能：文件下载、打开、预览
核心方法：
-
viewFile(item)- 入口函数，自动判断文件类型 -
openFile(filePath, item)- 使用 Taro.openDocument 打开文件 -
downloadAndOpenFile(item)- 下载并打开文件
支持的文件类型：
- 图片：jpg, jpeg, png, gif, webp, bmp, svg
- 视频：mp4, mov 等（跳转播放页面）
- 文档：pdf（直接预览），Office 文档（提示不支持）
使用示例：
import { useFileOperation } from '@/composables/useFileOperation'
const { viewFile } = useFileOperation()
// 打开文件
await viewFile({
downloadUrl: 'https://example.com/file.pdf',
fileName: 'document.pdf',
extension: 'pdf' // 可选，优先使用此字段判断类型
})
useSectionList.js
功能：分组列表页面管理
核心方法：
-
sections- 分组列表数据（shallowRef） -
handleItemClick(item)- 列表项点击处理
使用示例：
import { useSectionList } from '@/composables/useSectionList'
const { sections, handleItemClick } = useSectionList(
[
{
title: '常用功能',
items: [
{ title: '我的收藏', icon: 'star', subtitle: '查看收藏内容' }
]
}
],
(item, go) => {
// 自定义导航逻辑
go('/pages/favorites/index')
}
)
useCollectOperation.js
功能：收藏/取消收藏（乐观更新）
核心方法：
-
toggleCollect(item, successMsg, errorMsg)- 切换收藏状态
特性：
- 乐观更新 UI（先更新界面，后调用 API）
- 失败自动回滚
- 发送事件通知其他页面
使用示例：
import { useCollectOperation } from '@/composables/useCollectOperation'
const { toggleCollect } = useCollectOperation()
// 切换收藏
await toggleCollect(item, '收藏成功', '已取消收藏')
usePlanSubmit.js
功能：计划书提交后统一处理
核心方法：
-
handlePlanSubmit(result, callbacks)- 处理提交结果
特性：
- 自动关闭弹窗
- 自动清空选中产品
- 支持导航前后回调
使用示例：
import { usePlanSubmit } from '@/composables/usePlanSubmit'
const { handlePlanSubmit } = usePlanSubmit({
getPopupState: () => showPlanPopup.value,
setPopupState: (state) => { showPlanPopup.value = state },
clearSelectedProduct: () => { selectedProduct.value = null }
})
await handlePlanSubmit(result, {
beforeNav: async () => { console.log('导航前') },
afterNav: async () => { console.log('导航后') }
})
useEventTracking.js
功能：事件埋点
核心方法：
-
trackEvent(type, objectId, extraData)- 追踪事件 -
trackFileRead(fileId, extraData)- 追踪文件阅读
使用示例：
import { useEventTracking, EventType } from '@/composables/useEventTracking'
const { trackFileRead } = useEventTracking()
// 追踪文件阅读
await trackFileRead('file-id-123', {
title: '保险产品手册',
category: '产品资料'
})
useListItemClick.js
功能：列表项点击处理（带权限检查）
核心方法：
-
handleListItemClick(item, config)- 处理列表项点击
使用示例：
import { useListItemClick } from '@/composables/useListItemClick'
const { handleListItemClick } = useListItemClick()
// 点击列表项（自动检查登录权限）
handleListItemClick(item, {
needLogin: true,
onClick: (item) => {
console.log('点击了', item)
}
})
useFieldDependencies.js
功能：表单字段依赖管理
核心方法：
- 当字段 A 变化时，自动更新字段 B
useFieldValueTransform.js
功能：字段值转换
核心方法：
- 将用户输入转换为后端需要的格式
usePlanView.js
功能：计划书视图管理
核心方法：
- 管理计划书的显示状态
🎯 最佳实践
命名规范
// ✅ GOOD - 清晰的命名
usePermission()
useFileOperation()
useSectionList()
// ❌ BAD - 过于通用
useData()
useList()
抽取原则
必须抽取 Composable：
- ✅ 业务逻辑在 ≥ 3 个组件中重复
- ✅ 相同的状态管理模式重复
- ✅ 复杂的异步操作模式重复
返回值规范
// ✅ 返回响应式 refs 和函数
return {
// 响应式状态
users, // ref
loading, // ref
// 方法
fetchUsers,
refresh // 别名方法
}