SuperAPI AI Directory
Partner中文AI newsFavorites
Skillshmos-multidevice-natural-orientation

hmos-multidevice-natural-orientation

Frontend & websites

View repository

Updated 10-16 03:11

About this skill

Device natural orientation and screen rotation adaptation

Skill definition

Field Content
skill_id device-natural-orientation
skill_name 设备自然方向适配
one_line_purpose Provide unified orientation determination and update strategies for natural portrait, natural landscape, and special folded states.
device_scope phone / tablet / pc / 2in1 / tri-fold / foldable
problem_scope 屏幕旋转(rotation)、屏幕方向(display orientation)、窗口方向(window orientation)、自然方向差异、传感器旋转检测、多设备方向映射、三折叠 G 态方向、视频横竖屏切换、短视频自适应旋转
not_in_scope 与方向无关的纯布局问题、web视觉翻转的场景、折叠屏折痕避让（属 device-avoid-areas）、交互输入方式适配（属 interaction-methods）、硬件能力检测（属 hardware-access）
primary_outputs primary_scene, device_constraints, code_touchpoints, implementation_notes, fix_plan, verification_matrix

Core constraints

  1. First distinguish screen rotation, display orientation, and window orientation; the three have different meanings and uses and must not be conflated
  2. Controlling the app display orientation must be done on the window side via setPreferredOrientation() setting the rotation policy, and cannot be done via screen properties
  3. When multi-device adaptation is involved, the target device's natural orientation type must be clearly specified: natural portrait (rotation=0 is PORTRAIT), natural landscape (rotation=0 is LANDSCAPE), tri-fold G state (rotation=0 is LANDSCAPE_INVERTED)
  4. In split-screen/floating-window/free-window scenarios, setPreferredOrientation() is silently ineffective; adaptation to window size should be done via responsive layout
  5. For foldable devices, deviceInfo.deviceType returns 'phone', and deviceType cannot be used to distinguish foldables from bar phones; use display.isFoldable() + breakpoint system
  6. The output solution must explain the UI update logic and lifecycle management (save/restore orientation) after orientation changes

Three mainline structure

The module mainline is fixed as three blocks; first classify by mainline, then proceed to scenario subdivision:

Mainline Main scenario Main resource
Detection and listening ORIENT-01 RSC_ORIENT_03
Adaptation strategy ORIENT-02、ORIENT-03 RSC_ORIENT_02、RSC_ORIENT_04
Problem fixing ORIENT-04 RSC_ORIENT_05

Note:

  • RSC_ORIENT_01（orientation_concepts.md) is a foundational concept resource, not an independent scenario, and is referenced by each scenario as needed.
  • The three mainlines cover the complete chain of orientation adaptation: perceive changes → strategy adaptation → problem fixing.

Stage tags

Tag Stage Current module focus
REQ Requirements analysis and design Device orientation differences, natural orientation types, rotation capability boundaries, acceptance criteria
DEV Development Code placement, rotation policy selection, breakpoint determination, resource binding
FIX Problem fixing Root cause analysis (concept confusion/detection error/mapping error), minimal change path, regression points
VAL Feature verification Device coverage matrix, orientation switching evidence, pass criteria

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 natural portrait, natural landscape, rotation semantics, window orientation, and special folded states. In device-natural-orientation , it is usually which natural orientation types need to be supported, how rotation is interpreted, and in which scenarios conflating screen rotation and window orientation concepts is prohibited.
  • capability_boundary: refers to which device form factors and orientation modes the current orientation strategy holds for, and which scenarios require separate degradation or workarounds.
  • acceptance_focus: refers to the orientation determination results, switching consistency, and layout update trigger conditions that must be confirmed during requirements-stage acceptance.
  • In scene, deliverables.REQ appears device_constraints, meaning "after this orientation scenario is hit, requirements analysis must first provide the device constraint conclusion"; it is not about reinventing fields at the scenario layer.

AI retrieval requirements

  • When involving rotation angle acquisition, orientation change listening, sensor detection, or debugging rotation issues, prioritize hitting ORIENT-01。
  • When it involves multi-device orientation adaptation, one-multi strategy, foldable screen orientation, tri-fold G state, module.json5 orientation configuration, or breakpoint determination, prioritize ORIENT-02。
  • When it involves video landscape/portrait switching, short video adaptive rotation, the adaptive_video third-party library, or screen lock, prioritize ORIENT-03。
  • When it involves orientation adaptation bugs (foldable screen forced portrait, Tabs orientation lock, split-screen rotation failure, full-screen exit not restored, open/close flicker), prioritize ORIENT-04。
  • When it involves conceptual questions such as distinguishing rotation/orientation concepts, natural orientation definitions, or the 18 rotation strategies, first load RSC_ORIENT_01（orientation_concepts.md) as prerequisite knowledge.

Workflow

