Expo Dom

作者 expocd752143d19eMIT2.6K 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫昨天更新

Framework (OSS). Use Expo DOM components to run web code in a webview on native and as-is on web. Migrate web code to native incrementally. For the end-to-end migration of a whole web app, use the expo-web-to-native skill.

僅含說明Software Development

AI 產生的概覽

說明如何使用 Expo DOM 元件，讓網頁程式碼在原生端以 WebView 執行、在網頁端原樣呈現。

功能: 這個技能介紹 Expo DOM 元件：在檔案頂端加上 'use dom' 指示後，網頁程式碼可在 iOS 與 Android 上透過 WebView 執行，在網頁上則原樣呈現。內容涵蓋 DOM 元件的規則、dom 屬性與其選項、以 props 傳入非同步原生函式、使用僅支援網頁的套件、CSS 處理、Expo Router 用法、環境偵測、資源引用以及各平台行為。它產出的是說明與程式碼範例，而不是檔案或指令碼。
適用情境: 適用於在 Expo 應用程式中引入僅支援網頁的套件（例如圖表或語法突顯套件）、將現有 React 網頁元件逐步遷移到原生端，或嵌入 HTML/CSS、iframe、Canvas、WebGL 內容。也適合在判斷是否該採用 WebView 做法而非原生元件時參考。
執行需求: 需要一個使用 React Native 與 expo/dom 模組的 Expo 專案；這個技能不附帶指令碼，只有說明與程式碼範例。文件中提到的選用意見回饋指令透過 npx 執行，需要網路存取。

What are DOM Components?

DOM components allow web code to run verbatim in a webview on native platforms while rendering as-is on web. This enables using web-only libraries like recharts, react-syntax-highlighter, or any React web library in your Expo app without modification.

When to Use DOM Components

Use DOM components when you need:

Web-only libraries — Charts (recharts, chart.js), syntax highlighters, rich text editors, or any library that depends on DOM APIs
Migrating web code — Bring existing React web components to native without rewriting
Complex HTML/CSS layouts — When CSS features aren't available in React Native
iframes or embeds — Embedding external content that requires a browser context
Canvas or WebGL — Web graphics APIs not available natively

When NOT to Use DOM Components

Avoid DOM components when:

Native performance is critical — Webviews add overhead
Simple UI — React Native components are more efficient for basic layouts
Deep native integration — Use local modules instead for native APIs
Layout routes — _layout files cannot be DOM components

Basic DOM Component

Create a new file with the 'use dom'; directive at the top:

tsx

// components/WebChart.tsx"use dom";
export default function WebChart({  data,}: {  data: number[];  dom: import("expo/dom").DOMProps;}) {  return (    <div style={{ padding: 20 }}>      <h2>Chart Data</h2>      <ul>        {data.map((value, i) => (          <li key={i}>{value}</li>        ))}      </ul>    </div>  );}

// components/WebChart.tsx"use dom";
export default function WebChart({  data,}: {  data: number[];  dom: import("expo/dom").DOMProps;}) {  return (    <div style={{ padding: 20 }}>      <h2>Chart Data</h2>      <ul>        {data.map((value, i) => (          <li key={i}>{value}</li>        ))}      </ul>    </div>  );}

Rules for DOM Components

Must have 'use dom'; directive at the top of the file
Single default export — One React component per file
Own file — Cannot be defined inline or combined with native components
Serializable props only — Strings, numbers, booleans, arrays, plain objects
Include CSS in the component file — DOM components run in isolated context

The `dom` Prop

Every DOM component receives a special dom prop for webview configuration. Always type it in your props:

tsx

"use dom";
interface Props {  content: string;  dom: import("expo/dom").DOMProps;}
export default function MyComponent({ content }: Props) {  return <div>{content}</div>;}

"use dom";
interface Props {  content: string;  dom: import("expo/dom").DOMProps;}
export default function MyComponent({ content }: Props) {  return <div>{content}</div>;}

Common `dom` Prop Options

tsx

// Disable body scrolling<DOMComponent dom={{ scrollEnabled: false }} />
// Flow under the notch (disable safe area insets)<DOMComponent dom={{ contentInsetAdjustmentBehavior: "never" }} />
// Control size manually<DOMComponent dom={{ style: { width: 300, height: 400 } }} />
// Combine options<DOMComponent  dom={{    scrollEnabled: false,    contentInsetAdjustmentBehavior: "never",    style: { width: '100%', height: 500 }  }}/>

