Hmos Multidevice Avoid Areas

---
name: hmos-multidevice-avoid-areas
description: Handle HarmonyOS avoid-area adaptation through a declarative scene and resource index. Use when the task involves safe area expansion, status bar or navigation bar avoidance, notch or cutout handling, immersive full-screen layouts, or soft keyboard overlap handling.
metadata:
  version: 1.0.2
  keywords:
    - 避让区
    - 安全区
    - safe area
    - avoid area
    - 状态栏避让
    - 导航栏避让
    - 挖孔屏
    - 刘海屏
    - cutout
    - 沉浸式布局
    - 全屏适配
    - 软键盘遮挡
    - 键盘顶起
    - keyboard overlap
    - HDS
    - HDS沉浸式
    - 高级组件
    - HdsNavigation
    - dynamicHideTitleBar
    - hdsMaterial
    - 沉浸光感
    - systemMaterialEffect
    - 滚动模糊
---

# 设备避让区适配

## 技能定义

| 字段 | 内容 |
| --- | --- |
| `skill_id` | `device-avoid-areas` |
| `skill_name` | `设备避让区适配` |
| `one_line_purpose` | 为系统栏、挖孔区、软键盘和沉浸式布局提供统一避让策略。 |
| `device_scope` | `phone / tablet / 2in1 / tv / wearable` |
| `problem_scope` | `safe area、状态栏和导航栏避让、挖孔区、软键盘、沉浸式布局` |
| `not_in_scope` | `与系统区域无关的普通间距调整、纯业务交互逻辑` |
| `primary_outputs` | `primary_scene`、`device_constraints`、`implementation_notes`、`fix_plan`、`verification_matrix` |

## 核心约束

- 先明确要处理的是哪类避让区域，再决定使用动态检测、安全区扩展还是沉浸式方案。
- 不要硬编码系统栏、挖孔区或键盘尺寸，应优先使用 API 动态获取。
- 涉及沉浸式布局时，必须同时说明背景延伸策略和内容避让策略。
- 涉及软键盘时，必须说明弹出、收起和焦点变化三类时机的布局更新逻辑。
- 关键内容和核心点击区域不得放在挖孔区或不可交互区域。
- 未说明异常场景下的回退策略前，不得宣称避让方案完整。
- **VAL 阶段路由强制要求**：当验证涉及折叠设备多形态验证、hidumper 模拟、分辨率阶梯验证时，**不得在本 SKILL 内自行执行验证操作**（如直接调用 hdc 截屏、尝试悬浮窗等），必须按以下步骤路由：	 
  1. 读取 `../hmos-multidevice-scenario-entry/references/multi-device-verification.md`	 
  2. 按文档中的标准流程执行验证

- **HDS 高级组件推荐提示**：HDS（UI Design Kit）高级组件内置安全区处理、沉浸光感和滚动模糊等避让能力，可大幅减少手动避让代码。当 DEV 阶段命中以下避让场景时，**应主动向用户推荐 HDS 组件方案**，但**不自动替换用户已有的组件**，由用户决定是否采用：
  - **AVOID-02 安全区扩展**：手动 `expandSafeArea` + padding 避让 → `HdsNavigation` 的 `enableComponentSafeArea: true` 自动处理标题栏安全区，无需手动计算状态栏高度
  - **AVOID-03 沉浸式全屏**：
    - 手动 `setWindowLayoutFullScreen` + `setWindowSystemBarProperties` + `expandSafeArea` 沉浸式方案 → `HdsNavigation` 配合 `systemMaterialEffect`（`hdsMaterial.MaterialType.ADAPTIVE`）实现自适应沉浸光感效果
    - 手动滚动监听隐藏标题栏 → `HdsNavigation` 的 `dynamicHideTitleBar`（`HideMode.SCROLL_UP_TO`）一行配置替代
    - 手动列表沉浸模糊 → `HdsNavigation` 的 `scrollEffectOpts`（`ScrollEffectType.COMMON_BLUR` / `TRANSITION_BLUR` / `GRADIENT_BLUR`）替代手动滚动偏移计算
    - 手动浮层 TabBar → `HdsTabs` 的 `barFloatingStyle`（悬浮样式 + `systemMaterialEffect` 沉浸光感）替代手动 offset 跟随
  - **HDS 组件详细 API 和示例参见 `./references/hds-ui-design-kit.md`。**
  - **设备约束**：`hdsMaterial`（沉浸光感）仅支持手机和平板，其他设备需回退到手动方案；`HdsNavigation` 最低版本 5.1.0(18)，`hdsMaterial` 最低版本 6.1.0(23)。
  - 用户未选择 HDS 或设备不支持时，使用本技能 AVOID 场景的手动避让方案。

