> 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 app
* 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`会被设为。

| 项目  | 内容        |
| --- | --------- |
| 类型  | `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.