# orientation：请求 PWA 的默认屏幕方向

> manifest 的 orientation 字段请求了什么、它与独立的 Screen Orientation API 是什么关系，以及取值未被遵循时会发生什么。

import CompatTable from '@components/CompatTable.astro';

**一句话：** manifest 的 `orientation` 字段为已安装 Web 应用的顶层窗口请求一个默认屏幕
方向——例如 `portrait` 或 `landscape`——具体是否生效取决于浏览器和设备是否真的遵循它。

## 支持情况

<CompatTable feature="manifest-orientation" />

根据 MDN 与规范，`orientation` 的支持情况与实际表现取决于浏览器和设备是否遵循所请求的
取值——请把它当作一种偏好，而非保证。

## 如何使用

在 Web 应用 manifest 中使用规范定义的关键字取值之一来声明该字段：

```json
{
  "name": "Field Journal",
  "start_url": "/",
  "display": "standalone",
  "orientation": "portrait"
}
```

规范定义的可接受取值包括 `any`、`natural`、`landscape`、`landscape-primary`、
`landscape-secondary`、`portrait`、`portrait-primary` 和 `portrait-secondary`。

## 如何在运行时检测

manifest 的 `orientation` 字段设置默认方向；该方向可以在运行时通过其他方式覆盖，包括
Screen Orientation API。这个独立 API 的 `lock()` 方法仅获得有限的浏览器支持，因此请在
调用前对其做特性检测，并在该方法不存在或调用被拒绝时让布局仍能适应：

```js
function supportsOrientationLock() {
  return 'orientation' in screen && typeof screen.orientation.lock === 'function';
}

async function lockPortrait() {
  if (!supportsOrientationLock()) {
    return; // 该浏览器没有 lock API：改用下方的响应式布局兜底
  }
  try {
    await screen.orientation.lock('portrait');
  } catch {
    // 处理拒绝的情况——lock() 的浏览器支持有限
  }
}
```

```css
/* 兜底方案：用 CSS 适配布局，而不是假设某种方向机制一定生效。 */
@media (orientation: landscape) {
  .journal-entry {
    grid-template-columns: 1fr 1fr;
  }
}
```

## 常见问题

- 根据 MDN 与规范，各个 `orientation` 取值的支持情况可能因浏览器和设备而异；用户代理
  会尝试遵循所请求的取值，但对其接受的每个取值都不保证一定生效。
- MDN 将 manifest 中的 orientation 描述为浏览器或操作系统尝试遵循的一种偏好，同时
  另外将 Screen Orientation API 记录为一种在运行时改变方向的方式——两者相关但属于不
  同的机制。
- 根据 MDN，省略 `orientation` 通常会回退到设备的自然方向，并结合用户或系统自身的方向
  设置，而不是单纯、保证生效的"自然方向"直通。
- manifest 的 `orientation` 字段与独立的 Screen Orientation API（`screen.orientation`）
  是两种彼此独立的能力——用户代理可以只支持其中一个而不支持另一个。

## 下一步

- [Web App Manifest：orientation 支持情况](/zh/compatibility/manifest-orientation/) —
  浏览器支持矩阵
- [Manifest display 模式：standalone 与 fullscreen](/zh/reference/manifest/display/) —
  该方向请求所处的显示模式