### 资源采纳优先级

当用户问题描述与避让场景高度匹配时，按以下优先级采纳：

1. **场景方案（RSC_AVOID_06）为首要实现依据** — 其中的 API 调用、算法逻辑、组件结构、回调处理等细节不得省略或简化。如果场景方案提供了完整代码，必须完整采纳，不得选择性丢弃。
2. **HDS 高级组件为推荐替代方案** — 当避让场景可通过 HDS 组件内置能力解决时（见"HDS 高级组件推荐提示"），主动向用户推荐 HDS 组件方案，但不自动替换。HDS 组件详细 API 参见 `./references/hds-ui-design-kit.md`。
3. **指南文档（RSC_AVOID_01/02/03/04）为补充参考** — 仅在场景方案未覆盖的边界情况或需要额外解释时查阅，不得用指南文档中的通用描述替代场景方案中的具体实现。
4. **修复案例（RSC_AVOID_05）用于 FIX 阶段** — 仅在排查已有问题时参考，不用于新功能开发。

判断"高度匹配"的标准：用户描述的 UI 结构、交互行为、避让目标与场景方案的标题或描述基本一致（如"列表滚动隐藏标题栏"匹配场景1，"底部导航栏避让"匹配场景2）。

## 阶段标签

| 标签 | 阶段 | 当前模块关注点 |
| --- | --- | --- |
| `REQ` | 需求分析设计 | 避让区域类型、背景与内容边界、沉浸式适配、安全区扩展 |
| `DEV` | 开发 | 动态获取避让区域API、padding设置、窗口设置、expandSafeArea安全区域设置 |
| `FIX` | 问题修复 | 内容被系统栏区域遮挡、软键盘拉起遮挡内容、沉浸式错位、刘海区/挖孔区内容遮挡或交互失效 |
| `VAL` | 功能验证 | 截图证据、系统区域变化证据、键盘开闭证据 |

## 统一输出字段

- 路由字段：`active_phases`、`primary_phase`、`primary_scene`、`secondary_scenes`、`resources_used`
- `REQ`：`device_constraints`、`capability_boundary`、`acceptance_focus`
- `DEV`：`code_touchpoints`、`reuse_resources`、`implementation_notes`、`integration_risks`
- `FIX`：`problem_profile`、`root_cause_hypothesis`、`fix_plan`、`regression_watchlist`
- `VAL`：`verification_matrix`、`evidence_requirements`、`pass_criteria`、`residual_risks`

## 字段释义

- `device_constraints`：指由状态栏、导航栏、挖孔区、软键盘和沉浸式窗口带来的适配硬约束。在 `device-avoid-areas` 中，通常是哪些系统区域会遮挡内容、背景是否允许延伸、哪些交互区绝不能落入不可点击区域。
- `capability_boundary`：指当前避让方案在哪些窗口模式、系统 UI 状态或设备类型下有效，哪些场景需要回退或额外处理。
- `acceptance_focus`：指需求阶段验收时必须重点确认的遮挡现象、键盘开闭行为和系统区域变化表现。
- 统一输出字段中每个阶段列出的字段表示“命中避让场景后，该阶段必须输出这些字段”，由阶段决定输出内容，不再由场景单独定义。

## 场景决策树

