rax-compat 运行时兼容层:让 Rax 代码跑在真实 React 18 之上(ice.js 渐进式框架实践)

原创2026-09-20 21:46:121,394 阅读
文章标签:前端Web框架小程序SSR前端构建

rax-compat 运行时兼容层:让 Rax 代码跑在真实 React 18 之上(ice.js 渐进式框架实践)

rax-compat 是 ice.js 仓库中一个面向“存量 Rax 项目平滑迁移”的运行时 polyfill 包:开发者继续用 Rax 的 API 与心智模型书写组件,但底层实际渲染由真实 React 完成。本文以 packages/rax-compat/README.md 为核心,结合该包源码、测试与配套插件,说明 rax-compat 的 API 用法、打包配置方式,以及它在属性归一化、样式单位、事件映射、受控输入、Hooks 行为等关键点上是如何抹平 Rax 与 React 运行时差异的。读完本文,你将掌握在 ice.js 项目中用 rax-compat 迁移或复用 Rax 代码的完整方案,并理解其底层实现原理。

一、rax-compat 是什么:一次运行时层的“翻译”

rax-compat 在 package.json 中的自述是:

"Rax compatible mode, running rax project on the react runtime."

即:用 Rax 的语法写代码,但渲染时交给真正的 React 执行。它自身不实现任何渲染引擎,而是作为 polyfill 把 Rax 生态的调用约定转换成 React 能理解的形式:

  • Rax 风格的 createElement、render、Hooks、Component、Fragment 等 API,被一一映射到 React 18 的对应实现;
  • Rax 特有的约定(如 style 支持数组、rpx 单位、ontouchstart 事件名、onAppear/onDisappear 可见性事件、<input value> 双向行为)在属性进入 React 之前被“翻译”成 React 的标准形式。

从仓库目录看,rax-compat 是一个独立的 monorepo 包,src/ 下按职责拆分了二十余个模块(create-element.ts、render.ts、props.ts、style.ts、events.ts、hooks.ts、shared.ts、compat/ 等),并有覆盖 16 个测试文件的测试集(见 packages/rax-compat/tests),足以支撑生产级使用。

二、快速上手:createElement 与 JSX 两种写法

README 给出的最简用法是直接调用 Rax 风格的 createElement:

import { createElement } from 'rax-compat';

export default function() {
  return createElement('div', null, 'Hello World');
}

这里 createElement 与 Rax/早期 React 的签名一致:createElement(type, props, ...children)。在 create-element.ts 中可以看到它是对 React 原生 createElement 的封装:当 props.style 是数组时,会先通过 normalizeStyleProp 把 CSSProperties[] 展平合并成一个普通对象,避免 React 抛 Failed to set an indexed property on 'CSSStyleDeclaration' 错误——这是 Rax 允许 style 传数组、而 React 不允许的典型差异点。

除了 createElement 写法,rax-compat 同样支持 JSX。README 特别指出:

Also works with JSX, should be configured with packer(webpack/turbopack).

这是因为 JSX 的编译产物(React.createElement(...) 或 jsx()/jsxs())需要一个“编译目标”。rax-compat 在 exports 中专门暴露了两个子路径(见 package.json):

  • rax-compat/runtime/jsx-runtime:提供 jsx、jsxs、Fragment,对应 React 18 的自动 JSX 运行时;
  • rax-compat/runtime/jsx-dev-runtime:开发模式的对应实现。

以 jsx-runtime.ts 为例,它把 React 自带的 jsx/jsxs 包进 createJSXElementFactory,从而让自动 JSX 也走完整的兼容转换管线。配置方式有两种:

  1. 手动配置打包器:将 JSX runtime 指向 rax-compat/runtime/jsx-runtime(等价于 React 18 的 react/jsx-runtime);
  2. 使用配套插件 @ice/plugin-rax-compat(推荐,见下文第五节),插件会自动按源码情况调整 SWC 的 JSX 编译配置。

三、完整 API 面:一份“模拟 Rax”的导出清单

rax-compat 的入口 index.ts 与 exports.ts 定义了一套与 Rax 对齐的公共 API:

类别 导出 实现说明(源码位置)
元素创建 createElement、createFactory、cloneElement、isValidElement、createPortal、Fragment 见 src/create-element.ts、src/create-factory.ts 等
组件 Component、PureComponent、memo、forwardRef、createRef component.ts 直接 re-export React 对应实现
Context createContext hooks.ts
渲染 render、findDOMNode、unmountComponentAtNode 见 src/render.ts、src/find-dom-node.ts
Hooks useState、useEffect、useLayoutEffect、useRef、useCallback、useMemo、useReducer、useContext、useImperativeHandle hooks.ts
其他 shared、version(模拟值 '1.2.2-compat') shared.ts、exports.ts

