JSX

Oxc 转换器支持转换 JSX。

🌐 Oxc transformer supports transforming JSX.

一般使用

🌐 General Usage

import { transform } from "oxc-transform";

const result = await transform("App.jsx", sourceCode, {
  jsx: {
    runtime: "automatic", // or "classic"
    development: false, // or true
    throwIfNamespace: true, // or false
    pure: true, // or false
    importSource: "react",
    pragma: "React.createElement",
    pragmaFrag: "React.Fragment",
    refresh: false, // see below
  },
  // When transforming TSX files:
  typescript: {
    jsxPragma: "React.createElement", // same value with `jsx.pragma`
    jsxPragmaFrag: "React.Fragment", // same value with `jsx.pragmaFrag`
  },
});

你也可以设置 jsx: 'preserve' 来禁用 JSX 转换。

🌐 You can also set jsx: 'preserve' to disable JSX transformation.

Oxc 转换器也支持 JSX pragma 注释，这同样得到了 Babel 和 esbuild 的支持。Pragma 注释对于按文件配置 JSX 选项非常有用。

🌐 Oxc transformer also supports JSX pragma comments, which is also supported by Babel and esbuild. Pragma comments are useful for configuring JSX options on a per-file basis.

运行时

🌐 Runtime

默认情况下，使用自动运行时转换。该转换是在 React 17+ 中引入的。这种转换会自动注入所需的 import 语句。

🌐 By default, the automatic runtime transform is used. This transform was introduced in React 17+. This transform injects the required import statements automatically.

你也可以通过将 jsx.runtime 选项设置为 "classic" 来使用经典运行时转换。

🌐 You can also use the classic runtime transform by setting jsx.runtime option to "classic".

// @jsxRuntime classic / // @jsxRuntime automatic 是通过 pragma 注释配置此项的方式。

两个运行时的常用选项

🌐 Common Options for Both Runtimes

开发转型

🌐 Development Transform

默认情况下，特定于开发的转换是禁用的。你可以通过将 jsx.development 选项设置为 true 来启用它们。

🌐 By default, the development specific transforms are disabled. You can enable them by setting jsx.development option to true.

XML 命名空间标签名

🌐 XML Namespaced Tag Names

默认情况下，如果使用了带命名空间的 XML 标签名（例如 <foo:bar baz:qux="foobar" />），会抛出错误。虽然 JSX 规范允许这样做，但默认情况下不允许，因为 React 的 JSX 目前不支持它们。你可以通过将 jsx.throwIfNamespace 选项设置为 false 来允许它们。

🌐 By default, an error is thrown if the XML namespaced tag names (e.g. <foo:bar baz:qux="foobar" />) are used. Though the JSX spec allows this, it is disallowed by default since React's JSX does not currently support them. You can allow them by setting jsx.throwIfNamespace option to false.

纯注释

🌐 Pure Annotation

默认情况下，JSX 元素会带有纯注解。纯注解是标注表达式的注释，如果其返回值未被使用，这些表达式可以安全地被移除。但如果希望保留 JSX 元素，则可能不希望这样。你可以通过将 jsx.pure 选项设置为 false 来禁用此功能。

🌐 By default, JSX elements are annotated with pure annotations. Pure annotations are annotation comments that marks expressions that can be safely removed if their return values are not used. But this may not be desired if the JSX elements should be kept. You can disable this by setting jsx.pure option to false.

自动运行时特定选项

🌐 Automatic Runtime Specific Options

导入来源

🌐 Import Source

此选项指定 JSX 辅助函数的导入来源。默认值为 "react"。

🌐 This option specifies the import source for the JSX helper functions. The default value is "react".

例如，如果你想使用 preact 包而不是 react，你可以将 jsx.importSource 设置为 "preact"，然后可能会注入以下导入语句：

🌐 For example, if you want to use the preact package instead of react, you can set jsx.importSource to "preact", then the following import statements may be injected:

import { createElement } from "preact";
import { Fragment, jsxDEV } from "preact/jsx-dev-runtime";
import { Fragment, jsx, jsxs } from "preact/jsx-runtime";

// @jsxImportSource preact 是通过 pragma 注释配置此项的方法。

经典运行时特定选项

🌐 Classic Runtime Specific Options

指令

🌐 Pragma

此选项指定在转换 JSX 表达式时使用的函数名称。它应为限定名称（例如 React.createElement）或标识符（例如 createElement）。在 esbuild 中，此选项称为 jsxFactory。

🌐 This option specifies the function name to use when transforming JSX expressions. It should be a qualified name (e.g. React.createElement) or an identifier (e.g. createElement). This option is called jsxFactory in esbuild.

// @jsx createElement 是通过 pragma 注释配置此项的方法。

Pragma片段

🌐 Pragma Fragment

此选项指定在转换 JSX 片段时使用的函数名称。它应该是一个有效的 JSX 标签名称。此选项在 esbuild 中称为 jsxFragment。

🌐 This option specifies the function name to use when transforming JSX fragments. It should be a valid JSX tag name. This option is called jsxFragment in esbuild.

// @jsxFrag Fragment 是通过 pragma 注释配置此项的方法。

React 刷新

🌐 React Refresh

React Refresh（也称为 React 快速刷新）在开发过程中为 React 组件提供热重载功能。

🌐 React Refresh (also known as React Fast Refresh) provides hot reloading capabilities for React components during development.

用法

🌐 Usage

要启用 React Refresh 转换，请设置 jsx.refresh 选项：

🌐 To enable React Refresh transformation, set jsx.refresh option:

import { transform } from "oxc-transform";

const result = await transform("App.jsx", sourceCode, {
  jsx: {
    development: true,
    refresh: true,
    // or...
    // refresh: {
    //   refreshReg: "$RefreshReg$",
    //   refreshSig: "$RefreshSig$",
    //   emitFullSignatures: true,
    // },
  },
});

配置选项

🌐 Configuration Options

选项	类型	默认值	描述
refreshReg	string	"$RefreshReg$"	用于注册组件以刷新功能的函数名称
refreshSig	string	"$RefreshSig$"	用于创建刷新签名的函数名称
emitFullSignatures	boolean	false	是否发出完整签名以便更好地调试