```
用户提出避让区相关问题
│
├── Step 1: 阶段判断（primary_phase）
│   │
│   │  判断原则: 用户是否在描述已有代码/页面上出现的不正确结果
│   │
│   ├── FIX: 满足以下任一条件
│   │   ├── 用户描述了已有实现运行后的异常结果
│   │   │   强信号: "不生效"、"仍然是"、"错乱"、"跳变"、"返回值为0"、"被压缩"
│   │   │   中信号: "被遮挡"、"没有延伸"、"没有更新"、"重叠"、"上推"、"截断"
│   │   ├── 用户明确要求排查/修复已有问题
│   │   │   关键词: "排查原因"、"修复"、"为什么不生效"、"请排查"
│   │   └── prompt 同时包含 API/代码片段 + 异常结果（双重确认）
│   │
│   ├── DEV: 描述全新功能需求，无已有异常
│   │   关键词: "需要实现"、"请给出开发方案"、"请给出完整方案"
│   │   注意: "不能被遮挡"（设计约束）≠ "被遮挡"（已有问题）
│   │
│   └── REQ: 描述需求并要求分析/评估
│   │   关键词: "请给出需求分析"、"请分析"、"评估"
│
├── Step 2: 主场景路由（primary_scene）
│   │
│   ├── Q1: 是否涉及键盘弹出/遮挡输入框？
│   │   └── 是 → AVOID-04 软键盘避让与输入区稳定性
│   │       └── 结束路由
│   │
│   ├── Q2: 是否调用了 setWindowLayoutFullScreen 或 setWindowSystemBarProperties？
│   │   ├── 是 → AVOID-03 沉浸式全屏布局
│   │   │   └── 例外：如果核心是挖孔/Cutout遮挡UI元素 → AVOID-01（挖孔优先于全屏）
│   │   └── 否 → 继续 Q3
│   │
│   ├── Q3: 核心问题是"背景延伸但内容不延伸"？
│   │   │   特征关键词: expandSafeArea、背景铺满、内容保持安全区
│   │   ├── 是 → AVOID-02 安全区扩展与背景延伸
│   │   │   └── 例外：如果同时调用了全屏API → AVOID-03
│   │   └── 否 → 继续 Q4
│   │
│   └── Q4: 是否涉及避让区域信息的获取/监听？
│       │   特征关键词: getWindowAvoidArea、avoidAreaChange、
│       │             TYPE_CUTOUT、避让失效、返回异常值
│       ├── 是 → AVOID-01 避让区域识别与动态获取
│       └── 否 → 不命中避让区技能（not_in_scope）
│
└── Step 3: 关联场景补充（secondary_scenes）
    │   按用户问题中同时涉及的内容添加，无明确关联则输出 []
    │
    ├── AVOID-01 + AVOID-02: 同时涉及避让区域获取 + 背景延伸/内容边界
    ├── AVOID-01 + AVOID-03: 同时涉及避让区域获取 + 全屏模式
    ├── AVOID-03 + AVOID-02: 同时涉及全屏模式 + expandSafeArea
    ├── AVOID-04 + AVOID-01: 同时涉及键盘 + 多种避让区域监听
    └── []: 无明确关联
```

## 场景索引

#### `AVOID-01` 避让区域识别与动态获取

