SuperAPI AI 工具集

expo-dom

编程与开发

查看项目

更新于 10-27 13:02

技能介绍

用途

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、保存数据到原生存储)。
  • 提供 dom prop 用于配置 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 包装)。