# 全局加载视觉系统设计

## 目标

建立一个全项目共用、职责明确的加载视觉系统：整页首次加载和页面局部加载统一使用 `AppLoading.vue`，按钮提交继续由 `AppButton.vue` 负责，下拉刷新、触底加载和文件上传保留各自符合场景的反馈方式。

## 已确认方案

采用分层方案，不使用一个整页 Loading 覆盖所有异步场景。

### 1. `AppLoading` 的职责

- `variant="page"`：页面首次进入且主体数据尚不可展示时使用。
- `variant="section"`：搜索结果或页面局部区域等待数据时使用，保留周围已有内容。
- `text`：当前正在执行的动作。
- `description`：可选辅助说明。
- 组件自身不创建全屏遮罩、不接管标题栏或底部导航、不控制业务状态。
- 朱砂谱印、呼吸动效、文字层级和间距由组件单一维护，页面不得复制或重写印章动画。

### 2. 两档视觉尺寸

页面级：

- 谱印 `96×96rpx`，印内文字 `40rpx`。
- 主文案 `30rpx`，辅助说明 `24rpx`。
- 内容区最小高度 `320rpx`。

局部级：

- 谱印 `64×64rpx`，印内文字 `28rpx`。
- 主文案 `24rpx`，辅助说明 `22rpx`。
- 内容区最小高度 `180rpx`。

两档均保持透明背景和现有 `1.35s` 呼吸节奏。

## 首批接入范围

### 页面级 Loading

| 页面 | 文案方向 |
|---|---|
| G01 我的家谱 | 正在整理家谱 |
| G05 家谱总览 | 正在展开家谱 |
| G09 我的申请 | 正在整理申请记录 |
| G10 入谱审核 | 正在整理审核申请 |
| G11 家谱设置 | 正在读取家谱设置 |
| G12 字辈诗 | 正在整理字辈诗 |
| T01 世系树 | 正在整理世系 |
| T03 成员档案 | 正在读取成员档案 |
| T07 成员目录 | 正在整理成员目录 |
| F01 家族动态 | 正在整理家族动态 |
| N01 消息中心 | 正在整理消息 |

### 局部 Loading

- G06 搜索家谱：只替换搜索结果区域，搜索框、模式切换和筛选条件保持可见。

## 明确排除

- A01、A04、A05、G03、G08、G11 保存、T04、T05、F02、M02、M07 的提交／保存过程使用 `AppButton` 的加载态，不使用 `AppLoading`。
- 下拉刷新和触底加载必须保留已有列表及滚动位置，不显示整页 Loading。
- 头像、相册和动态图片上传显示上传进度，不显示整页 Loading。
- 错误、空数据和无权限状态不得伪装成 Loading。

## 状态与兼容

- 页面仍拥有自己的 `loading/list/empty/error/no-permission` 等业务状态；`AppLoading` 只消费状态结果。
- 现有用于 H5 样式审核的 `?state=loading` 入口继续保留。
- 页面从加载切换到成功、空、错误时必须移除 Loading，不与目标状态叠加。
- 320×568 允许自然纵向滚动，不允许横向溢出或遮挡固定底栏。

## 验证

- 组件契约锁定 `page/section` 两种变体、`text/description` 属性和唯一动画入口。
- 每个首批页面的静态契约必须证明使用 `AppLoading`，并禁止保留旧页面自制加载标识。
- 运行现有编译审计、各模块运行 smoke 和 `git diff --check`。
- 代表性页面检查 320×568、360×640、360×800、412×915；H5 证据不代表 Android/HBuilderX 正式验收。