| 1 | # Hooks 文档 |
| 2 | |
| 3 | 本目录包含项目级通用 React Hooks。只有被多个页面、布局、全局组件或跨业务域场景真实复用的 Hook 才能放入 `src/hooks`。 |
| 4 | |
| 5 | ## 文件列表 |
| 6 | |
| 7 | | 文件 | 描述 | |
| 8 | | ------------------------------ | ------------------------------------------ | |
| 9 | | `useDocumentTitle.ts` | 动态更新浏览器页面标题 Hook | |
| 10 | | `useDouyinPublishSession.ts` | 抖音 H5 发布会话轮询与 IndexedDB 恢复 Hook | |
| 11 | | `useDraftGenerationPricing.ts` | AI 草稿生成定价缓存 Hook | |
| 12 | | `useGeolocation.ts` | 浏览器地理位置 Hook | |
| 13 | | `useIsMobile.ts` | 移动端断点判断 Hook | |
| 14 | | `useKeepTimeCountdown.ts` | 倒计时 Hook | |
| 15 | | `useMediaUpload.ts` | 媒体文件上传 Hook，支持进度显示、中断上传 | |
| 16 | | `usePlatformMetadata.ts` | 平台元数据读取、场景过滤与名称解析 Hook | |
| 17 | | `useSystem.ts` | 系统相关 Hook | |
| 18 | | `useVideoThumbnail.ts` | 视频缩略图生成 Hook | |
| 19 | |
| 20 | ## 常用导入 |
| 21 | |
| 22 | ```ts |
| 23 | import { useDocumentTitle } from '@/hooks' |
| 24 | import { useMediaUpload } from '@/hooks' |
| 25 | import { usePlatformInfo } from '@/hooks/usePlatformMetadata' |
| 26 | ``` |
| 27 | |
| 28 | ## useDocumentTitle - 动态页面标题 Hook |
| 29 | |
| 30 | 在客户端组件中动态更新浏览器页面标题（`document.title`）。标题格式由 `src/utils/title.ts` 统一处理。 |
| 31 | |
| 32 | ```tsx |
| 33 | import { useDocumentTitle } from '@/hooks' |
| 34 | |
| 35 | function ChatPage() { |
| 36 | useDocumentTitle('New chat') |
| 37 | return <div>...</div> |
| 38 | } |
| 39 | ``` |
| 40 | |
| 41 | ## useMediaUpload - 媒体上传 Hook |
| 42 | |
| 43 | 封装媒体文件上传逻辑，支持进度显示、中断上传、移除媒体。 |
| 44 | |
| 45 | ```tsx |
| 46 | import { useMediaUpload } from '@/hooks' |
| 47 | import { toast } from '@/utils/ui/toast' |
| 48 | |
| 49 | function MyComponent() { |
| 50 | const { medias, isUploading, handleMediasChange, handleMediaRemove, clearMedias } = |
| 51 | useMediaUpload({ |
| 52 | onError: (error) => toast.error('上传失败: ' + error.message), |
| 53 | }) |
| 54 | |
| 55 | return <div>{isUploading ? 'Uploading...' : medias.length}</div> |
| 56 | } |
| 57 | ``` |
| 58 | |
| 59 | ## 新增 Hook 规范 |
| 60 | |
| 61 | 1. 先检查本文档、`src/hooks/index.ts` 和调用方局部 `hooks/`，确认没有类似实现。 |
| 62 | 2. 确认该 Hook 是项目级通用 Hook；单页面或单组件使用的 Hook 必须下沉到调用方局部目录。 |
| 63 | 3. 新增、迁移、删除 `src/hooks` 下任意文件时，同步更新本文档和 `src/hooks/index.ts`。 |
| 64 | 4. 完成后运行 `npx tsc --noEmit`。 |
| 65 |