JSX

Oxc 转换器支持对 JSX 进行转换。

一般用法

import { transform } from "oxc-transform";

const result = await transform("App.jsx", sourceCode, {
  jsx: {
    runtime: "automatic", // 或 "classic"
    development: false, // 或 true
    throwIfNamespace: true, // 或 false
    pure: true, // 或 false
    importSource: "react",
    pragma: "React.createElement",
    pragmaFrag: "React.Fragment",
    refresh: false, // 详见下文
  },
  // 当转换 TSX 文件时：
  typescript: {
    jsxPragma: "React.createElement", // 与 `jsx.pragma` 值相同
    jsxPragmaFrag: "React.Fragment", // 与 `jsx.pragmaFrag` 值相同
  },
});

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

Oxc 转换器还支持 JSX 语法注释，这一功能同样被 Babel 和 esbuild 支持。语法注释对于在单个文件级别配置 JSX 选项非常有用。

运行时

默认情况下，使用自动运行时转换。该转换于 React 17+ 中引入 见文档。此转换会自动注入所需的 import 语句。

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

// @jsxRuntime classic / // @jsxRuntime automatic 是通过语法注释进行配置的方式。

两种运行时共用的选项

开发模式转换

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

XML 命名空间标签名称

默认情况下，如果使用了 XML 命名空间标签名称（例如 <foo:bar baz:qux="foobar" />），会抛出错误。尽管 JSX 规范允许这种写法，但由于当前 React 的 JSX 不支持命名空间，因此默认禁止。你可以通过将 jsx.throwIfNamespace 选项设为 false 来允许此类写法。

纯注解

默认情况下，JSX 元素会被加上纯注解。纯注解是用于标记那些在返回值未被使用时可安全移除的表达式的注释。但如果你希望保留这些 JSX 元素，则可能不希望启用此功能。你可以通过将 jsx.pure 选项设为 false 来关闭此功能。

自动运行时特有选项

导入源

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

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

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

// @jsxImportSource preact 是通过语法注释进行配置的方式。

经典运行时特有选项

语法工厂

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

// @jsx createElement 是通过语法注释进行配置的方式。

语法片段

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

// @jsxFrag Fragment 是通过语法注释进行配置的方式。

React Refresh

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

使用方法

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

import { transform } from "oxc-transform";

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

配置选项

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