多设备场景库

项目简介

多设备场景库（multidevicelibrary）是一个 HAR 公共库，为多设备应用提供基于场景的窗口方向管理与自适应布局能力。库内包含四大核心模块：

• 场景管理：基于栈的场景控制器（SceneController），在页面进出时推送/释放场景，自动重算并应用栈顶场景的方向配置。
• 窗口方向控制：提供固定方向（fixed）、自动旋转（autoRotate）、跟随桌面（followDesktop）三种方向策略，并封装窗口方向的读取、应用与恢复。
• 响应式规则引擎：基于条件（field/operator/value）的规则求值器，结合开发者自定义的 Context 实现按设备形态动态选择方向配置。
• 短视频自适应布局：提供 AdaptiveShortVideoScene（场景容器）与 AdaptiveVideoSurface（自适应渲容器），内置区域模式（RegionMode）与适配模式（FitMode）双层解析，实现短视频自适应缩放和沉浸。

库内置 20 种页面类型（PageType）的预设场景与方向配置，开箱即用。

效果预览

本库为代码库，无独立运行界面。其能力通过主工程的多设备场景示例（应用首页、横竖屏游戏、图库、个股详情/K线、长视频详情/全屏播放、短视频播放等）展示，详见主工程README。

使用说明

1. 在模块的 oh-package.json5 中添加依赖："multidevicelibrary": "file:../../commons/multidevicelibrary"。
2. 在 EntryAbility 中创建 ResponsiveContext（开发者自定义上下文）、OrientationController（绑定窗口与上下文）、SceneController（绑定 OrientationController），并将 SceneController 存入 AppStorage。
3. 监听窗口尺寸变化（windowSizeChange）与屏幕属性变化（display 'change'），在回调中更新 ResponsiveContext 并调用 scene.recompute() 重新解析方向。
4. 在业务页面的 aboutToAppear 中调用 scene.push(ScenePresets.XXX) 推送场景，在 aboutToDisappear 中调用 scene.release(layerId) 释放场景。
5. 短视频自适应布局使用：
   • 使用场景容器 AdaptiveShortVideoScene 包裹短视频内容区域，传入 overlayTop 和 overlayBottom（顶部状态栏/底部Tab占位高度），组件自动推送/释放 SHORT_VIDEO 场景。
   • 使用自适应渲容器 AdaptiveVideoSurface 包裹视频播放器，传入 videoWidth 和 videoHeight（视频原始宽高），AdaptiveVideoSurface 会自动计算并应用视频最终宽高与偏移。

工程目录

├──Index.ets                                 // 库对外导出入口
└──src/main/ets
   ├──context                                // 上下文
   │  ├──DefaultContext.ets                  // 上下文接口
   │  └──ContextTypes.ets                    // 接口定义
   ├──hover                                  // 悬停态监测
   │  ├──HoverDataStore.ets                  // 悬停态监测实现
   │  └──HoverProvider.ets                   // 悬停态上下文实现
   ├──orientation                            // 窗口方向控制
   │  ├──OrientationConfig.ets               // 方向配置类型（Fixed/AutoRotate/FollowDesktop）
   │  ├──OrientationController.ets           // 窗口方向应用控制器
   │  ├──OrientationStrategy.ets             // 方向策略到窗口Orientation的映射
   │  └──presets
   │     └──ResponsiveOrientationConfig.ets  // 按页面类型(PageType)的预设方向配置
   ├──responsiverule                         // 响应式规则引擎
   │  ├──ConditionValue.ets                  // 条件值类型
   │  ├──ResponsiveValue.ets                 // 响应式值类型别名
   │  ├──ResponsiveValueResolver.ets         // 规则解析器
   │  └──condition
   │     ├──Condition.ets                    // 条件接口
   │     ├──ConditionResponsiveValue.ets     // 条件响应式值接口
   │     ├──Operator.ets                     // 运算符枚举
   │     ├──OperatorPredicates.ets           // 运算符谓词实现
   │     └──Rule.ets                         // 规则接口
   ├──scene                                  // 场景管理
   │  ├──Scene.ets                           // 场景接口
   │  ├──SceneController.ets                 // 场景栈控制器
   │  ├──presets
   │  │  └──ScenePresets.ets                 // 预设场景集合
   │  └──shortvideo                          // 短视频自适应布局预设
   │     ├──component
   │     │  ├──AdaptiveShortVideoScene.ets   // 场景容器
   │     │  └──AdaptiveVideoSurface.ets      // 自适应渲染容器
   │     ├──material
   │     │  ├──Rule.ets                      // 响应式规则定义
   │     │  └──ShortVideoTypes.ets           // 类型定义
   │     └──runtime
   │        ├──FitModeResolver.ets           // 适配模式解析器
   │        └──RegionResolver.ets            // 区域模式解析器
   └──AbilityRegister.ets                    // 上下文注册

具体实现

1. 场景栈管理：SceneController 维护一个 SceneLayer 栈。push 时入栈并触发 recompute；release 时按 layerId 移除并触发 recompute。recompute 自底向上遍历栈，取最高的非空方向配置通过 OrientationController 应用；栈空时恢复入口方向快照。
2. 方向策略映射：OrientationStrategy 将 OrientationConfig 映射为窗口 window.Orientation。followDesktop 返回 FOLLOW_DESKTOP；fixed 按方向类型锁定；autoRotate 按范围返回受限自动旋转或用户旋转方向。
3. 响应式规则求值：ResponsiveValueResolver 将开发者 Context 视为 Record<string, ConditionValue>，遍历规则的每个条件，通过 OperatorPredicates 中的谓词判断字段值是否满足，首个全部条件匹配的规则其 value 生效，否则返回 defaultValue。
4. 预设配置：ResponsiveOrientationConfig 按 PageType 返回对应的方向配置；ScenePresets 为每种页面类型提供预设 Scene，二者一一对应。
5. 短视频自适应布局：采用双层解析模型。区域模式（RegionMode）：由 RegionResolver 解析，决定视频区域的整体布局方式。适配模式（FitMode）：由 FitModeResolver 根据视频原始宽高比与区域宽高比解析，决定视频在区域内的缩放方式。
6. 悬停态状态检测：监听系统悬停状态及当前折痕区方向，计算悬停态变量isHover。

相关权限

不涉及

约束与限制

1. 本库仅支持在标准系统上运行，支持设备：直板机、双折叠（Mate X系列）、三折叠、平板、电脑、车机、智慧屏。
2. HarmonyOS系统：HarmonyOS 6.1.0 Release及以上。
3. DevEco Studio版本：DevEco Studio 6.1.0 Release及以上。
4. HarmonyOS SDK版本：HarmonyOS 6.1.0 Release SDK及以上。