控制 WebView 的属性

本文档中，为了控制 WebView 的运行方式 apps-in-toss.config.ts可在其中设置的 webView 选项。

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

支持环境

• 运行环境：WebView、Toss app
• SDK 版本：WebView 3.x 以上

WebView 属性设置方法

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

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

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

SDK 2.x 中的 granite.config.ts和 webViewProps在 SDK 3.x 中分别 apps-in-toss.config.ts, webView更名为。子选项保持不变。

可用的 WebView 属性

webView中可以设置以下属性。

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 官方文档

限制媒体自动播放（mediaPlaybackRequiresUserAction)

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

将此值 true设为后，用户必须手动点击，媒体才会播放。在 Android 上，此选项仅适用于 17 及以上版本。

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

参考： react-native-webview mediaPlaybackRequiresUserAction

允许滑动返回/前进（allowsBackForwardNavigationGestures)

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

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

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

参考： react-native-webview allowsBackForwardNavigationGestures

设置示例

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

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 属性是在设置阶段应用的，而不是在运行时。