```yaml
scene_id: AVOID-01
scene_name: 避让区域识别与动态获取
phase_tags: [REQ, DEV, FIX, VAL]
intent_signals:
  - AvoidAreaType
  - TYPE_SYSTEM
  - TYPE_NAVIGATION_INDICATOR
  - TYPE_CUTOUT
  - TYPE_KEYBOARD
applies_when:
  - 需要动态获取系统栏、挖孔区或键盘区域
  - 当前问题表现为内容被系统区域遮挡
  - 涉及挖孔/Cutout/TYPE_CUTOUT 遮挡 UI 元素（最高优先级，即使同时使用全屏 API）
  - 折叠屏展开/折叠或横竖屏切换后，避让区域高度变化导致布局不更新
  - avoidAreaChange 监听未注册或 getWindowAvoidArea 时序问题导致获取旧值
  - getWindowAvoidArea 返回值异常（为 0 或不正确），且未使用全屏 API
not_applies_when:
  - 只是背景延伸且不涉及动态获取避让区域（属于 AVOID-02）
  - 已使用 setWindowLayoutFullScreen 或 setWindowSystemBarProperties 开启全屏，getWindowAvoidArea 只是为全屏布局提供避让参数（属于 AVOID-03）
  - 使用 setWindowLayoutFullScreen 后 getWindowAvoidArea 返回 0，属于全屏配置问题（属于 AVOID-03）
  - 仅涉及键盘弹出遮挡输入框（属于 AVOID-04）
  - 用户使用了 expandSafeArea 且问题出在内容层未加 padding 避让（属于 AVOID-02）
  - 用户问题主要涉及软键盘弹出遮挡，getWindowAvoidArea 只是辅助监听（属于 AVOID-04）
  - 问题核心是 padding 加在错误位置，而非避让区域获取（属于 AVOID-02）
decisions:
  REQ:
    - 确定目标避让区域类型：无输入框跳过 TYPE_KEYBOARD；内容不靠近边缘可降低优先级（参考 RSC_AVOID_06 场景5 状态栏适配中避让区域类型的选择）
    - 确定覆盖设备形态：折叠屏必须考虑展开/折叠后高度变化；平板注意导航条可能不存在
    - 确定是否需要持续监听：静态布局可一次性获取；支持旋转/折叠必须 avoidAreaChange
  DEV:
    - 选择获取方式：一次性用 getWindowAvoidArea，响应变化用 avoidAreaChange，通常两者配合（参考 RSC_AVOID_06 场景4 挖孔区四方向检测的实现）
    - 选择注册时机：全局复用在 onWindowStageCreate，单页面用在 aboutToAppear（注意窗口就绪时序）
    - 选择消费策略：padding（最常用）/ margin / 组件级 offset / 结构切换（横竖屏两套布局）
    - 处理时序兜底：avoidAreaChange 回调触发前用缓存值，getWindowAvoidArea 返回 0 时延迟重试
  FIX:
    - 定位问题环节：始终遮挡→获取环节；变化后遮挡→监听环节（参考 RSC_AVOID_05 场景11）；首次加载遮挡→时序环节（参考 RSC_AVOID_05 场景10）
    - 检查避让类型完整性：是否遗漏 TYPE_CUTOUT 或 TYPE_NAVIGATION_INDICATOR（参考 RSC_AVOID_05 场景2 挖孔区未检测 TYPE_CUTOUT）
    - 检查回调链路：是否注册 → 注册时机是否正确 → 回调是否触发 → UI 状态是否绑定
    - 检查设备形态切换：折叠屏展开/横竖屏旋转后回调是否重新触发、值是否正确更新（参考 RSC_AVOID_05 场景10 windowSizeChange 时序问题、场景12 display.on 时序跳变）
  VAL:
    - 截图验证：直板竖屏/横屏、折叠屏折叠态/展开态、平板默认态
    - 动态变化证据：旋转前后、折叠/展开前后的截图对比
    - 数值验证：getWindowAvoidArea 返回值不为 0，avoidAreaChange 回调值在变化前后不同
resource_refs:
  - RSC_AVOID_01
  - RSC_AVOID_05
  - RSC_AVOID_06
```

#### `AVOID-02` 安全区扩展与背景延伸

```yaml
scene_id: AVOID-02
scene_name: 安全区扩展与背景延伸
phase_tags: [REQ, DEV, FIX, VAL]
intent_signals:
  - expandSafeArea
  - SafeAreaType
  - SafeAreaEdge
  - 背景延伸
  - 背景色铺满状态栏
  - 图片延伸到系统栏
  - 内容保持在安全区
  - enableComponentSafeArea
  - HdsNavigation安全区
applies_when:
  - 背景需要铺满系统区域，但内容仍需保持在安全区内
  - 需要明确顶部和底部内容边界
  - 未调用 setWindowLayoutFullScreen，仅用 expandSafeArea 延伸背景
  - 核心特征是"背景延伸、内容不延伸"
  - expandSafeArea 已设置但背景未延伸或内容层未留 padding
  - padding 加在了外层容器而非子组件上，导致背景色出现间隙（属于分层问题，不是全屏设置问题）
not_applies_when:
  - 页面使用了 setWindowLayoutFullScreen 开启全屏（属于 AVOID-03）
  - 使用了 setWindowSystemBarProperties 设置状态栏透明（属于 AVOID-03）
  - 涉及避让系统导航条 + 沉浸效果且使用 AvoidAreaManager 管理器（属于 AVOID-03）
  - 涉及键盘弹出遮挡输入框（属于 AVOID-04）
  - 需要动态获取避让区域类型（属于 AVOID-01）
decisions:
  REQ:
    - 确定需要延伸的层：背景层（颜色/图片）必须铺满系统栏区域，内容层（文字/按钮）必须保持在安全区内
    - 确定延伸方向：通常顶部（状态栏）和底部（导航条），左右视设计稿决定
    - 确定内容安全间距：内容距离安全区边缘的最小距离，是否需要额外留白
  DEV:
    - 选择 expandSafeArea 参数：SafeAreaType 指定 SYSTEM/CUTOUT/KEYBOARD，SafeAreaEdge 指定 TOP/BOTTOM/START/END
    - 决定设置层级：expandSafeArea 加在背景容器上，而非内容组件上
    - 决定内容层 padding 补偿：背景延伸后内容层需手动加 padding 保持安全区，padding 必须加在子组件上（加在外层容器会导致背景色间隙）
    - 处理 SafeAreaEdge 遗漏：只设 TOP 不设 BOTTOM → 底部出现间隙；需按设计稿逐方向确认
  FIX:
    - 定位间隙来源：背景色在系统栏区域出现间隙 → padding 加在了外层容器而非子组件，分层策略有误（参考 RSC_AVOID_05 场景4 顶部 padding 位置错误导致背景色间隙）
    - 定位内容溢出：内容跑到状态栏区域 → expandSafeArea 错误地加在了内容层而非背景层
    - 排查全屏 API 干扰：如果同时调了 setWindowLayoutFullScreen，问题可能属于 AVOID-03 而非本场景
  VAL:
    - 截图验证：安全区边界处背景是否铺满、内容是否保持安全距离
    - 多设备验证：不同状态栏高度、有无导航条的设备上表现是否一致
    - 旋转验证：横竖屏切换后背景是否仍然延伸、内容是否仍然安全
resource_refs:
  - RSC_AVOID_02
  - RSC_AVOID_05
```

