移动开发跨平台UI组件前端【免费下载链接】react-native-webviewReact Native Cross-Platform WebView项目地址https://gitcode.com/gh_mirrors/re/react-native-webview点击查看免费下载导读react-native-webview 是 React Native 社区维护的跨平台 WebView 组件用于在 iOS、Android、Windows 与 macOS 应用中嵌入网页内容同时兼容 React Native 新旧两套架构Paper 与 Fabric。本文以官方 README 为主线系统讲解其安装链接、基本用法、常用 API 与常见问题并结合仓库源码剖析 originWhitelist、消息桥接等核心机制的底层实现帮助开发者快速上手并写出稳定可靠的混合渲染页面。一、项目概览为什么需要它React Native WebView是一个由社区维护的 WebView 组件定位是替换 React Native 内置的 WebView该内置组件已从 React Native 核心中移除。由于 WebView 常被用于渲染 SVG、PDF、登录流程等大量不同场景且需要同时支持多个平台与两套 React Native 架构项目维护复杂度很高自 WebView 从核心仓库抽出以来社区已合并近 500 个 Pull Request。平台与架构兼容性兼容平台iOS、Android、Windows、macOS架构支持同时支持旧架构Paper与新架构Fabric生态兼容可与 Expo 配合使用Expo SDK 中提供了对应的 webview 封装。仓库中可看到架构层面的直接证据Android 端在android/src/newarch与android/src/oldarch两个目录下分别维护了RNCWebViewManager.java与RNCWebViewModule.java两套实现分别对应 Fabric 与 Paper 架构而package.json中通过codegenConfig声明了原生代码生成配置name 为RNCWebViewSpecAndroid 包名为com.reactnativecommunity.webview供新架构的 codegen 流程使用。版本策略项目遵循语义化版本semantic versioning。社区不回避破坏性变更但此类变更只会在主版本major version中发布依赖方可以据此制定升级策略。二、快速上手安装与原生依赖链接1. 添加依赖使用 yarn 或 npm 安装均可# yarn $ yarn add react-native-webview # 或 npm $ npm install --save react-native-webview2. 链接原生依赖包含 Objective-C、Swift、Java 或 Kotlin 原生代码的 React Native 模块必须经过链接编译器才能将其纳入应用。React Native 0.60 及以上版本autolinking 会自动处理链接步骤无需手动执行 link 命令旧版本或需要手动链接时$ react-native link react-native-webview如需卸载执行react-native unlink react-native-webview解除链接。3. 各平台补充步骤iOS 与 macOS若使用 CocoaPods在项目的ios/或macos/目录下执行$ pod install建议优先使用 CocoaPods 方式而非手动链接。Androidreact-native-webview 版本 6执行 link 命令后无需额外步骤版本 6.X.X需确保项目已启用 AndroidX在android/gradle.properties中添加两行配置android.useAndroidXtrue android.enableJetifiertrueWindowsReact Native Windows 0.63 手动链接React Native Windows v0.63 及以上支持 autolinking低版本需要手动修改以下文件windows/myapp.sln在 Visual Studio 2019 中右键 Solution Add Existing Project选择node_modules\react-native-webview\windows\ReactNativeWebView\ReactNativeWebView.vcxprojwindows/myapp/myapp.vcxproj右键主应用项目 Add Reference勾选 Solution Projects 中的ReactNativeWebViewpch.h添加#include winrt/ReactNativeWebView.happ.cpp在InitializeComponent();之前添加PackageProviders().Append(winrt::ReactNativeWebView::ReactPackageProvider());。提示若希望在 Windows 端启用 Touch 滚动需要为应用关闭 perspective参见 React Native Windows 文档中ReactRootView.IsPerspectiveEnabled的说明。仓库中windows/ReactNativeWebView/目录含ReactWebView.cpp、ReactWebView2.cpp、ReactPackageProvider.cpp等即为 Windows 平台的原生实现ReactWebView2.cpp对应 WebView2Chromium实现。Windows WebView2 支持v11.18.0 起WebView2 是基于 Microsoft EdgeChromium渲染引擎的 WinUI 控件。如果应用使用 RNW v0.68 及以上可按以下步骤启用让 autolinking 自动把ReactNativeWebView项目加入应用将应用的 WinUI 2.x 版本升级到2.8.0-prerelease.210927001或更高WebView2 的 WinUI 2.x 支持尚未进入 stable 版本需使用 prerelease必要时在应用的packages.config中显式指定Microsoft.Web.WebView2包出现构建错误时错误信息会给出所需版本。启用后即可通过useWebView2属性在 JavaScript 侧使用 WinUI WebView2 控件该属性支持运行时切换并兼容 Fast Refresh。三、在组件中使用 WebView加载远程 URLimport React, { Component } from react; import { WebView } from react-native-webview; class MyWeb extends Component { render() { return ( WebView source{{ uri: https://infinite.red }} style{{ marginTop: 20 }} / ); } }加载内联 HTML最小示例import React, { Component } from react; import { WebView } from react-native-webview; class MyInlineWeb extends Component { render() { return ( WebView originWhitelist{[*]} source{{ html: h1Hello world/h1 }} / ); } }关键点使用静态 HTML 时必须将originWhitelist设置为[*]否则 HTML 不会被加载详见下文 API 解析。source 属性详解source支持两种数据形状加载 URILoad uriuristring要加载的 URI可以是本地或远程文件可通过 React state/props 变更来导航到新页面methodstringHTTP 方法默认 GET。Android 与 Windows 仅支持 GET 与 POSTheadersobject附加 HTTP 请求头。Android 上仅可用于 GET 请求bodystringHTTP 请求体必须是合法 UTF-8 字符串原样发送不做 URL 转义或 base64 编码。Android 与 Windows 上仅可用于 POST 请求。静态 HTMLStatic HTMLhtmlstring要在 WebView 中显示的静态 HTML 页面baseUrlstringHTML 中相对链接的基础 URL也用于 CORS 请求的 origin 头。对于视频嵌入如 Twitter/Facebook 含视频的帖子需要设置 baseUrl 才能正常播放视频。注意传入新的静态 HTML source 会触发 WebView 重新渲染。四、常用 Props 与 Methods 实战originWhitelistURL 导航白名单用于限制允许导航到的 origin 列表。字符串支持通配符且只匹配 origin而非完整 URL。如果用户点击导航到不在白名单中的新页面该 URL 会交给系统OS处理。默认白名单为[http://*, https://*]。// 仅允许以 https:// 或 git:// 开头的 URI WebView source{{ uri: https://reactnative.dev }} originWhitelist{[https://*, git://*]} /底层实现位于 src/WebViewShared.tsx默认白名单defaultOriginWhitelist [http://*, https://*]会被编译为以^开头的正则originWhitelistToRegex将*替换为.*并额外注入about:blank当 URL 未通过白名单校验时会尝试调用Linking.openURL交给系统打开并阻止 WebView 继续加载反之再交由onShouldStartLoadWithRequest回调决定是否放行返回true继续加载false停止加载。注意 Android 上onShouldStartLoadWithRequest在首次加载时不会被调用。injectedJavaScript页面加载完成后注入脚本在文档加载完成之后、其他子资源加载完成之前向页面注入 JavaScript。字符串必须能求值为合法类型true即可且不能抛出异常。const INJECTED_JAVASCRIPT (function() { window.ReactNativeWebView.postMessage(JSON.stringify(window.location)); })();; WebView source{{ uri: https://reactnative.dev }} injectedJavaScript{INJECTED_JAVASCRIPT} onMessage{this.onMessage} /;配套属性还包括injectedJavaScriptBeforeContentLoaded在 document 元素创建后、其他子资源加载前注入。注意 Android 上该功能并不 100% 可靠见 issue #1609 与 PR #1099文档建议改用injectedJavaScriptObjectinjectedJavaScriptForMainFrameOnly默认trueAndroid 强制仅注入主 frame设为false时仅 iOS/macOS 支持注入所有 frame如 iframeinjectedJavaScriptObject向 WebView 注入任意 JS 对象页面中可通过window.ReactNativeWebView.injectedObjectJson()读取。注意对象中的任何值对网页所有 frame可见含敏感数据时应配置严格的 CSP 防止泄露。onMessage 与消息桥接onMessage在 WebView 内调用window.ReactNativeWebView.postMessage时被触发。设置该属性会在 WebView 中注入全局对象postMessage接收一个参数data必须是字符串通过event.nativeEvent.data获取。消息桥接的原生侧实现可追溯到 Android 源码在 android/src/main/java/com/reactnativecommunity/webview/RNCWebView.java 中定义了RNCWebViewBridge内部类其postMessage方法标注了JavascriptInterface注释明确说明当 WebView 内的 JavaScript 调用window[JAVASCRIPT_INTERFACE].postMessage时调用此方法若未设置onMessage处理器messaging 被禁用会输出警告日志 ReactNativeWebView.postMessage method was called but messaging is disabled. Pass an onMessage handler to the WebView.。同时 RNCWebViewManagerImpl.kt 中将postMessage注册为原生命令command供 JS 侧postMessage(str)方法反向向页面发送消息。温馨提示Windows 端 WebView 原生不支持 alert任何展示 alert 的脚本都不会生效。加载生命周期事件事件触发时机说明onLoadStart开始加载nativeEvent 含url、title、loading、canGoBack、canGoForward等onLoad加载完成同上onLoadEnd加载成功或失败可用于更新 isLoading 状态onLoadProgress加载过程中额外包含progress0~1iOS/Android/macOSonError加载失败nativeEvent 含code、description、didFailProvisionalNavigation等iOS 另有domain可调用preventDefault()onHttpError收到 HTTP 错误含statusCode、description仅 AndroidAndroid API 最低 23onRenderProcessGoneAndroid 渲染进程崩溃/被系统杀死含didCrashAndroid API 最低 26onContentProcessDidTerminateiOS/macOS WKWebView 内容进程终止进程被终止不一定是崩溃例如后台长时间后为释放内存被系统回收常配合reload()自动恢复onNavigationStateChange加载开始或结束navState含canGoBack、canGoForward、loading、title、urliOS 另有navigationTypeonOpenWindow应打开新窗口时触发于 JS 调用window.open(url, _blank)或点击target_blank链接nativeEvent 含targetUrlonScroll滚动事件nativeEvent 含contentOffset、contentSize、velocity等这些事件在 JS 侧由useWebViewLogic统一调度见 src/WebViewShared.tsx加载开始/结束、进度、错误、HTTP 错误、进程终止等回调被串联起来并维护viewStateIDLE/LOADING/ERROR驱动默认的加载与错误视图Android 上还做了特殊处理——只有加载结束的 URL 与起始 URL 一致时才会切回IDLE状态。Android 端对应的事件实现可见android/src/main/java/com/reactnativecommunity/webview/events/目录下的一系列TopXxxEvent.kt文件。渲染控制与样式startInLoadingState首次加载时强制显示加载视图必须为true才能使用renderLoadingrenderLoading自定义加载指示器默认实现为居中ActivityIndicator见defaultRenderLoadingrenderError出错时返回自定义视图回调参数为错误名称默认实现展示 Domain、Error Code、Description见defaultRenderErrorstyle/containerStyle自定义 WebView 及其容器样式。注意存在默认样式例如要使用height属性需显式加flex: 0。WebView source{{ uri: https://reactnative.dev }} startInLoadingState{true} renderLoading{() Loading /} renderError{(errorName) Error name{errorName} /} /平台差异化配置Android 常用配置javaScriptEnabled默认true控制是否启用 JavaScriptdomStorageEnabled控制 DOM Storage 是否启用仅 AndroidmixedContentMode混合内容模式。never默认禁止安全 origin 加载不安全内容/always允许任意混合/compatibility按现代浏览器方式兼容处理thirdPartyCookiesEnabled默认true控制第三方 CookieAndroid Lollipop 及以上Kitkat 及以下与 iOS 默认开启cacheMode缓存模式。LOAD_DEFAULT默认/LOAD_CACHE_ELSE_NETWORK/LOAD_NO_CACHE/LOAD_CACHE_ONLYtextZoom默认 100解决 Android 系统自定义字体导致页面缩放异常的问题WebView textZoom{100} /scalesPageToFit默认true控制网页内容是否缩放适配视图overScrollModealways默认/content/neversetSupportMultipleWindows默认true关闭后可能暴露 UXSS 漏洞CVE-2020-6506需谨慎minimumFontSizeAndroid 强制的最小字号范围 1~72默认 8allowsProtectedMedia是否允许播放受 DRM 保护的媒体默认false关闭不会撤销已授予当前页面的权限需 reload下载提示文案downloadingMessage默认 Downloading与lackPermissionToDownloadMessage。iOS/macOS 常用配置allowsInlineMediaPlaybackHTML5 视频是否内联播放默认false需配合 HTML 中webkit-playsinline属性allowsPictureInPictureMediaPlayback是否允许画中画默认falseallowsAirPlayForMediaPlayback是否允许 AirPlay默认falsecontentModeiOS 13recommended默认/mobile/desktopdataDetectorTypes自动识别并转为可点击链接的内容类型phoneNumber默认/link/address/calendarEvent/trackingNumber/flightNumber/lookupSuggestion/none/alllimitsNavigationsToAppBoundDomainsiOS 14 限制只导航到 App-Bound Domains最多 10 个通过 Info.plist 的WKAppBoundDomains配置enableApplePay启用后网站可从 WebView 内调用 Apple Pay但会牺牲injectedJavaScript、sharedCookiesEnabled等能力且需页面显式调用window.webkit.messageHandlers.ReactNativeWebView.postMessage(...)才能向 App 发消息pullToRefreshEnabled下拉刷新默认false开启会自动把bounces设为truewebviewDebuggingEnabled是否允许 Safari/Chrome 远程调试默认falseiOS 16.4 生效更早版本默认允许。跨平台通用cacheEnabled是否使用浏览器缓存默认trueincognitoWebView 生命周期内不存储任何数据userAgent/applicationNameForUserAgent自定义 UA 或在现有 UA 后追加字符串userAgent会覆盖applicationNameForUserAgentbasicAuthCredential基本认证凭据对象{ username, password }forceDarkOnAndroid 强制深色主题不持久每次进程启动需重新调用menuItems与onCustomMenuSelection自定义文本选择菜单回调携带label、key、selectedText仓库中 Android 事件实现见 TopCustomMenuSelectionEvent.kt。实例方法方法说明goForward()历史记录中前进一页goBack()历史记录中后退一页reload()重新加载当前页面stopLoading()停止加载当前页面injectJavaScript(str)执行一段 JS 字符串postMessage(str)向 WebView 发送消息由onMessage接收requestFocus()请求 WebView 获得焦点TV 应用常用clearFormData()Android only清除当前聚焦表单字段的自动填充弹窗clearCache(bool)清除资源缓存。缓存是应用级的会清空所有 WebView 的缓存iOS 上true会同时移除 web storage 与数据库数据Windows 因 WebView2 与 Edge 共享缓存只能清 CookieclearHistory()Android only清除 WebView 内部前进/后退列表五、项目源码结构导览理解源码结构有助于定位问题、贡献代码或自行定制跨平台 JS 入口src/index.ts 导出WebView组件src/WebView.tsx 定义了WebViewPropsiOS、Android、Windows 属性联合并在不支持的平台如 Expo web渲染提示占位视图平台分文件src/下按平台拆分为WebView.android.tsx、WebView.ios.tsx、WebView.macos.tsx、WebView.windows.tsx类型定义集中在WebViewTypes.ts共享逻辑src/WebViewShared.tsx 承载白名单校验、加载/错误状态机与全部事件回调解耦是各平台组件复用的核心原生实现Android 主实现在android/src/main/java/com/reactnativecommunity/webview/RNCWebView.java、RNCWebViewManagerImpl.kt、RNCWebViewClient.java、RNCWebChromeClient.java等并按newarch/oldarch拆分了 Fabric 与 Paper 两套 Manager/ModuleiOS/macOS 实现在apple/目录RNCWebView.mm、RNCWebViewImpl.m、RNCWebViewManager.mm等Windows 实现在windows/ReactNativeWebView/示例应用example/目录内置完整示例Alerts、CustomMenu、Downloads、Messaging、OpenWindow、Uploads 等并在example/android、example/ios、example/macos、example/windows下提供了各平台的工程配置可直接运行验证example/examples/中的每个场景均有对应演示页面。六、常见问题排查1. Invariant Violation: Native component for RNCWebView does not exist出现该错误通常意味着你忘记运行react-native link或者链接过程中出现了错误。处理方式确认已执行链接/autolinking 步骤RN 0.60 检查自动链接是否成功重新构建原生工程iOS 重新pod install并构建Android 重新 sync gradle 并构建。2. 构建报错:app:mergeDexRelease构建 Android 时在:app:mergeDexRelease任务报错通常需要启用 multidex。在android/app/build.gradle中配置android { defaultConfig { multiDexEnabled true } }七、延伸阅读完整 API 参考全部 Props 与 Methodsdocs/Reference.md使用场景深入指南文件上传/下载、JS 与原生通信、Cookie 管理、自定义请求头、页面导航手势等docs/Guide.md各平台手动链接细节docs/Getting-Started.md参与贡献docs/Contributing.md多语言版本README.portuguese.md、README.french.md、README.italian.md本项目基于MIT 许可证开源可放心用于商业与非商业项目。赞分享移动开发跨平台UI组件前端【免费下载链接】react-native-webviewReact Native Cross-Platform WebView项目地址https://gitcode.com/gh_mirrors/re/react-native-webview点击查看免费下载相关推荐react-native-webview 跨平台 WebView 组件实战指南安装、接入与常见问题排查react native webview 跨平台 WebView 组件实战指南安装、接入与常见问题排查 本指南以仓库内 docs/README.italian移动开发跨平台UI组件前端React Native Maps终极指南10个实用技巧实现流畅地图动画与精准定位React Native Maps终极指南10个实用技巧实现流畅地图动画与精准定位 React Native Maps是React Native生态中最强大的移动开发UI组件前端React Native WebView 跨平台 WebView 组件指南安装使用、版本演进与问题排查React Native WebView 跨平台 WebView 组件指南安装使用、版本演进与问题排查 本文档基于当前仓库的 docs/README.port移动开发跨平台UI组件前端上一篇RuboCop v0.84.0 版本解析OpenSSL 常量检查、属性访问器空行配置与默认行长度调整下一篇BuildKit 安全校验指南SecretsUsedInArgOrEnv 规则与 Dockerfile 构建密钥Build Secrets最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
