use-dom

use-dom 技能概览

use-dom 技能能帮你解决什么问题

use-dom skill 讲的是如何使用 Expo DOM components，让 React web 代码既能在 Web 端正常渲染，也能在原生 Expo app 中通过 webview 运行。它真正要解决的，并不是孤立地“学会一个功能”，而是帮你判断：一个以 Web 为先的组件、库或布局，是否可以在不完整重写成 React Native 的前提下，实际交付到你的应用里。

哪些人适合使用 use-dom 技能

这个 use-dom skill 最适合以下前端开发者：

• 已经有现成的 React web 组件，希望在 Expo 中复用
• 需要依赖浏览器环境的库，比如图表、编辑器、语法高亮、嵌入内容或基于 iframe 的 UI
• 正在把 Web 应用渐进式迁移到原生端
• 需要 React Native 本身不直接提供的 DOM 和 CSS 能力

如果你的 UI 很简单，而且对性能非常敏感，那它通常不是最佳选择。

use-dom 和普通 Expo 提示词有什么不同

普通提示词通常会给出“直接用 WebView”或“改写成 React Native”这类泛化建议。use-dom guide 更聚焦：它围绕 Expo DOM component 模型、'use dom'; 文件指令，以及安装前最该先判断的适配边界来展开，尤其包括性能取舍、不支持的路由放置方式，以及哪些 Web 代码可以原样复用。

用户在评估 use-dom 时最先关心什么

多数人在评估 use-dom 时，首先想确认这四件事：

1. 我现有的 Web 组件能不能基本不改就继续用？
2. 如果目标库依赖 DOM，它还能不能正常工作？
3. 在原生端会带来哪些性能和 UX 取舍？
4. 到什么情况下，我应该停下来，改做原生组件？

当这些问题正好卡住你的决策时，这个技能最有价值；如果你需要的是更深入的原生集成，它就没那么合适。

use-dom 适合与不适合的场景

适合 use-dom for Frontend Development 的典型场景包括：

• recharts、chart.js、富文本编辑器、语法高亮工具
• 依赖大量 HTML/CSS 的组件
• 基于 iframe 的嵌入内容
• 预期浏览器 API 的 canvas 或 WebGL 代码

不适合的场景包括：

• React Native 本来就能直接渲染的基础应用 UI
• 对原生性能要求很高的页面
• 需要深度调用平台 API 的组件
• _layout 路由文件，这类文件不应该做成 DOM components

如何使用 use-dom 技能

安装 use-dom 技能

从 Expo skills 仓库安装：

npx skills add https://github.com/expo/skills --skill use-dom

这样你的 agent 或工作流就能拿到可复用的 use-dom install 与实现参考，而不是只依赖一次性的 prompt。

先读这个文件

先从这里开始：

• SKILL.md

对这个技能来说，几乎所有真正有价值的指导都集中在这里。你不需要在一大堆辅助文件里来回翻找，才能决定要不要采用它。

先理解核心机制

use-dom usage 的模型其实很简单，但很关键：新建一个组件文件，并在文件顶部加上 'use dom'; 指令。这样就会把该组件标记为基于 DOM 的组件。到了 Web 端，它照常渲染；到了原生端，它会运行在 webview 上下文中。

这也意味着，真正需要判断的重点不是语法，而是：你的组件是否真的足够依赖浏览器 API，以至于值得引入这层 webview 边界。

使用 use-dom 技能前，你需要提供哪些输入

想让 use-dom skill 给出有用结果，最好提供这些信息：

• 你打算使用的组件或库
• 它现在是否已经能在 React web 中工作
• 它是否依赖 DOM APIs、canvas、iframes 或高级 CSS
• 它会放在 Expo app 的哪个位置
• 性能是不是硬性要求
• 你是否需要 native modules 或更深层的设备集成

没有这些上下文，给出的建议通常会过于泛泛，不足以作为可靠决策依据。

把模糊目标变成高质量 prompt

弱 prompt：

• “Help me use use-dom.”

强 prompt：

