> 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/integration/props.md).

# 控制 WebView 的属性

本文档中，为了控制 WebView 的行为方式 `apps-in-toss.config.ts`中可以设置的 `webView` 选项进行说明。 

如滚动行为、媒体播放方式、是否使用手势等 **会直接影响用户体验的 WebView 属性**可以根据服务特性进行调整。

{% hint style="info" %}
**支持环境**

* 运行环境：WebView、Toss 应用
* SDK 版本：WebView 3.x 及以上
  {% endhint %}

## WebView 属性设置方法

WebView 属性 `apps-in-toss.config.ts` 文件的 `webView` 项目中设置。

```ts
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  webView: {
    // 与 WebView 行为相关的选项
  },
});
```

{% hint style="warning" %}
SDK 2.x 中的 `granite.config.ts`和 `webViewProps`在 SDK 3.x 中分别 `apps-in-toss.config.ts`, `webView`更名为。子选项保持不变。
{% endhint %}

## 可用的 WebView 属性

`webView`中可以设置以下属性。

```ts
webView?: {
  allowsInlineMediaPlayback?: boolean;
  bounces?: boolean;
  pullToRefreshEnabled?: boolean;
  overScrollMode?: 'always' | 'content' | 'never';
  mediaPlaybackRequiresUserAction?: boolean;
  allowsBackForwardNavigationGestures?: boolean;
};
```

### 允许内联媒体播放（`allowsInlineMediaPlayback`)

设置 HTML5 视频是否不以全屏而是在 WebView 内部以内联方式播放。

这是仅适用于 iOS 的属性， `true`设置为 `<video>` 标签中 `webkit-playsinline` 属性，才能进行内联播放。

| 项目  | 内容        |
| --- | --------- |
| 类型  | `boolean` |
| 默认值 | `false`   |
| 平台  | iOS       |

### 使用滚动回弹效果（`bounces`)

设置在到达滚动区域末端时是否使用回弹效果。

这是仅适用于 iOS 的属性，默认值为 `true`。

| 项目  | 内容        |
| --- | --------- |
| 类型  | `boolean` |
| 默认值 | `true`    |
| 平台  | iOS       |

### 启用下拉刷新（`pullToRefreshEnabled`)

设置是否启用向下拖拽刷新（Pull-to-Refresh）行为。

这是仅适用于 iOS 的选项，默认值为 `true`为。将此值 `true`设置为 `bounces` 选项也会自动 `true`被设置为 \`unavailable\`。

| 项目  | 内容        |
| --- | --------- |
| 类型  | `boolean` |
| 默认值 | `true`    |
| 平台  | iOS       |

### 设置超滚动行为方式（`overScrollMode`)

设置在到达滚动内容末端时，Android 如何处理超滚动效果。

| 项目  | 内容                                 |
| --- | ---------------------------------- |
| 类型  | `'always' \| 'content' \| 'never'` |
| 默认值 | `'always'`                         |
| 平台  | Android                            |

各值的含义如下。

| 值           | 说明                         |
| ----------- | -------------------------- |
| `'always'`  | 无论内容大小，都允许超滚动效果。           |
| `'content'` | 仅当内容比 WebView 更大时才允许超滚动效果。 |
| `'never'`   | 不使用超滚动效果。                  |

参考： [Android 官方文档](https://developer.android.com/reference/android/view/View#OVER_SCROLL_NEVER)

### 限制媒体自动播放（`mediaPlaybackRequiresUserAction`)

设置是否限制音频或视频自动播放。

将此值 `true`设置为后，需要用户手动点击，媒体才会播放。在 Android 上，此选项仅在 17 及以上版本中生效。

| 项目  | 内容           |
| --- | ------------ |
| 类型  | `boolean`    |
| 默认值 | `true`       |
| 平台  | iOS, Android |

参考： [react-native-webview mediaPlaybackRequiresUserAction](https://github.com/react-native-webview/react-native-webview/blob/v13.6.2/docs/Reference.md#mediaplaybackrequiresuseraction)

### 允许通过滑动返回/前进（`allowsBackForwardNavigationGestures`)

设置是否允许通过左右滑动手势进行后退或前进导航。

将此值 `false`设置为后，用户将无法通过滑动手势切换页面。

| 项目  | 内容        |
| --- | --------- |
| 类型  | `boolean` |
| 默认值 | `true`    |
| 平台  | iOS       |

参考： [react-native-webview allowsBackForwardNavigationGestures](https://github.com/react-native-webview/react-native-webview/blob/v13.6.2/docs/Reference.md#allowsBackForwardNavigationGestures)

## 设置示例

下面的示例同时设置了 WebView 的滚动行为和媒体播放方式。

```ts
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  webView: {
    bounces: true,
    pullToRefreshEnabled: true,
    allowsInlineMediaPlayback: false,
    overScrollMode: 'never',
  },
});
```

## 参考事项

* 部分 WebView 属性仅适用于 iOS 或 Android。请务必确认各平台的行为差异。
* 建议根据服务特性谨慎设置对用户体验影响较大的选项。
* WebView 属性在配置阶段应用，而不是运行时。


---

# 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/integration/props.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.