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 上檢視此頁面 • 報告此內容的錯誤