#### `AVOID-03` 沉浸式全屏布局

```yaml
scene_id: AVOID-03
scene_name: 沉浸式全屏布局
phase_tags: [REQ, DEV, FIX, VAL]
intent_signals:
  - setWindowLayoutFullScreen
  - 全屏
  - 沉浸式
  - 状态栏透明
  - 列表沉浸
  - 滚动隐藏标题栏
  - 浮层 TabBar
  - 阅读器全屏
  - 视频播放全屏
  - hdsMaterial
  - 沉浸光感
  - dynamicHideTitleBar
  - scrollEffectOpts
  - 滚动模糊
  - systemMaterialEffect
  - barFloatingStyle
applies_when:
  - 页面需要背景或媒体内容铺满边缘
  - 当前问题表现为全屏后内容与系统栏重叠
  - 列表/信息流场景需要上滑隐藏标题栏和导航栏
  - 核心特征是"调用了 setWindowLayoutFullScreen 或状态栏透明设置"
  - 涉及浮层 TabBar、自定义导航栏等全屏场景组件
not_applies_when:
  - 仅使用 expandSafeArea 背景延伸，未开启全屏（属于 AVOID-02）
  - 问题核心是 padding 加在了错误位置（如外层容器而非子组件），而非全屏设置问题（属于 AVOID-02）
  - 问题核心是 avoidAreaChange 监听未注册或 getWindowAvoidArea 时序问题导致折叠屏变化后不更新（属于 AVOID-01）
  - 涉及键盘弹出导致布局问题（属于 AVOID-04）
  - 仅需要获取避让区域高度，不涉及全屏（属于 AVOID-01）
  - 涉及挖孔遮挡 UI 元素（属于 AVOID-01，挖孔优先于全屏）
decisions:
  REQ:
    - 确定沉浸式类型：完全沉浸（视频/阅读器全屏）、半沉浸（列表上滑隐藏标题栏）（参考 RSC_AVOID_06 场景1 列表滚动沉浸）、持续沉浸（自定义导航栏+透明状态栏）
    - 确定系统栏可见性：完全隐藏 vs 透明显示 vs 半透明叠加
    - 确定退出机制：返回键退出、手势退出、超时自动退出
  DEV:
    - 选择窗口级 API：setWindowLayoutFullScreen 开启全屏 + setWindowSystemBarProperties 设置状态栏颜色/透明度
    - 选择页面级避让策略：全屏后内容延伸到系统栏区域，需在页面内用 avoidAreaChange 获取高度手动处理 padding
    - 处理列表沉浸：上滑隐藏标题栏 → 监听滚动偏移量动态调整；浮层 TabBar → offset 跟随滚动（参考 RSC_AVOID_06 场景1 onScrollFrameBegin 线性比例算法）
    - 处理自定义导航栏：padding-top = 状态栏高度（从 avoidAreaChange 获取），不能硬编码
    - 识别实践场景：命中 list immersive / video immersive / reading immersive 时必须逐条对照实现（参考 RSC_AVOID_06 场景1/2/3 的完整方案）
  FIX:
    - 确认全屏是否生效：setWindowLayoutFullScreen 调用后 getWindowAvoidArea 仍返回 0 → 全屏配置未生效或调用时机不对
    - 定位内容遮挡：全屏后内容跑到状态栏下面 → 页面内未加避让 padding 或未注册 avoidAreaChange（参考 RSC_AVOID_05 场景1 阅读器顶部遮挡、场景7 底部被导航指示器遮挡）
    - 定位系统栏显示异常：setWindowSystemBarProperties 后状态栏仍不透明 → 检查调用时机（需在窗口创建后）和参数格式
    - 排查非全屏场景：如果未调用 setWindowLayoutFullScreen，问题属于 AVOID-01 或 AVOID-02
  VAL:
    - 截图验证：全屏模式下背景是否铺满、内容是否合理避让
    - 系统栏交互验证：滑动/点击时系统栏是否按预期显示/隐藏/恢复
    - 多设备验证：不同状态栏高度下自定义导航栏高度是否正确
    - 退出验证：各种退出方式是否正常恢复非沉浸状态
resource_refs:
  - RSC_AVOID_03
  - RSC_AVOID_06
  - RSC_AVOID_05
```

