> 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.