其中 version 被刻意 mock 成 '1.2.2-compat',用于骗过那些在运行时检查 Rax 版本号的三方库(见 exports.ts 的注释 "Mocked version for rax")。shared 则模拟了 Rax 内部暴露的 Rax.shared 对象,包括 Element(构造带 $$typeof 标记的 React Element)、Host、Instance(挂载/卸载实例与 DOM 节点的关联)以及 flattenChildren(见 shared.ts)。

同时,为了兼容按子路径导入的 Rax 生态习惯,package.json 的 exports 字段还提供了 rax-compat/children、rax-compat/clone-element、rax-compat/create-factory、rax-compat/create-portal、rax-compat/find-dom-node、rax-compat/is-valid-element、rax-compat/unmount-component-at-node 等独立入口,一一对应 rax- 系列包(如 rax-children)。

四、运行时兼容的六大关键细节

这一节深入 rax-compat 的“翻译”管线。所有 JSX 与 createElement 最终都会经过 compat/element.ts 中的 createJSXElementFactory,按顺序完成以下处理。

4.1 属性(props)归一化:事件名与标准属性名映射

对真实 DOM(typeof type === 'string')节点,props.ts 会逐个遍历 props 并做两类转换:

  • 事件名:Rax 里 ontouchstart 这类小写事件名在 React 的事件插件系统中无法识别。rax-compat 维护了一张事件映射表 registrationNameToReactEvent(见 events.ts),它从 React 源码 fork 出完整事件清单(touchStart、animationEnd、transitionEnd、pointerMove 等数十个),统一注册为 on + 事件名 的映射,并特殊处理 dblclick -> onDoubleClick 这类名称不一致的事件。
  • 标准属性名:class、for、maxlength、autofocus、cellpadding 等非 React 标准写法,通过 possibleStandardNames 映射表转成 className、htmlFor、maxLength 等 React 标准写法;无法映射的(如 rax 组件特有的 resizeMode)则统一转小写,避免 React 报警告(见 props.ts)。

4.2 样式单位兼容:rpx 转 vw

Rax 面向多端,常使用 rpx 单位;React DOM 环境不认识它。style.ts 复用 style-unit 包的 convertUnit 与 cached:

  • 数值型样式值会按“是否为无量纲属性”判断后,把 ${value}rpx 转换为 vw 等可用单位;
  • 字符串值统一走 convertUnit;
  • 不会修改原始 style 对象,而是拷贝到新对象(Object.create(Object.prototype)),避免污染调用方(见 style.ts)。

无量纲属性(如 opacity、flex、zIndex、fontWeight、lineHeight、grid*、columnCount、tabSize、animationIterationCount 等)通过注释中列出的大正则 NON_DIMENSIONAL_REG 匹配,不会被错误地追加单位。

4.3 可见性事件:onAppear / onDisappear

Rax 的 onAppear/onDisappear 事件在 React 中不存在。rax-compat 在检测到真实 DOM 上挂有这两个回调时,会用 @ice/appear 提供的 VisibilityChange 组件包裹元素(见 compat/element.ts),由它监听可见性变化并触发回调;同时把这两个非标准 props 从真实 DOM 上删除。

4.4 受控输入:InputCompat

Rax 的 <input>/<textarea> 是“非受控但可改 value”的双向行为;React 中一旦传入 value 即变成受控组件,且 onChange 收到的是 SyntheticEvent 而非原生事件。rax-compat 用 compat/input.ts 中的 InputCompat(forwardRef 组件)替代原生元素:

  • 内部用 useState 维护 value,保证外部传值可生效;
  • onChange 回调通过原生 change/input 事件监听器以原生事件触发(延迟到 setTimeout 0),并同步刷新内部状态;
  • onInput 收到的是 event.nativeEvent。

转换发生在 compat/element.ts:当 type === 'input' || type === 'textarea' 时,把原始类型记录到 inputType,并将元素替换为 InputCompat。

4.5 render:基于 React 18 createRoot

render.ts 复刻了 Rax 的 render(element, container, options?, callback?) 签名,并兼容 Rax driver-dom 的“未传 container 时默认渲染到 document.body”行为(见其源码注释引用的 Rax 实现)。其内部直接使用 React 18 的 createRoot(...).render(...),并通过 containerRootMap 记录容器与 root 的关系(见 container-root-map.ts),供 unmountComponentAtNode 等卸载 API 复用。

4.6 Hooks 行为差异:useState 浅比较过滤

Rax 的 useState 在 set 相同值时不会触发重渲染,而 React 的 useState 没有此保证。rax-compat 在 hooks.ts 中封装了一层:用 ref 缓存“当前值”,setState 时先用 is(浅比较,见 is.ts)过滤相等值;同时支持函数式初始 state 与函数式更新。其余 Hooks(useEffect、useLayoutEffect、useContext、useRef、useMemo、useCallback、useReducer、useImperativeHandle)则直接透传 React 实现。