• “I have an Expo app and want to reuse a React web chart component built with recharts. It already works on web, uses responsive container sizing, and only needs passed-in data and click callbacks. Show me how to convert it into a DOM component with 'use dom';, explain prop shape expectations, and call out native performance tradeoffs.”

为什么这种写法更有效：

• 明确写出了实际使用的库
• 确认了它在 Web 端已可用
• 说明了数据流方式
• 交代了交互需求
• 要求的不只是代码，还包括取舍分析

use-dom 的基础实现模式

一个典型的 use-dom guide 流程通常是这样的：

1. 先找出一个已经能在 React web 中正常工作的 Web 组件。
2. 创建组件文件，并加上 'use dom';。
3. 把依赖 DOM 的渲染逻辑限制在这个组件内部。
4. 从 Expo 侧传入可序列化、定义清晰的 props。
5. 同时在 Web 和原生端测试行为，尤其关注尺寸表现和交互。

源码示例里，这个 DOM component 会接收普通 props，以及 dom: import("expo/dom").DOMProps。在设计组件接口时，这是个很有参考价值的信号。

先从一个小组件开始，不要一上来包整屏

如果先迁一个边界清晰的小部件，采用 use-dom 往往会顺利得多，比如：

• 一个图表
• 一个代码查看器
• 一块富文本内容
• 一个嵌入模块

不要一开始就去包大范围的应用结构或导航。仓库里明确提到了 layout route 的限制，所以从一个小型叶子组件切入，通常是更稳妥的首个成功案例。

尽早判断你是否能接受 webview 开销

这是安装决策里最关键的因素。use-dom 的吸引力在于它能避免重写，但代价是原生端需要承担 webview 的开销。如果这个组件位于性能关键路径、要渲染大量内容，或者必须表现出非常原生的体验，那在决定采用前一定要先测。

如果只是简单 UI，长期来看通常还是 React Native 更合适。

更高效的仓库阅读顺序

对于这个技能，建议按这个顺序阅读：

1. SKILL.md 中的 “What are DOM Components?”
2. SKILL.md 中的 “When to Use DOM Components”
3. SKILL.md 中的 “When NOT to Use DOM Components”
4. SKILL.md 中 “Basic DOM Component” 下的示例

按这个顺序看，可以用最小成本先掌握适配场景、限制条件和实现轮廓。

用于 use-dom 的实用 prompt 模板

当你让 agent 应用这个技能时，可以直接用下面这种 prompt：

Use the use-dom skill to evaluate whether this React web component should become an Expo DOM component.

Component purpose:
- [what it does]

Current library dependencies:
- [libraries]

Why React Native alone is not enough:
- [DOM APIs / CSS / iframe / canvas / WebGL]

Performance sensitivity:
- [low / medium / high]

Route placement:
- [where the component will be used]

What I need from you:
- fit assessment
- implementation outline
- example component file with 'use dom';
- risks and when not to use use-dom

相比抽象地说一句“帮我做迁移”，这种结构化写法通常能得到更高质量的输出。

编码前先检查这些常见阻碍

在真正实现之前，先确认以下几点：

• 目标库是否真的需要 DOM / 浏览器环境
• 这个组件是否不会用于 _layout 路由
• 你是否不需要在 DOM 渲染部分里深度调用原生 API
• 你的团队是否接受原生端和 Web 端行为存在差异
• 这个组件是否真的值得复用，而不是直接重写更划算

这些检查能节省很多时间，因为它们正对应了这个技能里最常见的不匹配场景。

use-dom 技能 FAQ

use-dom 比普通 prompt 更好吗？

大多数情况下是的，前提是你的问题确实是：“这个 Web 组件能不能不重写，直接跑在 Expo 里？” 普通 prompt 往往会给出多个彼此无关的方案。use-dom skill 会把判断范围收窄到 Expo DOM components，并给出明确的适配边界，减少反复试错。

use-dom 只适合做迁移吗？

不是。迁移确实是它的重要使用场景，但并不是唯一场景。use-dom 同样适合全新的 Expo 应用，尤其是在你需要浏览器专属库、基于 iframe 的内容、高级 CSS 行为、canvas 或 WebGL，而 React Native 又无法直接提供这些能力时。