#### `AVOID-04` 软键盘避让与输入区稳定性

```yaml
scene_id: AVOID-04
scene_name: 软键盘避让与输入区稳定性
phase_tags: [REQ, DEV, FIX, VAL]
intent_signals:
  - keyboardAvoidMode
  - avoidAreaChange
  - 输入框被遮挡
  - 键盘弹出
applies_when:
  - 输入框、按钮或底部操作栏会被软键盘遮挡
  - 当前问题表现为键盘开闭导致内容跳动或错位
not_applies_when:
  - 页面没有输入交互
  - 不涉及软键盘，仅涉及系统栏或挖孔区（属于 AVOID-01/02/03）
decisions:
  REQ:
    - 确定页面输入场景：单输入框（登录页）、多输入框（表单）、底部输入框（聊天页）、固定底部栏（底部按钮+输入框）
    - 确定避让期望：内容上推/滚动到可见区域/底部栏固定上移/布局重排
    - 确定焦点切换行为：多输入框间切换时是否需要平滑滚动
    - 确定键盘收起后恢复：是否立即恢复原位、是否有动画过渡
  DEV:
    - 选择 keyboardAvoidMode：RESIZE（调整窗口大小，适合固定布局）PAN（平移内容，适合单输入框简单场景）OFFSET（偏移，适合有底部固定栏的场景）
    - 处理底部固定栏：键盘弹出后底部栏需上移 → 通过 avoidAreaChange 中 TYPE_KEYBOARD 获取高度计算 offset
    - 处理列表/表单滚动：键盘弹出后自动滚动到焦点输入框 → 结合 scroller.scrollToIndex 或 scrollTo
    - 处理键盘动画时序：键盘收起动画期间布局可能跳动 → avoidAreaChange 回调中 keyboard height 从非 0 变为 0 时延迟恢复
  FIX:
    - 定位问题类型：输入框被遮挡 → 避让模式或 offset 计算有误；布局跳动 → 键盘弹出/收起动画冲突；底部栏异常 → 固定定位与键盘避让策略冲突
    - 检查 keyboardAvoidMode：是否选错模式（如列表页用了 PAN 导致内容被裁切而非滚动）
    - 检查焦点与滚动同步：点击输入框后是否自动滚动到可见位置，多输入框切换时是否跟随
    - 检查键盘收起恢复：收起后布局是否恢复原位、是否有残留 offset、快速弹出/收起时是否稳定
    - 排查非键盘问题：如果遮挡来自系统栏或挖孔而非键盘 → 属于 AVOID-01/02/03
  VAL:
    - 截图验证：键盘弹出时输入框是否可见、底部栏是否正确上移
    - 键盘收起验证：收起后布局是否恢复原位、无残留偏移
    - 焦点切换验证：多输入框间切换时页面是否平滑滚动到目标输入框
    - 多输入法验证：系统键盘 vs 第三方输入法（高度不同）表现是否一致
    - 边界场景：快速弹出/收起、横屏键盘、物理键盘连接时的稳定性
resource_refs:
  - RSC_AVOID_01
  - RSC_AVOID_04
  - RSC_AVOID_05
  - RSC_AVOID_06
```

