Manifest 中的清单成员
orientation 清单成员
发布于 更新于
清单成员 orientation 请求浏览器锁定已安装 Web 应用顶层窗口的默认方向,例如 portrait 或 landscape。应用采用应用式显示模式运行期间,锁定持续生效。清单设定默认方向,每当方向被解锁或窗口发生导航,浏览器都会恢复到这个方向;运行期间则可用 screen.orientation.lock() 改变锁定。
BCD(manifests.webapp.orientation)把该成员标为支持的有 Android 上的 Chrome 39、Samsung Internet 4.0、
Android WebView 39 与 Firefox for Android 79。桌面端的 Chrome 39 与 Edge 79 同样被标为支持,但 BCD 没有区分解析与锁定窗口,
而 screen.orientation.lock() 在桌面 Chromium 上总是被拒绝。桌面端 Firefox 以及 iOS 与 macOS 上的 Safari 被标为不支持。
规范把方向可以与哪些显示模式搭配交给各浏览器决定,并以 browser 模式举例,说明那里改变默认方向可能没有意义,
所以锁定预计在 fullscreen、standalone 和 minimal-ui 下出现,浏览器标签页里不会出现。
| 属性 | 值 |
|---|---|
| 类型 | 字符串,取 OrientationLockType 之一:any、natural、landscape、landscape-primary、landscape-secondary、portrait、portrait-primary 或 portrait-secondary。 |
| 默认值 | 缺省。MDN 说此时应用通常采用设备的自然方向,并遵循用户和系统的方向设置。 |
| 示例值 | "portrait"。 |
natural 是设备自身的默认方向(手机通常是竖屏,平板和显示器通常是横屏)。portrait 与
landscape 允许该轴向上的两种变体,所以支持 secondary 方向的手机倒过来拿仍然可读;-primary 与 -secondary 形式
只钉住其中一种。any 允许操作系统和用户设置所许可的所有方向,用来明确表示不限制;省略该成员时行为通常相近。
遇到列表之外的值,Chromium 会忽略该值,记录 unknown 'orientation' value ignored.,然后按没有该成员处理,清单的其余部分仍然有效。锁定属于应用窗口,会影响窗口内显示的 scope 内文档;同一 URL 在浏览器标签页中打开时不受影响。
浏览器不遵循方向锁定时,布局仍需适应横屏和竖屏。
为只用竖屏的外勤日志声明方向
链接到“为只用竖屏的外勤日志声明方向”一节一个表单按手机竖持布局的录入应用锁定为 portrait。在 Chrome for Android 上,已安装应用会无视
设备旋转;在浏览器标签页和 iOS 上,同一份清单没有效果,布局在横屏下仍然必须可用。
{ "name": "Field Journal", "short_name": "Journal", "start_url": "/", "display": "standalone", "orientation": "portrait"}设置 portrait 后,用户把设备掉头,支持 secondary 方向的设备上屏幕可以翻转 180 度。portrait-primary 会阻止这种旋转。
读取当前方向并响应变化
链接到“读取当前方向并响应变化”一节清单的锁定对脚本不可见,但它产生的方向是可见的。Screen Orientation API(MDN)通过
screen.orientation.type 报告方向,并在 screen.orientation 上触发 change,180 度掉头也会触发。没有该 API 的浏览器(iOS 16.4 之前的 Safari)走回退分支,
媒体查询只能读出轴向,所以 primary 与 secondary 之间的翻转不会被察觉。
function currentOrientation() { if ('orientation' in screen && screen.orientation?.type) { return screen.orientation.type; // 例如 "portrait-primary" } // 回退:没有 Screen Orientation API,从视口推断轴向。 return matchMedia('(orientation: portrait)').matches ? 'portrait' : 'landscape';}
function update() { document.documentElement.dataset.orientation = currentOrientation();}
if (screen.orientation?.addEventListener) { screen.orientation.addEventListener('change', update);} else { matchMedia('(orientation: portrait)').addEventListener('change', update);}update();清单锁定生效时,应用固定在单一轴向上,监听器最多只在该轴向两种变体之间翻转时触发;浏览器忽略锁定时,同一监听器可以在设备横过来时切换到双栏布局。
在清单被忽略的环境里于运行时锁定
链接到“在清单被忽略的环境里于运行时锁定”一节screen.orientation.lock() 可以从脚本施加同样的锁定,但有两个清单没有的限制:锁定通常只在移动设备和全屏状态下启用,
桌面端 Chrome 与 Edge 则总是以 NotSupportedError 拒绝调用(MDN,ScreenOrientation.lock() 及其兼容性数据)。
回退做法是什么都不做,依靠响应式布局。
async function lockPortraitIfPossible() { if (!('orientation' in screen) || typeof screen.orientation.lock !== 'function') { return 'unsupported'; // Safari:没有 lock(),布局保持响应式 } try { await document.documentElement.requestFullscreen(); await screen.orientation.lock('portrait'); return 'locked'; } catch (err) { // 桌面端 Chrome 与 Edge 以不支持为由拒绝;sandbox 缺少 `allow-orientation-lock` 的 iframe 中以安全错误拒绝。 return err.name; }}从 click 处理函数里调用它,因为 requestFullscreen() 需要用户激活;返回的字符串告诉界面是否
保留“请旋转设备”的提示。
另请参阅
链接到“另请参阅”一节- display 清单成员
- scope 清单成员
- WebAPK:Chrome 在 Android 上安装 PWA 的方式
- Web Application Manifest: orientation member(w3.org)
- ScreenOrientation: lock() method(developer.mozilla.org)
规范
| 规范 | 状态 |
|---|---|
| Web 应用清单:orientation | W3C |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| Chrome (Desktop)# | 支持 | 39 | 高 | 来源 | — |
| Chrome (Android)# | 支持 | 39 | 高 | 来源 | 1 |
| Edge (Desktop)# | 支持 | 79 | 高 | 来源 | 2 |
| Firefox (Desktop)# | 不支持 | — | 高 | 来源 | 3 |
| Firefox (Android)# | 支持 | 79 | 高 | 来源 | — |
| Safari (macOS)# | 不支持 | — | 高 | 来源 | 4 |
| Safari (iOS)# | 不支持 | — | 高 | 来源 | 56 |
| Samsung Internet# | 支持 | 4.0 | 高 | 来源 | 7 |
| WebView (Android)# | 支持 | 39 | 高 | 来源 | 8 |
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- browser-compat-data 未记录 Firefox 的支持。
- browser-compat-data 未记录 Safari 的支持。
- browser-compat-data 未记录 iOS 版 Safari 的支持。
- 由 browser-compat-data 镜像自 Safari 的数据推导。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。