rax-compat 运行时兼容层:让 Rax 代码跑在真实 React 18 之上(ice.js 渐进式框架实践)
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 也走完整的兼容转换管线。配置方式有两种:
- 手动配置打包器:将 JSX runtime 指向
rax-compat/runtime/jsx-runtime(等价于 React 18 的react/jsx-runtime); - 使用配套插件
@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)分别处理:
- 类型定义:Rax 的类型停留在 React 16.8 之前,与 React 18 类型存在差异;插件新增一份基于 React 类型声明 Rax namespace 的
.d.ts; - 别名:把
rax-children、rax-clone-element等构成 Rax 核心逻辑的rax-*包映射到 rax-compat 内部实现;legacy模式下还会把rax映射到 legacy 导出文件,支持Rax.createContext用法; - JSX 编译:源码中使用
@jsx createElement注解时,将 SWC 的 JSX runtime 设为classic;源码导入了rax时,设置importSource为rax-compat/runtime(与 React 18 保持一致); - 样式(仅
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 上继续运行。