# 适配横竖屏

开放平台提供了小程序的全局页面方向配置，以及单个页面方向配置的能力。当小程序页面中包含宽度较大的图表或其他在竖屏页面不方便查看的内容时，可以选择适配横屏进行旋转查看。

## 使用限制

小程序适配横竖屏功能支持的客户端版本或操作系统如下：

- 飞书: V5.26 版本及以上

- 开发者工具: V2.25 版本及以上

- 操作系统: Android、iOS

## 配置方式

适配横竖屏的功能配置方式分为全局配置（app.json 文件）和单个页面配置（页面的 json 文件）。

### app.json 文件

在配置文件中的 window 字段内，新增了 pageOrientation 字段。整个小程序所有页面将根据 pageOrientation 的配置显示页面方向。参数的取值范围如下：

- auto：跟随系统设备方向。不支持竖屏反方向的旋转，即将设备旋转 180 度。
- landscape：强制横屏，支持正反方向的横屏。
- portrait（默认值）：强制竖屏。

示例代码如下所示。

```json
"window": {
  "pageOrientation": "auto"
}
```

### 页面的 json 文件

在配置文件中新增了 pageOrientation 字段。当前页面将根据 pageOrientation 的配置显示页面方向。参数的取值范围如下：

- auto：跟随系统设备方向。不支持竖屏反方向的旋转，即将设备旋转 180 度。
- landscape：强制横屏，支持正反方向的横屏。
- portrait（默认值）：强制竖屏。

示例代码如下所示。

```json
{
  "pageOrientation": "auto"
}
```

### 注意事项

- 配置 `"pageOrientation": "auto"` 的页面在跟随系统设备方向旋转时，需依赖系统旋转开关(Android、iOS)，该开关关闭情况下，小程序不会跟随系统设备方向旋转页面方向。
- 如果页面 json 文件和 app.json 文件都配置了 pageOrientation 参数，则当前页面以页面 json 文件的配置为准。
- 由于系统限制，在设备竖屏的情况，从 landscape 页面跳转回 auto 页面时：iOS 页面仍为横屏、Android 页面会变为竖屏。
- 你也可以通过 [setPageOrientation](https://open.feishu.cn/document/uYjL24iN/uEDO3UjLxgzN14SM4cTN/setpageorientation) 接口设置当前小程序页面方向。

## 相关操作

### 监听屏幕旋转事件

当页面发生翻转的时候, 可以通过 onResize 接口获取当前页面方向和尺寸。该接口本质是一个页面监听函数，其作用域与 onShow 等其他页面监听函数一致。关于接口的参数说明以及示例代码，参见 [onResize](https://open.feishu.cn/document/uYjL24iN/uEDO3UjLxgzN14SM4cTN/onresize)。

### 获取当前页面方向

通过 [tt.getSystemInfo](https://open.feishu.cn/document/uYjL24iN/uQjNx4CN2EjL0YTM) 或 [tt.getSystemInfoSync](https://open.feishu.cn/document/uYjL24iN/uUjNx4SN2EjL1YTM) 接口可获取当前页面方向，在以上接口的返回结果中，包含了 `pageOritation` 属性，值为 `portrait`（竖屏） 、 `landscape`（横屏正方向，以 HOME 键在屏幕右侧为正方向）或 `landscapeReverse`(横屏反方向，以 HOME 键在屏幕左侧为反方向)。

此外，如果你的小程序配置的是自定义导航栏，在横竖屏切换收到 onResize 回调时，可通过 getSystemInfo 接口重新获取当前页面新的 `statusBarHeight` 和 `navigationBarSafeArea`，用于重新计算自定义导航栏的尺寸。

#### 示例代码

```js
tt.getSystemInfo({ 
    success(res) {
      console.log(JSON.stringify(res));
    },
    fail(res) {
      console.log(`getSystemInfo fail: ${JSON.stringify(res)}`);
    }
});
```

#### 回调函数返回对象示例

```json
{
    "pixelRatio": 3,
    "pageOrientation": "portrait",
    "version": "5.17.0-alpha",
    "nativeSDKVersion": "2.46.0",
    "platform": "ios",
    "statusBarHeight": 47,
    "wifiSignal": 4,
    "language": "zh_CN",
    "benchmarkLevel": 40,
    "fontSizeSetting": 16,
    "model": "iPhone14,2",
    "screenWidth": 390,
    "windowWidth": 390,
    "errMsg": "getSystemInfo:ok",
    "screenHeight": 844,
    "appName": "Feishu",
    "SDKUpdateVersion": "1.9.72.2",
    "navigationBarSafeArea": "",
    "gadgetVersion": "preview",
    "SDKVersion": "1.9.72",
    "battery": 100,
    "system": "iOS 15.4.1",
    "windowHeight": 753,
    "safeArea": {
            "bottom": 810,
            "left": 0,
            "top": 47,
            "width": 390,
            "right": 390,
            "height": 763
    },
    "brand": "Apple",
    "devicePixelRatio": 3
}
```

### 在开发者工具内调试小程序

在开发小程序阶段，你可以在[开发者工具](https://open.feishu.cn/document/uYjL24iN/ucDOzYjL3gzM24yN4MjN)的模拟器中，通过旋转功能模拟页面横竖屏的样式和效果。

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/6d46edfdbb39345b19f6c4097cc7c387_uglkZudbHO.png?height=236&lazyload=true&maxWidth=500&width=964)

## 已知问题

### API & 组件

横屏下的部分 API 和组件的适配能力在逐步完善中，可能存在部分控件在横屏下显示效果不正确的情况。在开发测试阶段需要注意小程序实际展示效果是否符合预期。

### iOS 系统

在 iOS 系统中，小程序首次从强制横屏页面进入后台再返回前台时，页面布局会存在异常。如果在此之前，飞书已经进入过后台，则不会出现该异常。