什么情况下应该避免使用 use-dom 技能？

以下情况建议跳过 use-dom：

• 你的 UI 用 React Native 就足够实现
• 你对性能非常敏感
• 你需要很强的原生体验和深度集成
• 该组件属于 _layout
• 已经有原生或跨平台库能干净利落地解决问题

use-dom 对新手友好吗？

算是中等友好。概念本身不复杂，但决策质量很依赖你是否理解 Web 与原生之间的取舍。新手也能用好它，前提是先从一个独立小组件开始，并尽早在真机上测试。

use-dom 能替代 React Native 组件吗？

不能。它是一个定向的 escape hatch，不应当成为默认 UI 策略。use-dom for Frontend Development 的最佳用法，是有选择地复用依赖浏览器环境的代码，而不是把整个 app 都搬进 DOM components 里重建。

哪些类型的库最适合 use-dom？

最适合的是那些默认假设自己运行在浏览器环境中的库，例如：

• 图表库
• 语法高亮库
• 富文本编辑器
• 基于 iframe / embed 的小部件
• 重度依赖 DOM 的可视化工具

如果这个库已经有成熟的 React Native 替代方案，优先先比较那个方案。

如何进一步提升 use-dom 技能的使用效果

给 agent 一个组件级的明确目标

想提升 use-dom 的输出质量，最快的方法是定义一个具体组件，而不是抛出一个模糊的迁移目标。把文件名、库、props 和所在页面都说清楚。这样 agent 才能判断这层 DOM 边界是否合理。

明确写出浏览器依赖点

不要只说“这是一个 Web 组件”，要说清楚它为什么只能是 Web：

• window 或 document
• canvas 渲染
• iframe 嵌入
• CSS 布局要求
• 默认假设存在 DOM 的第三方包

这会直接提升适配判断的准确性，因为这个技能本来就是围绕这些约束来工作的。

一开始就说明性能预期

很多效果不佳的 use-dom guide 结果，问题都出在太晚才发现组件位于关键交互路径。请提前说明这个组件是否：

• 首屏可见
• 会频繁 rerender
• 有大量滚动场景
• 交互密集
• 可以接受放在 webview 中运行

这些信息会实质性影响最终建议。

不要只要代码，要明确要求给出 go / no-go 判断

更好的提问方式是：

• “Should I use use-dom here, and why?”

而不是只说：

• “Write the component.”

这样更能发挥这个技能的价值，因为它最核心的能力之一，就是帮你划清边界：什么时候该用 DOM components，什么时候不该用。

让 agent 一并审视 prop 设计

源码模式暗示了一点：传给 DOM component 的 props 应该尽量设计清晰。可以让 agent 一起审查：

• 哪些 props 适合跨边界传递
• 数据是否应该先简化
• callbacks 是否足够少且确有必要
• 哪些值可能带来不必要的复杂度

很多时候，清晰的输入比“聪明”的实现更重要。

根据第一版结果继续迭代

拿到第一版结果后，用更有针对性的追问去收敛：

• “Reduce this to the minimum DOM-dependent surface.”
• “What part should remain native?”
• “What would make this too slow on native?”
• “Can you rewrite this example so the DOM component only handles the chart body?”

相比一上来就要一大段代码，这类追问通常更能提升实际采用质量。

留意这些常见失败模式

常见的 use-dom usage 误区包括：

• 把它用在本该保持原生实现的基础 UI 上
• 试图把 DOM components 放进不支持的 layout routes
• 低估 webview 开销
• 把整块页面中过多内容搬进 DOM 层
• 因为 Web 版本已经能跑，就跳过真机测试

如果你已经出现这些迹象，先收缩范围，再继续推进。

先测对的东西，才能更快建立信心

第一次测试，不要只看视觉是否一致。更应该检查：

• 原生端渲染是否正确
• 尺寸和容器行为是否稳定
• 输入与交互是否正常
• 数据更新是否可靠
• 在目标设备上的体感性能如何

这是验证 use-dom install 是否值得继续保留在技术栈里的最快方式。