d758563a13
三层架构组件库： - 第 1 层原子组件：PageShell/ContentCard/StatusTag/SectionTitle/LoadingCard - 第 2 层组合模式：PageHeader/SearchSection/CardList/PaginationBar - 第 3 层 Hook：useListPage（列表页通用逻辑抽象） Token 扩展：新增 --tk-card-*/--tk-gap-*/--tk-page-* 等结构化 CSS 变量， 关怀模式通过变量覆写自动生效，新组件零额外代码即获关怀支持。 设计规格：docs/superpowers/specs/2026-05-16-miniprogram-unified-components-design.md
142 lines
5.2 KiB
Markdown
142 lines
5.2 KiB
Markdown
# 小程序统一组件库设计规格
|
||
|
||
> 日期: 2026-05-16 | 状态: 编写中 | 方案: 三层架构（原子 + 模式 + Hook）
|
||
|
||
---
|
||
|
||
## 1. 背景与问题
|
||
|
||
小程序端 66 个页面存在严重 UI 不统一：59 页手写骨架、119 处卡片重写、9+ 列表页无模板、关怀模式未覆盖 doctor 端。根因是缺少组件级统一抽象。
|
||
|
||
目标：改 1 处组件 = 全部页面同步；页面代码减少 ~70%；关怀 100% 覆盖。
|
||
|
||
## 2. 设计决策
|
||
|
||
三层架构 | 仅小程序端 | 温润东方风 | 组件级关怀 | 渐进迁移
|
||
|
||
## 3. 目录结构
|
||
|
||
components/ui/ (原子) → components/patterns/ (组合) → hooks/useListPage.ts (Hook)
|
||
|
||
## 4. 第 1 层：原子组件
|
||
|
||
**PageShell** — 页面容器。padding 语义化（none/sm/md/lg），safeBottom，scroll 包裹。
|
||
**ContentCard** — 卡片。3 种 variant，统一圆角/阴影/触摸反馈。
|
||
**StatusTag** — 状态标签。内置 5 色映射，pill 圆角。
|
||
**SectionTitle** — 段落标题。赤土橙竖线装饰。
|
||
**LoadingCard** — 骨架屏。与 ContentCard 同尺寸。
|
||
|
||
## 5. 第 2 层：组合模式
|
||
|
||
**PageHeader** — 页面顶部（title + back + actions）。
|
||
**SearchSection** — 搜索区域（搜索框 + 可选筛选标签）。
|
||
**CardList** — 列表容器（自动处理 loading/error/empty）。
|
||
**PaginationBar** — 分页控制（替代 2 种命名体系）。
|
||
|
||
## 6. 第 3 层：useListPage Hook
|
||
|
||
封装分页/搜索/筛选/加载/空状态。返回 listPageProps 可直接展开给组合组件。列表页从 ~120 行降至 ~35 行。
|
||
|
||
---
|
||
|
||
## 7. 关怀模式集成
|
||
|
||
### 现状问题
|
||
|
||
当前关怀模式通过 `elder-mode.scss` 全局 CSS 覆写实现，存在 3 个问题：
|
||
1. 按类名匹配，新增页面不用正确类名就漏掉
|
||
2. doctor 端页面完全不在覆写范围内
|
||
3. 每次改组件样式都要同步改 elder-mode.scss
|
||
|
||
### 新方案：组件级自适应
|
||
|
||
每个原子组件内部全部读取 CSS 变量，关怀模式只需改变量值：
|
||
|
||
1. **扩展 tokens.scss** — 新增结构化 Token：
|
||
|
||
```
|
||
--tk-card-bg: #fff // 卡片背景
|
||
--tk-card-padding: 24px // 卡片内间距
|
||
--tk-card-radius: 16px // 卡片圆角
|
||
--tk-gap-sm: 12px // 小间距
|
||
--tk-gap-md: 16px // 中间距
|
||
--tk-gap-lg: 24px // 大间距
|
||
--tk-page-padding: 24px // 页面内间距
|
||
--tk-touch-feedback-opacity: 0.85 // 触摸反馈透明度
|
||
```
|
||
|
||
2. **原子组件全部读变量** — ContentCard 的 padding 使用 `var(--tk-card-padding)`，border-radius 使用 `var(--tk-card-radius)`
|
||
|
||
3. **elder-mode.scss 只覆写变量值**：
|
||
|
||
```scss
|
||
.elder-mode {
|
||
--tk-card-padding: 32px; // 24px → 32px
|
||
--tk-card-radius: 20px; // 16px → 20px
|
||
--tk-gap-md: 20px; // 16px → 20px
|
||
--tk-page-padding: 32px; // 24px → 32px
|
||
// ... 已有字号/触控变量保持不变
|
||
}
|
||
```
|
||
|
||
4. **新页面自动获得关怀支持** — 只要使用原子组件，无需额外代码
|
||
|
||
5. **精简 elder-mode.scss** — 只保留页面级特殊覆写（如体征网格 2 列→1 列），不再需要组件级覆写
|
||
|
||
---
|
||
|
||
## 8. 迁移策略
|
||
|
||
### Phase 1：创建组件 + Token 扩展（~2天）
|
||
|
||
- 扩展 tokens.scss 新增 `--tk-card-*`、`--tk-gap-*`、`--tk-page-*` 等结构化 Token
|
||
- 实现 5 个原子组件 + 4 个组合组件 + useListPage Hook
|
||
- 每个组件编写基本测试（渲染/Props/变体）
|
||
- **不动任何现有页面**，新组件与旧代码并行
|
||
|
||
### Phase 2：迁移 doctor 端列表页（~1.5天）
|
||
|
||
- 选择 patients 列表页做试点 — 完整迁移 + 截图对比验证
|
||
- 批量迁移剩余 8 个列表页：dialysis, prescription, report, alerts, consultation(doctor), followup, article, consultation(患者)
|
||
- 每页迁移后：截图对比 → 功能验证（搜索/分页/空状态）→ 确认无回归
|
||
|
||
### Phase 3：迁移非列表页 + 关怀模式（~1.5天）
|
||
|
||
- 首页、详情页、表单页等迁移为 PageShell + ContentCard
|
||
- 扩展 elder-mode.scss 结构化 Token 覆写
|
||
- doctor 端页面首次获得关怀模式支持
|
||
- 全量页面关怀模式验证
|
||
|
||
### Phase 4：清理旧代码 + 文档（~0.5天）
|
||
|
||
- 删除各页面不再使用的手写样式（.search-bar, .xxx-card, .pagination 等）
|
||
- 清理未使用的 mixins（card 等）
|
||
- 精简 elder-mode.scss 为纯页面级特殊覆写
|
||
- 编写组件使用文档
|
||
|
||
---
|
||
|
||
## 9. 预期效果
|
||
|
||
| 指标 | 改造前 | 改造后 |
|
||
|------|--------|--------|
|
||
| 页面模板代码 | ~120 行/页 | ~35 行/页 |
|
||
| 卡片样式定义 | 119 处分散 | 1 处 ContentCard |
|
||
| 搜索栏实现 | 4 处重写 | 1 个 SearchSection |
|
||
| 分页器体系 | 2 种混用 | 1 个 PaginationBar |
|
||
| 状态标签实现 | 3 种方式 | 1 个 StatusTag |
|
||
| 关怀模式覆盖 | 仅患者端 TabBar | 100%（含 doctor 端） |
|
||
| 新功能 UI 开发 | 从零手写 | 组装组件 |
|
||
|
||
---
|
||
|
||
## 10. 验证方式
|
||
|
||
每个迁移阶段完成后执行：
|
||
|
||
- **视觉对比** — 截图对比改造前后，确保一致
|
||
- **功能验证** — 搜索、分页、空状态、错误状态均正常
|
||
- **关怀模式** — 切换后全量页面自适应无异常
|
||
- **构建通过** — `pnpm build` 无报错
|
||
- **真机预览** — DevTools 或真机预览验证触摸反馈和交互
|