orientation

可用性有限

此特性不是基线特性，因为它在一些最广泛使用的浏览器中不起作用。

orientation 清单成员用于指定 Web 应用的默认方向。它定义了应用启动和使用期间应如何显示，相对于设备的屏幕方向，尤其是在支持多种方向的设备上。

注意：应用的方向可以在运行时通过多种方式更改，例如使用屏幕方向 API。

语法

json

/* Keyword values */
"orientation": "any"
"orientation": "natural"
"orientation": "portrait"
"orientation": "portrait-primary"
"orientation": "portrait-secondary"
"orientation": "landscape"
"orientation": "landscape-primary"
"orientation": "landscape-secondary"

值

orientation

一个字符串，用于指定 Web 应用的默认方向。如果未指定 orientation 成员或提供了无效值，Web 应用通常会使用设备的自然方向以及任何用户或系统级别的方向设置。

orientation 值必须是以下关键字之一

任意

以设备操作系统或用户设置允许的任何方向显示 Web 应用。它允许应用自由旋转以匹配设备方向的变化。

natural

以浏览器、操作系统、用户设置或屏幕本身确定的设备最自然的方向显示 Web 应用。它对应于设备最常见的握持或使用方式。

在通常垂直握持的设备上，例如手机，natural 通常是 portrait-primary。
在通常水平使用的设备上，例如电脑显示器和平板电脑，natural 通常是 landscape-primary。

当设备旋转时，应用可能会或可能不会旋转以匹配设备的自然方向；此行为可能因特定设备、浏览器实现和用户设置而异。

portrait（纵向）

以高度大于宽度的方向显示 Web 应用。它允许应用在设备旋转时在 portrait-primary 和 portrait-secondary 方向之间切换。

portrait-primary

以纵向模式显示 Web 应用，通常是设备竖直握持。这通常是自然纵向设备的默认应用方向。根据设备和浏览器实现，即使设备旋转，应用通常也会保持此方向。

portrait-secondary

以反向纵向模式显示 Web 应用，即 portrait-primary 旋转 180 度。根据设备和浏览器实现，即使设备旋转，应用通常也会保持此方向。

landscape（横向）

以宽度大于高度的方向显示 Web 应用。它允许应用在设备旋转时在 landscape-primary 和 landscape-secondary 方向之间切换。

landscape-primary

以横向模式显示 Web 应用，通常是设备处于其标准水平位置。这通常是自然横向设备的默认应用方向。根据设备和浏览器实现，即使设备旋转，应用通常也会保持此方向。

landscape-secondary

以反向横向模式显示 Web 应用，即 landscape-primary 旋转 180 度。根据设备和浏览器实现，即使设备旋转，应用通常也会保持此方向。

描述

要理解 orientation 清单成员，熟悉以下与方向相关的概念很重要

设备方向：定义设备在物理上如何握持或放置。
屏幕方向：定义设备显示屏的物理方向。
应用方向：定义应用的内容相对于屏幕方向的显示方式。

当设备旋转时，它通常会改变屏幕方向。例如，将手机从垂直方向旋转到水平方向通常会将屏幕从纵向模式切换到横向模式。在清单中没有指定特定方向的情况下，大多数应用都会调整其布局以适应新的屏幕方向。

清单的 orientation 成员允许您控制应用如何响应这些变化。通过为应用指定首选方向，您可以决定应用是应该适应屏幕方向的变化，还是在不考虑设备如何握持的情况下保持固定的布局。例如，通过设置 "orientation": "portrait-primary"，您可以指示您的应用首选始终以相对于屏幕的竖直纵向模式显示，即使设备已旋转。浏览器或操作系统将在可能的情况下尝试满足此偏好。

下面的示例说明了在手机旋转时 Web 应用的布局可能如何显示。在此示例中，假设应用的 orientation 值设置为 any，允许应用在手机旋转时在所有 orientation 值之间旋转。还假设手机和浏览器都支持所有方向。此序列显示了手机的顺时针旋转，每个位置相对于起始位置的旋转如下

左上角：portrait-primary（起始位置）
右上角：landscape-primary（90 度）
左下角：portrait-secondary（180 度）
右下角：landscape-secondary（270 度）

<div class="container">
  <div class="orientation">
    <div class="device portrait-primary">
      <div class="screen">
        <div class="title-bar">App Title Bar</div>
        <div class="content">App content in portrait mode</div>
      </div>
    </div>
    <div class="label"><code>portrait-primary</code></div>
  </div>
  <div class="orientation">
    <div class="device landscape-primary">
      <div class="screen">
        <div class="title-bar">App Title Bar</div>
        <div class="content">App content in landscape mode</div>
      </div>
    </div>
    <div class="label"><code>landscape-primary</code></div>
  </div>
  <div class="orientation">
    <div class="device portrait-secondary">
      <div class="screen">
        <div class="title-bar">App Title Bar</div>
        <div class="content">App content in inverted portrait mode</div>
      </div>
    </div>
    <div class="label"><code>portrait-secondary</code></div>
  </div>
  <div class="orientation">
    <div class="device landscape-secondary">
      <div class="screen">
        <div class="title-bar">App Title Bar</div>
        <div class="content">App content in inverted landscape mode</div>
      </div>
    </div>
    <div class="label"><code>landscape-secondary</code></div>
  </div>
