跳转到内容

Manifest 中的清单成员

orientation 清单成员

发布于 更新于

有限可用不支持的浏览器: Firefox (Desktop)、Safari (macOS)、Safari (iOS)W3C

清单成员 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() 需要用户激活;返回的字符串告诉界面是否 保留“请旋转设备”的提示。

规范

规范状态
Web 应用清单:orientationW3C
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
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
  1. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  2. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  3. browser-compat-data 未记录 Firefox 的支持。
  4. browser-compat-data 未记录 Safari 的支持。
  5. browser-compat-data 未记录 iOS 版 Safari 的支持。
  6. 由 browser-compat-data 镜像自 Safari 的数据推导。
  7. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
  8. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/manifest-orientation.json · 全球使用占比: 76 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-03 · 置信度: 高 (由来源计算)