@isvrax/isv-plugin-rax-compat

An ice.js plugin for migrating rax-app projects.

Usage

Add plugin in ice.config.mts:

import { defineConfig } from 'ice';
import compatRax from '@isvrax/isv-plugin-rax-compat';

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

Options

inlineStyle

• Default: false.
• 将css样式转换为style样式.

cssModule

• Default: true
• 当 inlineStyle 启用且 cssModule 不启用时, CSS Module 文件也会转转换为style行内样式（不推荐）

legacy

• Default: false
• Enable legacy way to import rax as namespace, like v0.6:

import Rax from 'rax';

Rax.createContext();

说明

这个插件将会处理这些兼容逻辑：

• 类型定义，Rax 中的类型定义来自于 React 16.8 前，与 React 18 的类型定义存在一些差异。

  • 这个插件会新增一个对 Rax namespace 进行声明的 .d.ts 文件，内部使用 React 类型定义来进行声明。

• 别名，将组成 rax 核心逻辑的 rax- 包，如 rax-children 等，映射到 rax-compat 的内部实现。

  • 同时，在启用 legacy 模式时，会将 rax 映射到 rax-compat-legacy-exports.ts，此文件支持了 Rax.createContext 这样的使用方式（Rax v0.6.x）。

• JSX，插件内部将基于源码类型来调整 swc 的编译配置。

  • 在源码中使用了 @jsx createElement annotation 时，将设置 jsx runtime 为 classic。
  • 在源码导入了 rax 包时，将设置 importSource 为 rax-compat/runtime（与 React 18 保持一致）。

• 屏幕适配

  • 在 isv-h5-adapter/rax 中，已经将 rax 组件的 px 值用 style-unit 转换为 vm。特别注意，本插件将 lineHeight 属性也视作以 px 为单位进而转换为了 vm 单位。

• 样式对象

  • 由于本插件是处理的rax 0.x 版本，该版本支持数组形式的 style 对象，也进行了兼容。

• css样式转为行内样式，在启用 inlineStyle 时，插件内部将额外处理行内样式逻辑。

  • 首先，JSXClassNameTransformer 会将源码中的 <div className="header" /> 的写法转换为 <div style={styleSheet.header} />。 - 注意，只有项目源码内的代码才会被转换。

    - 注意，scss/less的嵌套写法不能生效。
    
    - 注意，`<div className={'xxx'} />` 这样的写法不会被转换。
            
    - 注意，`*.module.css` 和 `*.global.css`这样的文件不会被转换。

  • 接着，在 ClientSide，插件会覆盖原本的 Webpack Ruleset：

    • 对于命中了 inlineStyle 的资源文件，会使用 stylesheet-loader 进行处理为 styleSheet 对象（非 css 文件还会先交由预处理器编译）。其它文件会保持原本的处理逻辑，即处理到额外的 CSS 文件中。
    • 注意，目前在 --speedup 下此逻辑无法生效。
    • 注意，如果禁用了 cssModule ，那么 .module.css(less/...) 文件也会被交由 stylesheet-loader 处理。

  • 在 ServerSide，对命中了 inlineStyle 的资源文件，会使用 esbuild 进行处理为 styleSheet 对象(文件的类型会被改变为 JS 文件)。

  • 关于行内样式的额外说明：

    • 只有项目源码中使用了 className="xxx" 的写法，才会被转换为 style={styleSheet.xxx} 的写法，因此 CSS Module 使用的 className={styles.xxx} 这种写法也不会被转换。

    • 来自 node_modules 的代码不会被转换。

    • 只有项目使用了 css 方式来覆盖 rax/rox/nuke 等 weex 系组件的工程中才需要启用，不建议直接将 inlineStyle 设置为true，而是用函数的方式通过文件路径来判断是否需要执行转换：inlineStyle: (path) => path.includes('not-react-component-file')，通过这样可排除对 react 组件文件及其样式的转换，否则可能引起非期望样式丢失问题。