hmos-multidevice-avoid-areas

Device Avoidance Area Adaptation

Skill Definition

Field	Content
`skill_id`	`device-avoid-areas`
`skill_name`	`设备避让区适配`
`one_line_purpose`	Provide a unified avoidance strategy for the system bar, punch-hole area, soft keyboard, and immersive layout.
`device_scope`	`phone / tablet / 2in1 / tv`
`problem_scope`	`safe area、状态栏和导航栏避让、挖孔区、软键盘、沉浸式布局`
`not_in_scope`	`与系统区域无关的普通间距调整、纯业务交互逻辑`
`primary_outputs`	`primary_scene`、`device_constraints`、`implementation_notes`、`fix_plan`、`verification_matrix`

Core Constraints

First clarify which type of avoidance area is being handled, then decide whether to use dynamic detection, safe area expansion, or an immersive solution.
Do not hard-code the system bar, punch-hole area, or keyboard dimensions; prefer using APIs to obtain them dynamically.
When immersive layout is involved, both the background extension strategy and the content avoidance strategy must be specified.
When the soft keyboard is involved, the layout update logic for the three timings of pop-up, dismissal, and focus change must be specified.
Key content and core click areas must not be placed in the punch-hole area or non-interactive areas.
Do not claim that an avoidance solution is complete before specifying the fallback strategy for exceptional scenarios.

Stage Tags

Tag	Stage	Current Module Focus
`REQ`	Requirements Analysis and Design	Avoidance area types, background and content boundaries, immersive adaptation, safe area expansion
`DEV`	Development	Dynamic acquisition of avoidance area APIs, padding settings, window settings, expandSafeArea safe area settings
`FIX`	Bug Fixing	Content obscured by the system bar area, content obscured when the soft keyboard is raised, immersive misalignment, content obstruction or interaction failure in the notch area/punch-hole area
`VAL`	Feature Verification	Screenshot evidence, evidence of system area changes, evidence of keyboard open/close

Unified Output Fields

Routing fields: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

Field Definitions

device_constraints: Refers to the hard adaptation constraints brought by the status bar, navigation bar, punch-hole area, soft keyboard, and immersive window. In device-avoid-areas , it is usually which system areas obscure content, whether the background is allowed to extend, and which interactive areas must never fall into non-clickable areas.
capability_boundary: Refers to which window modes, system UI states, or device types the current avoidance solution is effective under, and which scenarios require fallback or additional handling.
acceptance_focus: Refers to the obstruction phenomena, keyboard open/close behavior, and system area change manifestations that must be confirmed as key points during the requirements stage acceptance.
In scene, deliverables.REQ appears device_constraints, indicating that "after this avoidance scenario is hit, the requirements stage must first specify the obstruction and boundary constraints," not that the field is defined repeatedly.

AI Retrieval Requirements

When system area type identification and dynamic acquisition are involved, prioritize matching AVOID-01。
When the background or image extends but the content remains within the safe area, prioritize matching AVOID-02。
When full-screen pages, transparent status bars, or immersive layouts are involved, prioritize matching AVOID-03。
When the input box is obscured by the keyboard or the page jumps when the keyboard opens or closes, prioritize matching AVOID-04。

Scenario Index

`AVOID-01` Avoidance Area Identification and Dynamic Acquisition

scene_id: AVOID-01
scene_name: 避让区域识别与动态获取
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
intent_signals:
  - AvoidAreaType
  - TYPE_SYSTEM
  - TYPE_NAVIGATION_INDICATOR
  - TYPE_CUTOUT
  - TYPE_KEYBOARD
applies_when:
  - 需要动态获取系统栏、挖孔区或键盘区域
  - 当前问题表现为内容被系统区域遮挡
not_applies_when:
  - 只是普通布局间距问题
decisions:
  - 确定需要监听哪些避让区域
  - 决定使用 padding、margin、offset 还是结构切换
deliverables:
  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
resource_refs:
  - RSC_AVOID_01
  - RSC_AVOID_05

`AVOID-02` Safe Area Expansion and Background Extension

scene_id: AVOID-02
scene_name: 安全区扩展与背景延伸
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
intent_signals:
  - expandSafeArea
  - SafeAreaType
  - SafeAreaEdge
  - 背景延伸
applies_when:
  - 背景需要铺满系统区域，但内容仍需保持在安全区内
  - 需要明确顶部和底部内容边界
not_applies_when:
  - 页面需要完全沉浸式展示且不保留常规内容边界
decisions:
  - 确定哪些层允许越过安全区，哪些层必须避让
  - 决定安全区扩展后是否还要补额外内边距
deliverables:
  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
resource_refs:
  - RSC_AVOID_02

`AVOID-03` Immersive Full-Screen Layout

scene_id: AVOID-03
scene_name: 沉浸式全屏布局
phase_tags: [REQ, DEV, FIX, VAL]
priority: P1
intent_signals:
  - setWindowLayoutFullScreen
  - 全屏
  - 沉浸式
  - 状态栏透明
  - 列表沉浸
applies_when:
  - 页面需要背景或媒体内容铺满边缘
  - 当前问题表现为全屏后内容与系统栏重叠
  - 列表/信息流场景需要上滑隐藏标题栏和导航栏
not_applies_when:
  - 页面保持普通安全区布局即可
decisions:
  - 明确背景延伸和内容避让的分层策略
  - 决定窗口级设置和页面级布局如何配合
  - 识别是否命中 best practice 场景, 命中时必须逐条对照
