用途
Expo DOM 组件用于让 Web 代码在原生平台上通过 WebView 原样运行,而在 Web 平台上则直接渲染。它主要解决两类问题:一是在 Expo 应用中使用仅支持 Web 的库,例如 recharts、chart.js、react-syntax-highlighter 或任何依赖 DOM API 的 React Web 库;二是将已有的 React Web 组件逐步迁移到原生端,无需重写。
主要能力
- 在原生端以 WebView 运行 Web 代码,在 Web 端直接渲染。
- 支持使用任意 Web 库,包括图表库、语法高亮器、富文本编辑器、iframe/嵌入内容、Canvas 或 WebGL 等。
- 支持在 DOM 组件内使用 expo-router 的
<Link />组件和 router API。 - 可通过传入异步函数作为 props,向 WebView 暴露原生功能(如弹出原生 Alert、保存数据到原生存储)。
- 提供
domprop 用于配置 WebView,例如禁用滚动、禁用安全区域内边距、手动控制尺寸等。 - 提供
IS_DOM常量用于检测代码是否运行在 DOM 组件中。 - 开发过程中 DOM 组件支持热重载。
使用方式
创建 DOM 组件时,需要在文件顶部添加 'use dom'; 指令,并且每个文件只能有一个默认导出的 React 组件。组件不能内联定义,也不能与原生组件混合在同一个文件中。props 必须是可序列化的类型,如字符串、数字、布尔值、数组和普通对象。CSS 需要写在 DOM 组件文件内,因为 DOM 组件运行在隔离的上下文中。
每个 DOM 组件都会收到一个特殊的 dom prop,用于 WebView 配置,需要在 props 类型中声明。常见配置包括:scrollEnabled: false 禁用 body 滚动,contentInsetAdjustmentBehavior: "never" 让内容延伸到刘海下方,以及通过 style 手动控制尺寸。
在原生端使用 DOM 组件时,像普通组件一样导入即可。在 Web 平台上,dom prop 会被忽略,因为不需要 WebView。
适用场景
- 需要使用仅支持 Web 的库,如 recharts、chart.js、react-syntax-highlighter。
- 将现有 React Web 组件迁移到原生端而不重写。
- 需要复杂 HTML/CSS 布局,而 React Native 不支持相应 CSS 特性。
- 需要嵌入 iframe 或依赖浏览器上下文的外部内容。
- 需要使用 Canvas 或 WebGL 等原生不可用的 Web 图形 API。
限制
- 原生性能关键场景不宜使用,WebView 会带来额外开销。
- 简单 UI 建议使用 React Native 组件,效率更高。
- 需要深度原生集成时,应使用本地模块而非 DOM 组件。
_layout布局路由文件不能作为 DOM 组件。- 部分 expo-router hooks(如
useLocalSearchParams、useGlobalSearchParams、usePathname、useSegments、useRootNavigation、useRootNavigationState)不能直接在 DOM 组件中使用,需要在原生父组件中读取后作为 props 传入。 - WebView 拥有独立的 JavaScript 上下文,无法与原生端直接共享状态。
- 大型 DOM 组件可能影响性能,必要时需进行性能分析。
- 建议在 Web 和原生各平台分别测试,Web 渲染结果可能与原生 WebView 略有差异。
- 资源建议使用
require引入而非 public 目录。
平台行为
iOS 上渲染在 WKWebView 中,Android 上渲染在 WebView 中,Web 上直接渲染(无 WebView 包装)。