Steps

  1. Based on intent_signals / applies_when hit primary scenario (primary_scene) and secondary scenario (secondary_scenes）。
  2. Read by scenario resource_refs and skill_to_path, prioritize loading the P0 official path.
  3. For conceptual questions or scenarios where the concept is unclear during fixing, additionally load RSC_ORIENT_01（orientation_concepts.md）。
  4. Generate phased results (REQ/DEV/FIX/VAL) according to the "unified output fields".
  5. Complete the required fields according to the "phase output contract" and provide verification evidence requirements.

Output

  • Routing fields:active_phases、primary_phase、primary_scene、secondary_scenes、resources_used。
  • Phase fields: output the corresponding structured results according to the REQ/DEV/FIX/VAL contract.

Checklist

  • has hit at least one ORIENT-* scenario, and the hit basis is explained.
  • has prioritized the use of P0 official resources,P1 template resources are only used to accelerate implementation.
  • When conceptual questions or root cause analysis involve conceptual confusion, RSC_ORIENT_01。
  • has been loaded and has output all required fields for the current phase (see "phase output contract").
  • already includes orientation verification evidence requirements and residual risk statements.

Scenario Index

ORIENT-01 Screen rotation detection and orientation change listening

scene_id: ORIENT-01
scene_name: 屏幕旋转检测与方向变化监听
phase_tags: [DEV, FIX, VAL]
priority: P0
intent_signals:
  - "如何获取旋转角度"
  - "传感器检测方向"
  - "重力传感器 atan2"
  - "监听屏幕旋转"
  - "windowSizeChange"
  - "display.on('change')"
  - "hdc 调试旋转"
  - "获取设备握持角度"
  - "旋转180° 不触发"
applies_when:
  - 需要获取连续旋转角度而非离散方向
  - 需要监听方向变化并响应
  - 需要调试旋转相关问题
  - 需要实现自定义旋转检测逻辑
not_applies_when:
  - 只需使用系统旋转策略，不需要自定义检测
  - 概念不清，需先理解基础概念
decisions:
  - 优先使用系统旋转策略（setPreferredOrientation），仅当系统策略不满足时才自定义传感器检测
  - display.on('change') 回调中必须通过 Display 实例获取信息，不能通过 Window 实例（有时序问题）
  - windowSizeChange 在旋转 180° 时不触发，需结合 display.on('change') 补充
  - 传感器数据需防抖和平滑处理，回调必须使用命名引用以便取消
deliverables:
  DEV:
    - code_touchpoints
    - reuse_resources
    - implementation_notes
    - integration_risks
  FIX:
    - problem_profile
    - root_cause_hypothesis
    - fix_plan
  VAL:
    - verification_matrix
    - evidence_requirements
resource_refs:
  - RSC_ORIENT_03
  - RSC_ORIENT_08
  - RSC_ORIENT_06
  - RSC_ORIENT_07
skill_to_path:
  - skill: 旋转检测与方向监听
    path: ./references/rotation_detection.md

ORIENT-02 Multi-device orientation adaptation (one-multi strategy)

scene_id: ORIENT-02
scene_name: 多设备方向适配（一多策略）
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
intent_signals:
  - "多设备方向适配"
  - "折叠屏方向"
  - "三折叠 G 态"
  - "follow_desktop"
  - "348vp 阈值"
  - "一多方向策略"
  - "module.json5 orientation"
  - "AUTO_ROTATION_RESTRICTED"
  - "断点判断方向"
  - "WidthBreakpoint"
  - "折叠屏展开态方向"
applies_when:
  - 同一应用需适配多种设备形态的方向策略
  - 需要配置 module.json5 方向
  - 需要选择设备方向映射策略
  - 需要理解三折叠 G 态特殊性
not_applies_when:
  - 纯概念理解不涉及适配实现
  - 只涉及视频横竖屏切换（应命中 ORIENT-03）
  - 只涉及传感器检测不涉及多设备策略选择
decisions:
  - 一多推荐策略：module.json5 配置 follow_desktop + 运行时基于断点动态切换
  - 优先使用系统断点 API（WidthBreakpoint/HeightBreakpoint）判断设备形态，而非 deviceInfo.deviceType
  - 三折叠 G 态 rotation=0 对应 LANDSCAPE_INVERTED，窗口方向不能通过 rotation 推断
  - 折叠屏 deviceInfo.deviceType 返回 'phone'，需用 display.isFoldable() + 断点系统区分
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_ORIENT_02
  - RSC_ORIENT_01
  - RSC_ORIENT_09
  - RSC_ORIENT_10
skill_to_path:
  - skill: 多设备方向适配
    path: ./references/orientation_adaptation.md
  - skill: 方向概念与API速查
    path: ./references/orientation_concepts.md

ORIENT-03 Video application landscape/portrait switching and adaptive rotation

scene_id: ORIENT-03
scene_name: 视频应用横竖屏切换与自适应旋转
phase_tags: [DEV, FIX, VAL]
priority: P0
intent_signals:
  - "视频横竖屏切换"
  - "USER_ROTATION_LANDSCAPE"
  - "短视频自适应旋转"
  - "adaptive_video"
  - "视频全屏"
  - "屏幕锁定"
  - "横竖屏性能优化"
  - "视频全屏退出恢复"
applies_when:
  - 视频播放页需要横竖屏切换
  - 短视频页面需要自适应旋转
  - 视频全屏退出后方向未恢复
  - 需要使用 adaptive_video 三方库
not_applies_when:
  - 非视频类应用的方向适配
  - 不涉及视频播放的方向问题
decisions:
  - 视频全屏用 USER_ROTATION_LANDSCAPE，退出时恢复之前保存的方向
  - 进入时保存方向、退出时恢复，必须成对调用 setPreferredOrientation()
  - 折叠屏展开态视频全屏时不旋转，直接调整播窗大小
  - Navigation 场景用 onShown/onHidden 处理方向切换
  - Tabs 场景方向控制放 Tabs.onChange，不放子组件生命周期
deliverables:
  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
resource_refs:
  - RSC_ORIENT_04
  - RSC_ORIENT_01
skill_to_path:
  - skill: 视频横竖屏切换
    path: ./references/video_rotation.md

ORIENT-04 Orientation adaptation issue fixing

scene_id: ORIENT-04
scene_name: 方向适配问题修复
phase_tags: [DEV, FIX, VAL]
priority: P0
intent_signals:
  - "方向锁定异常"
  - "折叠屏被强制竖屏"
  - "Tabs 方向 Bug"
  - "分屏旋转失效"
  - "全屏退出方向未恢复"
  - "折叠屏开合闪烁"
  - "方向适配Bug"
  - "Swiper 方向锁定"
  - "aboutToAppear 方向不恢复"
  - "Navigation 方向异常"
applies_when:
  - 遇到方向适配 Bug（强制竖屏、锁定失效、闪烁等）
  - 折叠屏展开态方向异常
  - Tabs/Swiper 方向锁定问题
  - 分屏/悬浮窗下旋转不生效
  - 折叠屏开合布局闪烁
not_applies_when:
  - 新需求设计，不涉及 Bug 修复
  - 纯概念理解，不涉及实际修复
decisions:
  - Bug 修复优先尊重开发者原有适配方式，在其方案基础上修复，不强制切换方案
  - 先归类问题类型（概念混淆/检测错误/映射错误），再选对应修复方案
  - 修复顺序统一为：监听入口 → 几何/状态 → 布局/交互 → 生命周期回收 → 回归验证
  - 概念不清时先加载 RSC_ORIENT_01 确认概念是否被混淆
deliverables:
  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_ORIENT_05
  - RSC_ORIENT_02
  - RSC_ORIENT_01
skill_to_path:
  - skill: 方向适配问题修复场景库
    path: ./references/bug-fix-cases.md
  - skill: 多设备方向适配
    path: ./references/orientation_adaptation.md

Resource Index

Complete resource cards have been moved down to ./references/resource-index.md, the main file retains only the retrieval entry and output contract.

Usage order:

  • Prioritize reading the P0 official path as the primary solution.
  • P1 Engineering template resources are supplementary only and cannot replace the official baseline.

Resource grouping:

  • Basic concepts:RSC_ORIENT_01
  • Detection and listening:RSC_ORIENT_03、RSC_ORIENT_06、RSC_ORIENT_07、RSC_ORIENT_08
  • Adaptation strategy:RSC_ORIENT_02、RSC_ORIENT_04、RSC_ORIENT_09、RSC_ORIENT_10
  • Issue fixing:RSC_ORIENT_05

Phase Output Contract

REQ

  • Must output:active_phases、primary_phase、primary_scene、secondary_scenes
  • Must output:device_constraints、capability_boundary、acceptance_focus
  • Additional requirements: clarify the current device form, natural orientation type, rotation strategy, and orientation adaptation goal

DEV

  • Must output:code_touchpoints、reuse_resources、implementation_notes、integration_risks
  • Additional requirements: clarify the rationale for rotation strategy selection, breakpoint determination logic, and lifecycle management (save/restore orientation)

FIX

  • Must output:problem_profile、root_cause_hypothesis、fix_plan、regression_watchlist
  • Additional requirements: clarify whether the issue is conceptual confusion, detection error, or mapping error; prioritize fixing based on the original solution

VAL

  • Must output:verification_matrix、evidence_requirements、pass_criteria、residual_risks
  • Additional requirements: include at least orientation behavior evidence for each device form, hdc logs (rotation/orientation values), and verify that orientation restoration is correct

Orientation Quick Reference

Device Natural orientation Meaning of rotation=0 Whether rotation is supported by default
Bar phone Portrait PORTRAIT No
Folding screen folded state Portrait PORTRAIT No
Folding screen unfolded state Portrait PORTRAIT No (but the home screen can rotate)
Tri-fold F/M state Portrait PORTRAIT No
Tri-fold G state Landscape LANDSCAPE_INVERTED Yes
Tablet Portrait PORTRAIT Yes
PC/2in1 Landscape LANDSCAPE Rotation policy not supported