deliverables:
  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
resource_refs:
  - RSC_AVOID_03
  - RSC_AVOID_06
  - RSC_AVOID_05

`AVOID-04` Soft Keyboard Avoidance and Input Area Stability

scene_id: AVOID-04
scene_name: 软键盘避让与输入区稳定性
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
intent_signals:
  - keyboardAvoidMode
  - avoidAreaChange
  - 输入框被遮挡
  - 键盘弹出
applies_when:
  - 输入框、按钮或底部操作栏会被软键盘遮挡
  - 当前问题表现为键盘开闭导致内容跳动或错位
not_applies_when:
  - 页面没有输入交互
decisions:
  - 选择滚动、平移或重排哪种键盘避让方式
  - 决定键盘弹出、收起、焦点切换时的同步策略
deliverables:
  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
resource_refs:
  - RSC_AVOID_01
  - RSC_AVOID_04
  - RSC_AVOID_05

Resource Index

`RSC_AVOID_01` Avoidance Area Type Reference

resource_id: RSC_AVOID_01
resource_type: reference
path: ./references/avoid_area_types.md
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
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` Safe Area Expansion Reference

resource_id: RSC_AVOID_02
resource_type: reference
path: ./references/safe_area_api.md
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
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` Immersive Layout Reference

resource_id: RSC_AVOID_03
resource_type: reference
path: ./references/immersive_layout.md
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
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` Keyboard Avoidance Reference

resource_id: RSC_AVOID_04
resource_type: reference
path: ./references/keyboard_handling.md
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
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` Bug Fix Case Collection

resource_id: RSC_AVOID_05
resource_type: reference
path: ./references/bug-fix-cases.md
phase_tags: [FIX]
priority: P1
used_for:
  - 排查状态栏遮挡、挖孔区遮挡、沉浸式布局错位、键盘避让异常等常见问题
load_when:
  - 命中 AVOID-01 或 AVOID-03 或 AVOID-04 且处于 FIX 阶段
avoid_when:
  - 当前不涉及问题修复
supports_scenes:
  - AVOID-01
  - AVOID-03
  - AVOID-04
output_fields:
  - problem_profile
  - root_cause_hypothesis
  - fix_plan
  - regression_watchlist

`RSC_AVOID_06` Development Scenario Solution Collection

resource_id: RSC_AVOID_06
resource_type: reference
path: ./references/scenario-development-cases.md
phase_tags: [REQ, DEV, VAL]
priority: P0
used_for:
  - 提供沉浸式布局等场景的完整开发方案与分步实现
load_when:
  - 命中 AVOID-03 且处于 REQ 或 DEV 阶段
avoid_when:
  - 当前处于 FIX 阶段（应走 RSC_AVOID_05）
supports_scenes:
  - AVOID-03
output_fields:
  - acceptance_focus
  - implementation_notes
  - code_touchpoints
  - verification_matrix

Stage Output Contract

`REQ`

Must output:active_phases、primary_phase、primary_scene、secondary_scenes
Must output:device_constraints、capability_boundary、acceptance_focus
Additional requirement: clarify whether the background layer, content layer, and input layer are each allowed to extend beyond the system area

`DEV`

Must output:code_touchpoints、reuse_resources、implementation_notes、integration_risks
Additional requirement: clarify the dynamic API retrieval, layout update entry point, and window-level settings placement

`FIX`

Must output:problem_profile、root_cause_hypothesis、fix_plan、regression_watchlist
Additional requirement: clarify whether the occlusion source is the system bars, the punch-hole area, the soft keyboard, or immersive window settings

`VAL`

Must output:verification_matrix、evidence_requirements、pass_criteria、residual_risks
Additional requirement: provide at least screenshot or screen recording evidence under system bar changes, keyboard open/close, or punch-hole orientation changes

About this skill

Skill Definition

Core Constraints

Stage Tags

Unified Output Fields

Field Definitions

AI Retrieval Requirements

Scenario Index

AVOID-01 Avoidance Area Identification and Dynamic Acquisition

AVOID-02 Safe Area Expansion and Background Extension

AVOID-03 Immersive Full-Screen Layout

AVOID-04 Soft Keyboard Avoidance and Input Area Stability

Resource Index

RSC_AVOID_01 Avoidance Area Type Reference

RSC_AVOID_02 Safe Area Expansion Reference

RSC_AVOID_03 Immersive Layout Reference

RSC_AVOID_04 Keyboard Avoidance Reference

RSC_AVOID_05 Bug Fix Case Collection

RSC_AVOID_06 Development Scenario Solution Collection

Stage Output Contract

REQ

DEV

FIX

VAL

`AVOID-01` Avoidance Area Identification and Dynamic Acquisition

`AVOID-02` Safe Area Expansion and Background Extension

`AVOID-03` Immersive Full-Screen Layout

`AVOID-04` Soft Keyboard Avoidance and Input Area Stability

`RSC_AVOID_01` Avoidance Area Type Reference

`RSC_AVOID_02` Safe Area Expansion Reference

`RSC_AVOID_03` Immersive Layout Reference

`RSC_AVOID_04` Keyboard Avoidance Reference

`RSC_AVOID_05` Bug Fix Case Collection

`RSC_AVOID_06` Development Scenario Solution Collection

`REQ`

`DEV`

`FIX`

`VAL`