多设备场景库
项目简介
多设备场景库（multidevicelibrary）是一个 HAR 公共库，为多设备应用提供基于场景的窗口方向管理与自适应布局能力。库内包含四大核心模块：
- 场景管理：基于栈的场景控制器（SceneController），在页面进出时推送/释放场景，自动重算并应用栈顶场景的方向配置。
- 窗口方向控制：提供固定方向（fixed）、自动旋转（autoRotate）、跟随桌面（followDesktop）三种方向策略，并封装窗口方向的读取、应用与恢复。
- 响应式规则引擎：基于条件（field/operator/value）的规则求值器，结合开发者自定义的 Context 实现按设备形态动态选择方向配置。
- 短视频自适应布局：提供 AdaptiveShortVideoScene（场景容器）与 AdaptiveVideoSurface（自适应渲容器），内置区域模式（RegionMode）与适配模式（FitMode）双层解析，实现短视频自适应缩放和沉浸。
库内置 20 种页面类型（PageType）的预设场景与方向配置，开箱即用。
效果预览
本库为代码库，无独立运行界面。其能力通过主工程的多设备场景示例（应用首页、横竖屏游戏、图库、个股详情/K线、长视频详情/全屏播放、短视频播放等）展示，详见主工程README。
使用说明
- 在模块的 oh-package.json5 中添加依赖：
"multidevicelibrary": "file:../../commons/multidevicelibrary"。 - 在 EntryAbility 中创建 ResponsiveContext（开发者自定义上下文）、OrientationController（绑定窗口与上下文）、SceneController（绑定 OrientationController），并将 SceneController 存入 AppStorage。
- 监听窗口尺寸变化（windowSizeChange）与屏幕属性变化（display 'change'），在回调中更新 ResponsiveContext 并调用 scene.recompute() 重新解析方向。
- 在业务页面的 aboutToAppear 中调用 scene.push(ScenePresets.XXX) 推送场景，在 aboutToDisappear 中调用 scene.release(layerId) 释放场景。
- 短视频自适应布局使用：
- 使用场景容器
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 // 上下文注册
具体实现
- 场景栈管理：SceneController 维护一个 SceneLayer 栈。push 时入栈并触发 recompute；release 时按 layerId 移除并触发 recompute。recompute 自底向上遍历栈，取最高的非空方向配置通过 OrientationController 应用；栈空时恢复入口方向快照。
- 方向策略映射：OrientationStrategy 将 OrientationConfig 映射为窗口 window.Orientation。followDesktop 返回 FOLLOW_DESKTOP；fixed 按方向类型锁定；autoRotate 按范围返回受限自动旋转或用户旋转方向。
- 响应式规则求值：ResponsiveValueResolver 将开发者 Context 视为 Record<string, ConditionValue>，遍历规则的每个条件，通过 OperatorPredicates 中的谓词判断字段值是否满足，首个全部条件匹配的规则其 value 生效，否则返回 defaultValue。
- 预设配置：ResponsiveOrientationConfig 按 PageType 返回对应的方向配置；ScenePresets 为每种页面类型提供预设 Scene，二者一一对应。
- 短视频自适应布局：采用双层解析模型。区域模式（RegionMode）：由 RegionResolver 解析，决定视频区域的整体布局方式。适配模式（FitMode）：由 FitModeResolver 根据视频原始宽高比与区域宽高比解析，决定视频在区域内的缩放方式。
- 悬停态状态检测：监听系统悬停状态及当前折痕区方向，计算悬停态变量isHover。
相关权限
不涉及
约束与限制
- 本库仅支持在标准系统上运行，支持设备：直板机、双折叠（Mate X系列）、三折叠、平板、电脑、车机、智慧屏。
- HarmonyOS系统：HarmonyOS 6.1.0 Release及以上。
- DevEco Studio版本：DevEco Studio 6.1.0 Release及以上。
- HarmonyOS SDK版本：HarmonyOS 6.1.0 Release SDK及以上。