## 资源索引

#### `RSC_AVOID_01` 避让区域类型参考

```yaml
resource_id: RSC_AVOID_01
resource_type: reference
path: ./references/avoid_area_types.md
used_for:
  - 识别系统栏、导航栏、挖孔区和键盘区域类型
  - 设计动态获取与监听策略
load_when:
  - 命中 AVOID-01 或 AVOID-04
avoid_when:
  - 当前不涉及系统区域和键盘区域
supports_scenes:
  - AVOID-01
  - AVOID-04
output_fields:
  - device_constraints
  - capability_boundary
  - implementation_notes
  - root_cause_hypothesis
  - verification_matrix
```

#### `RSC_AVOID_02` 安全区扩展参考

```yaml
resource_id: RSC_AVOID_02
resource_type: reference
path: ./references/safe_area_api.md
used_for:
  - 定义安全区扩展和背景延伸的边界
  - 判断内容层与背景层的职责划分
load_when:
  - 命中 AVOID-02
avoid_when:
  - 页面不使用安全区扩展
supports_scenes:
  - AVOID-02
output_fields:
  - device_constraints
  - capability_boundary
  - implementation_notes
  - fix_plan
  - pass_criteria
```

#### `RSC_AVOID_03` 沉浸式布局参考

```yaml
resource_id: RSC_AVOID_03
resource_type: reference
path: ./references/immersive_layout.md
used_for:
  - 定义窗口级全屏和页面级避让的配合方式
  - 排查沉浸式布局中的内容遮挡问题
load_when:
  - 命中 AVOID-03
avoid_when:
  - 页面不需要沉浸式展示
supports_scenes:
  - AVOID-03
output_fields:
  - device_constraints
  - implementation_notes
  - root_cause_hypothesis
  - verification_matrix
  - residual_risks
```

#### `RSC_AVOID_04` 键盘避让参考

```yaml
resource_id: RSC_AVOID_04
resource_type: reference
path: ./references/keyboard_handling.md
used_for:
  - 设计键盘弹出、收起和焦点切换时的避让逻辑
  - 排查输入区跳动、按钮被遮挡等问题
load_when:
  - 命中 AVOID-04
avoid_when:
  - 页面没有输入交互
supports_scenes:
  - AVOID-04
output_fields:
  - acceptance_focus
  - implementation_notes
  - fix_plan
  - verification_matrix
  - evidence_requirements
```

#### `RSC_AVOID_05` 问题修复案例集

```yaml
resource_id: RSC_AVOID_05
resource_type: reference
path: ./references/bug-fix-cases.md
used_for:
  - 排查状态栏遮挡、挖孔区遮挡、沉浸式布局错位、键盘避让异常等常见问题
  - 排查安全区扩展与背景延伸相关的 padding 位置错误、背景色间隙等问题
load_when:
  - 命中 AVOID-01 或 AVOID-02 或 AVOID-03 或 AVOID-04 且处于 FIX 阶段
avoid_when:
  - 当前不涉及问题修复
supports_scenes:
  - AVOID-01
  - AVOID-02
  - AVOID-03
  - AVOID-04
output_fields:
  - problem_profile
  - root_cause_hypothesis
  - fix_plan
  - regression_watchlist
```

#### `RSC_AVOID_06` 开发场景方案集

```yaml
resource_id: RSC_AVOID_06
resource_type: reference
path: ./references/scenario-development-cases.md
used_for:
  - 提供沉浸式布局等场景的完整开发方案与分步实现
  - 提供挖孔区适配、底部导航栏避让、状态栏适配、键盘易操作等场景的完整开发方案
load_when:
  - 命中 AVOID-01 或 AVOID-03 或 AVOID-04 且处于 REQ 或 DEV 阶段
avoid_when:
  - 当前处于 FIX 阶段（应走 RSC_AVOID_05）
supports_scenes:
  - AVOID-01
  - AVOID-03
  - AVOID-04
output_fields:
  - acceptance_focus
  - implementation_notes
  - code_touchpoints
  - verification_matrix
```