> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/screen/properties.md).

# 屏幕属性

***

### 1. 设置屏幕方向（`setDeviceOrientation`)

将设备的屏幕方向设置为横屏或竖屏。如果只需要在特定屏幕上更改方向，离开该屏幕时请务必恢复为原来的方向。

**签名**

```typescript
function setDeviceOrientation(options: { type: 'portrait' | 'landscape' }): Promise<void>;
```

**参数**

* **options.type** · 必需 · `'portrait' | 'landscape'`

  设置屏幕方向。 `portrait`表示竖屏模式， `landscape`表示横屏模式。

**示例**

{% tabs %}
{% tab title="Web（JS）" %}

```js
import { setDeviceOrientation } from '@apps-in-toss/web-framework';

setDeviceOrientation({ type: 'landscape' });
```

{% endtab %}

{% tab title="Web（React）" %}

```tsx
import { setDeviceOrientation } from '@apps-in-toss/web-framework';
import { useEffect } from 'react';

function VideoScreen() {
  useEffect(() => {
    setDeviceOrientation({ type: 'landscape' });

    return () => {
      setDeviceOrientation({ type: 'portrait' }); // 离开屏幕时恢复。
    };
  }, []);
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { setDeviceOrientation } from '@apps-in-toss/framework';
import { useEffect } from 'react';

function VideoScreen() {
  useEffect(() => {
    setDeviceOrientation({ type: 'landscape' });

    return () => {
      setDeviceOrientation({ type: 'portrait' }); // 离开屏幕时恢复。
    };
  }, []);
}
```

{% endtab %}
{% endtabs %}

***

### 2. 设置屏幕常亮（`setScreenAwakeMode`)

设置为屏幕不会自动关闭。适用于漫画、视频、阅读文档等需要让屏幕持续亮着的场景。如果只在特定屏幕上使用，离开该屏幕时请务必停用。

**签名**

```typescript
function setScreenAwakeMode(options: { enabled: boolean }): Promise<{ enabled: boolean }>;
```

**参数**

* **options.enabled** · 必需 · `boolean`

  `true`设为时屏幕不会关闭， `false`设为时会根据默认的屏幕保护时间关闭。

**示例**

{% tabs %}
{% tab title="Web（React）" %}

```tsx
import { setScreenAwakeMode } from '@apps-in-toss/web-framework';
import { useEffect } from 'react';

function MediaScreen() {
  useEffect(() => {
    setScreenAwakeMode({ enabled: true });

    return () => {
      setScreenAwakeMode({ enabled: false }); // 离开屏幕时恢复。
    };
  }, []);
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { setScreenAwakeMode } from '@apps-in-toss/framework';
import { useEffect } from 'react';

function MediaScreen() {
  useEffect(() => {
    setScreenAwakeMode({ enabled: true });

    return () => {
      setScreenAwakeMode({ enabled: false }); // 离开屏幕时恢复。
    };
  }, []);
}
```

{% endtab %}
{% endtabs %}

***

### 3. 阻止屏幕截图（`setSecureScreen`)

在原生层面阻止屏幕截图。可用于显示账户余额、交易记录等敏感信息的屏幕。

**签名**

```typescript
function setSecureScreen(options: { enabled: boolean }): Promise<{ enabled: boolean }>;
```

**参数**

* **options.enabled** · 必需 · `boolean`

  `true`设为时会阻止屏幕截图， `false`设为时则允许。

**示例**

```tsx
import { setSecureScreen } from '@apps-in-toss/framework';
import { useEffect } from 'react';

function SecureScreen() {
  useEffect(() => {
    setSecureScreen({ enabled: true });

    return () => {
      setSecureScreen({ enabled: false }); // 离开屏幕时解除阻止。
    };
  }, []);
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/screen/properties.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.