五、与 @ice/plugin-rax-compat 插件配合:ice.js 中的完整迁移方案

README 末尾提示的 @ice/plugin-rax-compat 是 rax-compat 在 ice.js 构建链路中的“接线员”。该插件位于 packages/plugin-rax-compat,其 README.md 给出了接入方式:

// ice.config.mts
import { defineConfig } from 'ice';
import compatRax from '@ice/plugin-rax-compat';

export default defineConfig(() => ({
  plugins: [compatRax({ /* options */ })],
}));

插件从 src/index.ts 归一化三个选项:

选项 默认值 作用
inlineStyle false 启用行内样式加载器,将 CSS 文件转成 styleSheet 对象内联到 JS 中
cssModule true 仅在 inlineStyle 开启时生效;禁用后 .module.css(less/...) 也会走 stylesheet-loader 内联处理(不推荐)
legacy false 启用 Rax v0.6 风格的命名空间导入:import Rax from 'rax'; Rax.createContext();

插件内部的四个 Service(AliasService / JSXService / StyleService / TypingsService)分别处理:

  1. 类型定义:Rax 的类型停留在 React 16.8 之前,与 React 18 类型存在差异;插件新增一份基于 React 类型声明 Rax namespace 的 .d.ts;
  2. 别名:把 rax-children、rax-clone-element 等构成 Rax 核心逻辑的 rax-* 包映射到 rax-compat 内部实现;legacy 模式下还会把 rax 映射到 legacy 导出文件,支持 Rax.createContext 用法;
  3. JSX 编译:源码中使用 @jsx createElement 注解时,将 SWC 的 JSX runtime 设为 classic;源码导入了 rax 时,设置 importSource 为 rax-compat/runtime(与 React 18 保持一致);
  4. 样式(仅 inlineStyle 开启时):先用 JSXClassNameTransformer 将源码里的 <div className="header" /> 转成 <div style={styleSheet.header} />,再在 ClientSide 用 stylesheet-loader 处理命中的资源文件、ServerSide 用 esbuild 处理。注意:只有项目源码内的 className="xxx" 字面量写法会被转换,className={styles.xxx}、className={'xxx'}、import './x.module.css' 以及 node_modules 中的代码均不会被转换,且 --speedup 模式下该逻辑不生效。

仓库中的 examples/rax-project 是一个完整的 Rax 风格示例工程(app.tsx、document.tsx、页面组件均以 Rax 写法组织),可作为迁移后的工程形态参考。

六、测试覆盖与工程化交付

rax-compat 的可靠性由 tests 目录下的 16 组测试保障,覆盖 createElement、render、cloneElement、createFactory、createPortal、createReactClass、findDomNode、Fragment、Hooks、inputElement、props、events、shared 等全部核心模块,且测试文件使用 .tsx,说明 JSX 编译链路本身也在测试范围内。

工程化方面:

  • 包以 ESM 形式交付("type": "module"),通过 plugin.mjs 使用 @ice/pkg 同时产出 esm、es2017、es2021 三套目标代码(对应 package.json 的 exports 多条件分发);
  • peerDependencies 声明 react/react-dom 为 ^18(见 package.json),即前提是项目使用 React 18;
  • 依赖仅 @ice/appear(可见性事件)、style-unit(单位转换)与 @swc/helpers,体积轻量。

七、适用边界与注意事项

  • React 版本前提:rax-compat 面向 React 18(createRoot 并发渲染),render 不再返回组件实例,返回的是元素本身;如果项目仍停留在 React 16/17,需要评估升级成本;
  • 它不解决 JSX 编译问题:rax-compat 只提供运行时 API,JSX 的编译目标必须由打包器或 @ice/plugin-rax-compat 配置,这也是 README 特别强调 "should be configured with packer" 的原因;
  • 行内样式转换有明确限制:只有字面量 className="xxx" 写法会被转换,动态 className、CSS Module、node_modules 代码均不受影响;
  • 部分 Rax 特性为“模拟”:version 是 mock 值,shared 是简化模拟(如 Instance.get 返回的是浅拷贝实例),依赖 Rax 深层内部行为的第三方库可能仍需要针对性适配。

总体而言,rax-compat 与 @ice/plugin-rax-compat 的组合,为存量 Rax 项目提供了一条“代码基本不动、运行时整体切换”的低成本迁移路径:把 rax-compat 当作 Rax 的替身注入,配合插件完成别名、JSX、样式与类型的构建期改造,即可让 Rax 代码在真实 React 18 上继续运行。

登录后查看全文
ice