## 权限
无需在 `heybox.permissions` 中声明。详见[权限声明](../../../guide/permissions.md)。
## 兼容性
| 项目 | 内容 |
| --- | --- |
| 加入版本 | SDK `0.8.3` |
| 支持平台 | `android`、`ios`、`ohos` |
| 客户端要求 | `android: numeric-dot >= 1.3.396`（API 专属门槛）、`ios: numeric-dot >= 1.3.396`（API 专属门槛）、`ohos: numeric-dot >= 1.3.396`（API 专属门槛） |
| 稳定性 | experimental |
## 参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `options` | `SetDisplayPayload` | 方向与全屏目标，至少提供一个字段；省略的字段保持当前目标值。 |
## 相关类型
- [`SetDisplayPayload`](../../symbols/root/interfaces/SetDisplayPayload.md)
- [`SetDisplayResult`](../../symbols/root/types/SetDisplayResult.md)
## 返回值
Host 完成原生方向与胶囊设置、布局稳定后返回 `{ supported: true }`；能力缺失或
请求不受支持时返回 `{ supported: false }`，调用方仍应按实际窗口与安全区布局。
## 异常
- HbMiniProgramSDKError `INVALID_PARAMS` 表示参数不合法；
`ORIENTATION_TIMEOUT` 表示展示操作超时，`ORIENTATION_FAILED` 表示执行失败，
`ORIENTATION_SUPERSEDED` 表示被后续不同目标替代，`REQUEST_CANCELLED` 表示操作已取消。
SDK 或 Runtime 销毁、握手失败等其他错误保留对应 SDK 错误码。
## 说明
新容器默认竖屏、非全屏。省略字段保持当前目标值，至少传一个字段；合并后横屏强制全屏，竖屏按 fullscreen 控制。
全屏同时收起胶囊和宿主额外顶部栏，不保证原生内容铺满容器；页面应按实际 WebView 窗口和安全区适配。
系统状态栏、手势条不保证隐藏，重要控件仍应按实际窗口与安全区信息避让。
横屏时仅设置 fullscreen: false 不会退出全屏；退出需同时设置 orientation: portrait、fullscreen: false。
宿主退出按钮恢复竖屏、非全屏；仅设置 orientation: portrait 则保留当前全屏目标。
设置持续到下次调用或退出容器；SPA 路由应在进入时明确设置所需状态。
后续设置先合并目标，再取消不同的旧设置；旧调用以 ORIENTATION_SUPERSEDED 失败。
相同目标共用操作；方向和全屏一起确认，失败时一起恢复最后确认状态。
本方法等待 Host 展示操作完成，由 Runtime 的操作截止时间控制，不使用普通 bridge 请求的独立超时计时器。
操作超时或 SDK 销毁会向 Host 传递取消；不要依赖迟到的 Host 成功结果推进业务状态。
窗口尺寸与安全区变化通过 viewport_change 事件通知。
方向或全屏状态确认变化时通过 display_change 通知，包括用户点击宿主退出全屏按钮。
display_change 不回放初始状态；重复设置、不支持、失败或取消不会发出展示状态变化通知。
返回 supported: true 表示原生方向与胶囊设置已完成；不支持时返回 supported: false，保留原生状态。
降级时宿主仍尽力收起 H5 顶部栏，不能据此假定屏幕已旋转或胶囊已隐藏；布局始终按实际窗口适配。
SDK 统一处理能力缺失错误；超时、取消、参数或其他执行错误仍抛出。
## 示例
```ts
import hbSDK from '@heybox/hb-sdk'
// 同时恢复竖屏和非全屏，避免保留之前的全屏目标。
const result = await hbSDK.viewport.setDisplay({ orientation: 'portrait', fullscreen: false })
if (!result.supported) console.log('Host 不支持原生展示设置')
```
## 浏览
- 上一个：[`viewport.getWindowInfo`](./getWindowInfo.md)
- 下一个：[`viewport.setNavigationBarStyle`](./setNavigationBarStyle.md)