组件开发规范

本文引用的文件

AudioDownload.vue
MiniPlayer.vue
LazyImage.vue
Skeleton.vue
SkeletonList.vue
audio.ts
user.ts
index.vue
index.vue
index.ts
request.ts
storage.ts
package.json
tsconfig.json
vite.config.ts

简介

本规范面向AI有声书生成平台的前端组件开发，目标是统一组件命名、文件组织、代码风格与类型约束，明确属性定义、事件声明与插槽设计，规范状态管理与数据流，提供测试、调试与性能优化策略，并覆盖跨平台兼容、响应式设计与无障碍访问要点，最后给出版本管理、文档与发布流程的标准。

项目结构

前端采用基于Vue 3 + TypeScript + Pinia + UniApp的多端一体化架构，组件集中在src/components目录，页面位于src/pages，全局状态位于src/store，类型定义位于src/types，工具函数位于src/utils，构建与运行配置位于根目录配置文件。

graph TB
subgraph "页面层"
P_Index["pages/index/index.vue"]
P_Player["pages/player/index.vue"]
end
subgraph "组件层"
C_AudioDownload["components/AudioDownload.vue"]
C_LazyImage["components/LazyImage.vue"]
C_Skeleton["components/Skeleton.vue"]
C_SkeletonList["components/SkeletonList.vue"]
C_MiniPlayer["components/MiniPlayer.vue"]
end
subgraph "状态管理层"
S_Audio["store/audio.ts"]
S_User["store/user.ts"]
end
subgraph "工具与类型"
U_Request["utils/request.ts"]
U_Storage["utils/storage.ts"]
T_Index["types/index.ts"]
end
subgraph "构建与配置"
CFG_Pkg["package.json"]
CFG_TS["tsconfig.json"]
CFG_Vite["vite.config.ts"]
end
P_Index --> C_MiniPlayer
P_Player --> C_AudioDownload
P_Player --> S_Audio
P_Index --> S_User
C_AudioDownload --> U_Request
C_LazyImage --> U_Request
S_Audio --> U_Request
S_User --> U_Request
S_Audio --> T_Index
S_User --> T_Index
CFG_Pkg --> CFG_TS
CFG_Pkg --> CFG_Vite

图示来源

index.vue:106-108
index.vue:84-92
audio.ts:1-297
user.ts:1-107
request.ts:1-207
storage.ts:1-63
index.ts:1-89
package.json:1-65
tsconfig.json:1-14
vite.config.ts:1-24

章节来源

package.json:1-65
tsconfig.json:1-14
vite.config.ts:1-24

核心组件

音频下载组件：支持带重试的下载、进度展示与本地保存，具备插槽扩展能力。
迷你播放器：全局悬浮播放器，条件渲染与播放控制，与Pinia状态联动。
懒加载图片：基于uni-app的懒加载策略，支持占位图与事件透传。
骨架屏：单元素骨架屏与列表骨架屏，支持多种布局与动画。
页面组件：播放页与首页，演示组件组合、状态管理与数据流。

章节来源

AudioDownload.vue:1-179
MiniPlayer.vue:1-166
LazyImage.vue:1-73
Skeleton.vue:1-72
SkeletonList.vue:1-283
index.vue:1-190
index.vue:1-200

架构总览

组件开发遵循“页面-组件-状态-工具-类型”的分层，页面负责编排与交互，组件负责UI与行为，Pinia集中管理音频与用户状态，工具模块封装请求与存储，类型模块提供强类型约束。

sequenceDiagram
participant Page as "页面组件"
participant Comp as "业务组件"
participant Store as "Pinia状态"
participant Util as "工具模块"
participant API as "后端接口"
Page->>Comp : 传递属性/触发事件
Comp->>Util : 调用请求/存储工具
Util->>API : 发起HTTP请求
API-->>Util : 返回数据
Util-->>Comp : 标准化结果
Comp->>Store : 更新状态
Store-->>Page : 计算属性/状态变更

图示来源

index.vue:192-384
audio.ts:88-141
request.ts:34-99

组件详解与最佳实践

命名约定与文件组织

组件文件：PascalCase.vue，如 AudioDownload.vue、MiniPlayer.vue。
组件导出：默认导出Vue组件，内部使用

组件开发规范.md 15 KB Vēsture Neapstrādāts