</div>

.container {
  display: grid;
  grid-template-columns: 1fr 1fr;
  grid-gap: 40px;
  padding: 20px;
}

.orientation {
  display: flex;
  flex-direction: column;
  align-items: center;
  text-align: center;
}

.device {
  width: 200px;
  height: 300px;
  border: 5px solid black;
  border-radius: 20px;
  position: relative;
  background-color: white;
  margin-bottom: 10px;
}

.screen {
  width: 180px;
  height: 280px;
  border-radius: 15px;
  background-color: lightgrey;
  margin: 10px;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.title-bar {
  background-color: #4285f4;
  color: white;
  padding: 5px;
  text-align: center;
  font-weight: bold;
}

.content {
  flex-grow: 1;
  display: flex;
  justify-content: center;
  align-items: center;
  padding: 10px;
  text-align: center;
}

.landscape-primary,
.landscape-secondary {
  width: 300px;
  height: 200px;
}

.landscape-primary .screen,
.landscape-secondary .screen {
  width: 280px;
  height: 180px;
}

.portrait-secondary {
  transform: rotate(180deg);
}

.landscape-secondary {
  transform: rotate(180deg);
}

.label {
  margin-top: 10px;
  font-family: "Arial", sans-serif;
  font-size: 15px;
}

作用域和默认行为

指定的 orientation 应用于 Web 应用的所有顶层浏览上下文。

如果浏览器支持指定的 orientation 值，它将在应用生命周期中将其用作默认的应用方向，除非在运行时被覆盖。这意味着每当顶层浏览上下文发生导航时，浏览器都将恢复到此默认方向。

为 Web 应用选择首选方向

通过设置特定的方向，您可以确保您的 Web 应用针对其内容和用户界面进行最佳显示。例如，视频应用通常更适合横向方向，而阅读应用通常在纵向方向上效果更好。

不指定方向也可以是一种刻意的选择，允许您的 Web 应用灵活地适应不同的设备和用户偏好。

Manifest `orientation` 与屏幕方向 API 行为

虽然 orientation 清单成员设置了 Web 应用的默认方向，但一旦 Web 应用正在运行，就可以使用屏幕方向 API 来更改顶层浏览上下文的方向。

orientation 值在 Web 应用清单和屏幕方向 API 中是相似的，但它们的行为和目的不同。

Web 应用清单
- 使用 orientation 清单成员建议 Web 应用的首选默认方向。
- 设置应用启动时的初始方向。
Screen Orientation API
- 使用方向值将屏幕锁定到特定方向。
- 允许在运行时动态更改方向（例如，使用 screen.orientation.lock() 锁定方向）。
注意：屏幕方向 API 的 lock() 方法在浏览器中的支持有限。如果您打算在运行时使用它来动态更改屏幕方向，请检查其兼容性。

平台和浏览器限制

在为您的应用添加方向偏好时，请牢记以下注意事项和限制

浏览器供应商和设备制造商决定哪些方向和 display 模式是兼容的。
某些 UI/UX 考虑和平台约定可能会限制可以一起使用的屏幕方向和显示模式。
特定 orientation 值的支持可能因设备和平台而异。
某些设备可能不支持所有 orientation 值，例如 portrait-secondary 和 landscape-secondary。
某些浏览器可能不允许在某些显示模式下（例如 "display": "browser"）更改 Web 应用的默认方向。

示例

为 Web 应用指定固定方向

此示例将应用的方向设置为 portrait-primary。假设浏览器和设备支持，即使设备旋转，该应用也将始终以竖直纵向模式显示。

json

{
  "name": "My Web App",
  "orientation": "portrait-primary"
}

为 Web 应用设置灵活方向

考虑一个照片查看和编辑应用。在应用的清单文件中，如下所示，orientation 设置为 any。这允许应用以设备当前的方向启动，并适应 portrait 和 landscape 方向， as users rotate their devices。此 orientation 设置将使用户能够在最适合当前显示或其当前使用场景的任何方向上舒适地查看和编辑照片。

json

{
  "name": "PhotoGallery Pro",
  "short_name": "PhotoGal",
  "description": "A professional photo gallery and editing application",
  "start_url": "/index.html",
  "display": "standalone",
  "orientation": "any",
  "icons": [
    {
      "src": "icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ],
  "related_applications": [
    {
      "platform": "play",
      "url": "https://play.google.com/store/apps/details?id=com.example.photogallery"
    }
  ]
}

规范

规范
Web 应用清单 # orientation-member

浏览器兼容性

另见

帮助改进 MDN

了解如何贡献

此页面最后修改于 2025年10月13日，由 MDN 贡献者修改。

在 GitHub 上查看此页面 • 报告此内容的错误