From 3a333bfe325f1b517def1e3e554624fdfc76ca6d Mon Sep 17 00:00:00 2001 From: lanterngamescn Date: Thu, 25 Jun 2026 08:26:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E6=A8=AA=E5=B1=8F?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E7=BA=A6=E6=9D=9F=EF=BC=88=E9=BB=98=E8=AE=A4?= =?UTF-8?q?=E6=A8=AA=E5=B1=8F=E3=80=81=E4=B8=8D=E6=94=AF=E6=8C=81=E7=AB=96?= =?UTF-8?q?=E5=B1=8F=E8=87=AA=E5=8A=A8=E6=97=8B=E8=BD=AC=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 契约规范 §7：新增屏幕方向约束——默认横屏、不跟随传感器自动旋转； 但遵守 H5 零改动铁律，保留 orientation/SwitchOverGameData webtype/通用网页 orientation 三处 H5 显式方向控制（含竖屏），与原 Android 一致 - 框架指南 §7.4：实现落地——module.json5 orientation:landscape 默认横屏 + 运行时 window.setPreferredOrientation 按 H5 请求动态切换 - 经核对原 Android：上述三处确为真实竖屏切换（非死代码），故定调为 '默认横屏 + 不破坏 H5 方向控制' Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/设计文档/TSGame_HarmonyOS框架设计与开发指南.md | 12 ++++++++++++ docs/设计文档/TSGame_原生与H5接口契约总规范.md | 9 +++++++++ 2 files changed, 21 insertions(+) diff --git a/docs/设计文档/TSGame_HarmonyOS框架设计与开发指南.md b/docs/设计文档/TSGame_HarmonyOS框架设计与开发指南.md index ce8bff1..f998063 100644 --- a/docs/设计文档/TSGame_HarmonyOS框架设计与开发指南.md +++ b/docs/设计文档/TSGame_HarmonyOS框架设计与开发指南.md @@ -539,6 +539,18 @@ export struct GenericWebContainer { H5 以 `file://` 加载并请求本地/远程资源。HarmonyOS 侧采用官方"Web 页面跨域解决方案"：用 `onInterceptRequest` 自定义本地资源响应，或为本地页配置自定义协议/响应头，避免 file 同源限制。**对 H5 透明**。 +### 7.4 屏幕方向（横屏项目） + +本项目为**横屏项目**：应用**默认横屏、不跟随设备传感器自动旋转**；同时**遵守 H5 零改动铁律**，完整保留 H5 经方向接口显式切换（含竖屏）的能力，与原 Android 一致（《契约规范》§7 屏幕方向约束 / §8.4 / §11）。落地方式： + +- **默认横屏**：`EntryAbility` 在 `module.json5` 配 `"orientation": "landscape"`（启动即横屏、不随重力感应自动转竖屏）。 +- **H5 动态切换（保留竖屏能力）**：方向接口收到请求时用窗口 API **动态覆盖**，不写死锁定—— + - `AppSystemProvider` 的 `orientation` handler：`data === '1'` → 横屏，否则 → 竖屏（对齐 Android `setRequestedOrientation`）； + - 子游戏 `SwitchOverGameData`：按 `webtype`（`"3"` 横 / `"2"` 竖）设方向后再 `loadUrl`； + - `GenericWebContainer`：按打开参数 `orientation`（`"1"` 竖 / 其他 横）设方向。 +- **实现 API**：运行时 `window.Window.setPreferredOrientation(orientation: window.Orientation)` 动态切换，`window.Orientation` 取 `LANDSCAPE` / `PORTRAIT`（编码前用 `devecocli docs` 核对签名）。 +- **要点**：`module.json5` 的 `landscape` 提供"默认横屏 + 禁传感器自动转"，运行时 `setPreferredOrientation` 提供"H5 显式切换"——二者叠加既满足横屏项目定位，又守住 H5 零改动。 + --- ## 8. 启动编排与配置/资源子系统 diff --git a/docs/设计文档/TSGame_原生与H5接口契约总规范.md b/docs/设计文档/TSGame_原生与H5接口契约总规范.md index a2cbde5..d8cc3e2 100644 --- a/docs/设计文档/TSGame_原生与H5接口契约总规范.md +++ b/docs/设计文档/TSGame_原生与H5接口契约总规范.md @@ -430,6 +430,15 @@ gameconfig 值 = "tsgames.daoqi88.cn-config_test-update_jsonv2_test" | UserAgent | **未自定义**（用平台默认） | H5 不依赖特定 UA | | Cookie | 未特殊配置 | — | | 远程调试 | 启用（开发期） | — | +| 屏幕方向 | **默认横屏**，不跟随设备传感器自动旋转 | 横屏项目；H5 仍可经方向接口显式切换（见下） | + +> **🔴 屏幕方向约束（横屏项目）**：本项目为**横屏项目**，应用**默认横屏、不跟随设备重力传感器自动旋转**。 +> 但**遵守 H5 零改动铁律**：H5 经方向接口发起的显式切换**行为完全不变**，与原 Android 一致—— +> - `orientation` handler（§8.4）：`"1"` → 横屏，**非 `"1"` → 竖屏**（原生仍真实切竖屏，对齐 Android `setRequestedOrientation`）； +> - 子游戏 `SwitchOverGameData` 的 `webtype`（§11.1）：`"3"` 横屏 / `"2"` 竖屏； +> - 通用网页 `OpenurlTitleData` 的 `orientation`（§11.2）：`"1"` 竖屏 / 其他 横屏。 +> +> 即"不支持竖屏"指 **默认横屏、不随传感器自动转屏**，**不是**禁止 H5 控制方向。原生以"默认横屏 + 按 H5 请求动态切换方向"落地（见框架文档 §7.4），从而既是横屏项目，又不破坏 H5 零改动。 容器还需提供： - **本机 HTTP 服务**：用于"截图分享上传"。容器启动一个本机 HTTP server，把地址（`http://<本机IP>:<端口>/testurl`）通过桥 `setPostUrl` 推给 H5（见 §9）。新平台需提供等价的本机上传端点能力，否则截图分享链路不通。