// Disable body scrolling<DOMComponent dom={{ scrollEnabled: false }} />
// Flow under the notch (disable safe area insets)<DOMComponent dom={{ contentInsetAdjustmentBehavior: "never" }} />
// Control size manually<DOMComponent dom={{ style: { width: 300, height: 400 } }} />
// Combine options<DOMComponent  dom={{    scrollEnabled: false,    contentInsetAdjustmentBehavior: "never",    style: { width: '100%', height: 500 }  }}/>

Exposing Native Actions to the Webview

Pass async functions as props to expose native functionality to the DOM component:

tsx

// app/index.tsx (native)import { Alert } from "react-native";import DOMComponent from "@/components/dom-component";
export default function Screen() {  return (    <DOMComponent      showAlert={async (message: string) => {        Alert.alert("From Web", message);      }}      saveData={async (data: { name: string; value: number }) => {        // Save to native storage, database, etc.        console.log("Saving:", data);        return { success: true };      }}    />  );}

// app/index.tsx (native)import { Alert } from "react-native";import DOMComponent from "@/components/dom-component";
export default function Screen() {  return (    <DOMComponent      showAlert={async (message: string) => {        Alert.alert("From Web", message);      }}      saveData={async (data: { name: string; value: number }) => {        // Save to native storage, database, etc.        console.log("Saving:", data);        return { success: true };      }}    />  );}

tsx

// components/dom-component.tsx"use dom";
interface Props {  showAlert: (message: string) => Promise<void>;  saveData: (data: {    name: string;    value: number;  }) => Promise<{ success: boolean }>;  dom?: import("expo/dom").DOMProps;}
export default function DOMComponent({ showAlert, saveData }: Props) {  const handleClick = async () => {    await showAlert("Hello from the webview!");    const result = await saveData({ name: "test", value: 42 });    console.log("Save result:", result);  };
  return <button onClick={handleClick}>Trigger Native Action</button>;}

// components/dom-component.tsx"use dom";
interface Props {  showAlert: (message: string) => Promise<void>;  saveData: (data: {    name: string;    value: number;  }) => Promise<{ success: boolean }>;  dom?: import("expo/dom").DOMProps;}
export default function DOMComponent({ showAlert, saveData }: Props) {  const handleClick = async () => {    await showAlert("Hello from the webview!");    const result = await saveData({ name: "test", value: 42 });    console.log("Save result:", result);  };
  return <button onClick={handleClick}>Trigger Native Action</button>;}

Using Web Libraries

DOM components can use any web library:

tsx

// components/syntax-highlight.tsx"use dom";
import SyntaxHighlighter from "react-syntax-highlighter";import { docco } from "react-syntax-highlighter/dist/esm/styles/hljs";
interface Props {  code: string;  language: string;  dom?: import("expo/dom").DOMProps;}
export default function SyntaxHighlight({ code, language }: Props) {  return (    <SyntaxHighlighter language={language} style={docco}>      {code}    </SyntaxHighlighter>  );}

// components/syntax-highlight.tsx"use dom";
import SyntaxHighlighter from "react-syntax-highlighter";import { docco } from "react-syntax-highlighter/dist/esm/styles/hljs";
interface Props {  code: string;  language: string;  dom?: import("expo/dom").DOMProps;}
export default function SyntaxHighlight({ code, language }: Props) {  return (    <SyntaxHighlighter language={language} style={docco}>      {code}    </SyntaxHighlighter>  );}

tsx

// components/chart.tsx"use dom";
import {  LineChart,  Line,  XAxis,  YAxis,  CartesianGrid,  Tooltip,} from "recharts";
interface Props {  data: Array<{ name: string; value: number }>;  dom: import("expo/dom").DOMProps;}
export default function Chart({ data }: Props) {  return (    <LineChart width={400} height={300} data={data}>      <CartesianGrid strokeDasharray="3 3" />      <XAxis dataKey="name" />      <YAxis />      <Tooltip />      <Line type="monotone" dataKey="value" stroke="#8884d8" />    </LineChart>  );}

// components/chart.tsx"use dom";
import {  LineChart,  Line,  XAxis,  YAxis,  CartesianGrid,  Tooltip,} from "recharts";
interface Props {  data: Array<{ name: string; value: number }>;  dom: import("expo/dom").DOMProps;}
export default function Chart({ data }: Props) {  return (    <LineChart width={400} height={300} data={data}>      <CartesianGrid strokeDasharray="3 3" />      <XAxis dataKey="name" />      <YAxis />      <Tooltip />      <Line type="monotone" dataKey="value" stroke="#8884d8" />    </LineChart>  );}

CSS in DOM Components

CSS imports must be in the DOM component file since they run in isolated context:

tsx

// components/styled-component.tsx"use dom";
import "@/styles.css"; // CSS file in same directory
export default function StyledComponent({  dom,}: {  dom: import("expo/dom").DOMProps;}) {  return (    <div className="container">      <h1 className="title">Styled Content</h1>    </div>  );}

// components/styled-component.tsx"use dom";
import "@/styles.css"; // CSS file in same directory
export default function StyledComponent({  dom,}: {  dom: import("expo/dom").DOMProps;}) {  return (    <div className="container">      <h1 className="title">Styled Content</h1>    </div>  );}

Or use inline styles / CSS-in-JS:

tsx

"use dom";
const styles = {  container: {    padding: 20,    backgroundColor: "#f0f0f0",  },  title: {    fontSize: 24,    color: "#333",  },};
export default function StyledComponent({  dom,}: {  dom: import("expo/dom").DOMProps;}) {  return (    <div style={styles.container}>      <h1 style={styles.title}>Styled Content</h1>    </div>  );}

"use dom";
const styles = {  container: {    padding: 20,    backgroundColor: "#f0f0f0",  },  title: {    fontSize: 24,    color: "#333",  },};
export default function StyledComponent({  dom,}: {  dom: import("expo/dom").DOMProps;}) {  return (    <div style={styles.container}>      <h1 style={styles.title}>Styled Content</h1>    </div>  );}

Expo Router in DOM Components

The expo-router <Link /> component and router API work inside DOM components:

tsx

"use dom";
import { Link, useRouter } from "expo-router";
export default function Navigation({  dom,}: {  dom: import("expo/dom").DOMProps;}) {  const router = useRouter();
  return (    <nav>      <Link href="/about">About</Link>      <button onClick={() => router.push("/settings")}>Settings</button>    </nav>  );}

"use dom";
import { Link, useRouter } from "expo-router";
export default function Navigation({  dom,}: {  dom: import("expo/dom").DOMProps;}) {  const router = useRouter();
  return (    <nav>      <Link href="/about">About</Link>      <button onClick={() => router.push("/settings")}>Settings</button>    </nav>  );}

Router APIs That Require Props

These hooks don't work directly in DOM components because they need synchronous access to native routing state:

useLocalSearchParams()
useGlobalSearchParams()
usePathname()
useSegments()
useRootNavigation()
useRootNavigationState()

Solution: Read these values in the native parent and pass as props:

tsx

// app/[id].tsx (native)import { useLocalSearchParams, usePathname } from "expo-router";import DOMComponent from "@/components/dom-component";
export default function Screen() {  const { id } = useLocalSearchParams();  const pathname = usePathname();
  return <DOMComponent id={id as string} pathname={pathname} />;}

// app/[id].tsx (native)import { useLocalSearchParams, usePathname } from "expo-router";import DOMComponent from "@/components/dom-component";
export default function Screen() {  const { id } = useLocalSearchParams();  const pathname = usePathname();
  return <DOMComponent id={id as string} pathname={pathname} />;}

tsx

// components/dom-component.tsx"use dom";
interface Props {  id: string;  pathname: string;  dom?: import("expo/dom").DOMProps;}
export default function DOMComponent({ id, pathname }: Props) {  return (    <div>      <p>Current ID: {id}</p>      <p>Current Path: {pathname}</p>    </div>  );}

// components/dom-component.tsx"use dom";
interface Props {  id: string;  pathname: string;  dom?: import("expo/dom").DOMProps;}
export default function DOMComponent({ id, pathname }: Props) {  return (    <div>      <p>Current ID: {id}</p>      <p>Current Path: {pathname}</p>    </div>  );}

Detecting DOM Environment

Check if code is running in a DOM component:

tsx

"use dom";
import { IS_DOM } from "expo/dom";
export default function Component({  dom,}: {  dom?: import("expo/dom").DOMProps;}) {  return <div>{IS_DOM ? "Running in DOM component" : "Running natively"}</div>;}

"use dom";
import { IS_DOM } from "expo/dom";
export default function Component({  dom,}: {  dom?: import("expo/dom").DOMProps;}) {  return <div>{IS_DOM ? "Running in DOM component" : "Running natively"}</div>;}

Assets

Prefer requiring assets instead of using the public directory:

tsx

"use dom";
// Good - bundled with the componentconst logo = require("../assets/logo.png");
export default function Component({  dom,}: {  dom: import("expo/dom").DOMProps;}) {  return <img src={logo} alt="Logo" />;}

"use dom";
// Good - bundled with the componentconst logo = require("../assets/logo.png");
export default function Component({  dom,}: {  dom: import("expo/dom").DOMProps;}) {  return <img src={logo} alt="Logo" />;}

Usage from Native Components

Import and use DOM components like regular components:

tsx

// app/index.tsximport { View, Text } from "react-native";import WebChart from "@/components/web-chart";import CodeBlock from "@/components/code-block";
export default function HomeScreen() {  return (    <View style={{ flex: 1 }}>      <Text>Native content above</Text>
      <WebChart data={[10, 20, 30, 40, 50]} dom={{ style: { height: 300 } }} />
      <CodeBlock        code="const x = 1;"        language="javascript"        dom={{ scrollEnabled: true }}      />
      <Text>Native content below</Text>    </View>  );}

// app/index.tsximport { View, Text } from "react-native";import WebChart from "@/components/web-chart";import CodeBlock from "@/components/code-block";
export default function HomeScreen() {  return (    <View style={{ flex: 1 }}>      <Text>Native content above</Text>
      <WebChart data={[10, 20, 30, 40, 50]} dom={{ style: { height: 300 } }} />
      <CodeBlock        code="const x = 1;"        language="javascript"        dom={{ scrollEnabled: true }}      />
      <Text>Native content below</Text>    </View>  );}

Platform Behavior

On web, the dom prop is ignored since no webview is needed.

Tips

DOM components hot reload during development
Keep DOM components focused — don't put entire screens in webviews
Use native components for navigation chrome, DOM components for specialized content
Test on all platforms — web rendering may differ slightly from native webviews
Large DOM components may impact performance — profile if needed
The webview has its own JavaScript context — cannot directly share state with native

Submitting Feedback

If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:

bash

npx --yes submit-expo-feedback@latest --category skills --subject "expo-dom" "<actionable feedback>"

npx --yes submit-expo-feedback@latest --category skills --subject "expo-dom" "<actionable feedback>"

Only submit when you have something specific and actionable to report. Include as much relevant context as possible. If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

來源與署名

來源：expo/skills位於plugins/expo/skills/expo-dom提交cd75214

授權條款： MIT

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

Expo Dom

What are DOM Components?

When to Use DOM Components

When NOT to Use DOM Components

Basic DOM Component

Rules for DOM Components

The `dom` Prop

Common `dom` Prop Options

Exposing Native Actions to the Webview

Using Web Libraries

CSS in DOM Components

Expo Router in DOM Components

Router APIs That Require Props

Detecting DOM Environment

Assets

Usage from Native Components

Platform Behavior

Tips

Submitting Feedback

來源與署名

更多來自 expo/skills 的技能

Expo Migrate Module

Expo Upgrade

Expo Router

Expo Overview

Expo Module

Expo Dev Client

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Dpop Adoption

Gemini Live Api

Gemini Api

Platform	Behavior
iOS	Rendered in WKWebView
Android	Rendered in WebView
Web	Rendered as-is (no webview wrapper)

Expo Dom

What are DOM Components?

When to Use DOM Components

When NOT to Use DOM Components

Basic DOM Component

Rules for DOM Components

The dom Prop

Common dom Prop Options

Exposing Native Actions to the Webview

Using Web Libraries

CSS in DOM Components

Expo Router in DOM Components

Router APIs That Require Props

Detecting DOM Environment

Assets

Usage from Native Components

Platform Behavior

Tips

Submitting Feedback

來源與署名

更多來自 expo/skills 的技能

Expo Migrate Module

Expo Upgrade

Expo Router

Expo Overview

Expo Module

Expo Dev Client

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Dpop Adoption

Gemini Live Api

Gemini Api

The `dom` Prop

Common `dom` Prop Options