采用React编写小程序的Remax框架的编译流程解析

Z时代
2024-01-10
分类：综合

react

Remax是蚂蚁开源的一个用React来开发小程序的框架，采用运行时无语法限制的方案。整体研究下来主要分为三大部分：运行时原理、模板渲染原理、编译流程；看了下现有大部分文章主要集中在Reamx的运行时和模板渲染原理上，而对整个React代码编译为小程序的流程介绍目前还没有看到，本文即是来补充这个空白。

关于模板渲染原理看这篇文章：https://juejin.cn/post/6844904131157557262

关于remax运行时原理看这篇文章：https://juejin.cn/post/6881597846307635214#heading-22 https://zhuanlan.zhihu.com/p/83324871

关于React自定义渲染器看这篇文章：https://juejin.cn/post/6844903753242378248

Remax的基本结构：

1、remax-runtime 运行时，提供自定义渲染器、宿主组件的包装、以及由React组件到小程序的App、Page、Component的配置生成器

// 自定义渲染器
export { default as render } from './render';
// 由app.js到小程序App构造器的配置处理
export { default as createAppConfig } from './createAppConfig';
// 由React到小程序Page页面构造器的一系列适配处理
export { default as createPageConfig } from './createPageConfig';
// 由React组件到小程序自定义组件Component构造器的一系列适配处理
export { default as createComponentConfig } from './createComponentConfig';
// 
export { default as createNativeComponent } from './createNativeComponent';
// 生成宿主组件，比如小程序原生提供的View、Button、Canvas等
export { default as createHostComponent } from './createHostComponent';
export { createPortal } from './ReactPortal';
export { RuntimeOptions, PluginDriver } from '@remax/framework-shared';
export * from './hooks';
import { ReactReconcilerInst } from './render';
export const unstable_batchedUpdates = ReactReconcilerInst.batchedUpdates;
export default {
  unstable_batchedUpdates,
};

2、remax-wechat 小程序相关适配器

template模板相关，与模板相关的处理原则及原理可以看这个https://juejin.cn/post/6844904131157557262

templates // 与渲染相关的模板

src/api 适配与微信小程序相关的各种全局api，有的进行了promisify化

import { promisify } from '@remax/framework-shared';
declare const wx: WechatMiniprogram.Wx;
export const canIUse = wx.canIUse;
export const base64ToArrayBuffer = wx.base64ToArrayBuffer;
export const arrayBufferToBase64 = wx.arrayBufferToBase64;
export const getSystemInfoSync = wx.getSystemInfoSync;
export const getSystemInfo = promisify(wx.getSystemInfo);

src/types/config.ts 与小程序的Page、App相关配置内容的适配处理

/** 页面配置文件 */

// reference: https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/page.html

export interface PageConfig {

/**

* 默认值：#000000

* 导航栏背景颜色，如 #000000

navigationBarBackgroundColor?: string;

/**

* 默认值：white

* 导航栏标题颜色，仅支持 black / white

navigationBarTextStyle?: 'black' | 'white';

/** 全局配置文件 */

// reference: https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html

export interface AppConfig {

/**

* 页面路径列表

pages: string[];

/**

* 全局的默认窗口表现

window?: {

/**

* 默认值：#000000

* 导航栏背景颜色，如 #000000

navigationBarBackgroundColor?: string;

/**

* 默认值: white

* 导航栏标题颜色，仅支持 black / white

navigationBarTextStyle?: 'white' | 'black';

src/types/component.ts 微信内置组件相关的公共属性、事件等属性适配

import * as React from 'react';
/** 微信内置组件公共属性 */
// reference: https://developers.weixin.qq.com/miniprogram/dev/framework/view/component.html
export interface BaseProps {
  /** 自定义属性: 组件上触发的事件时，会发送给事件处理函数 */
  readonly dataset?: DOMStringMap;
  /** 组件的唯一标示: 保持整个页面唯一 */
  id?: string;
  /** 组件的样式类: 在对应的 WXSS 中定义的样式类 */
  className?: string;
  /** 组件的内联样式: 可以动态设置的内联样式 */
  style?: React.CSSProperties;
  /** 组件是否显示: 所有组件默认显示 */
  hidden?: boolean;
  /** 动画对象: 由`wx.createAnimation`创建 */
  animation?: Array<Record<string, any>>;
  // reference: https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxml/event.html
  /** 点击时触发 */
  onTap?: (event: TouchEvent) => void;
  /** 点击时触发 */
  onClick?: (event: TouchEvent) => void;
  /** 手指触摸动作开始 */
  onTouchStart?: (event: TouchEvent) => void;

src/hostComponents 针对微信小程序宿主组件的包装和适配；node.ts是将小程序相关属性适配到React的规范

export const alias = {
  id: 'id',
  className: 'class',
  style: 'style',
  animation: 'animation',
  src: 'src',
  loop: 'loop',
  controls: 'controls',
  poster: 'poster',
  name: 'name',
  author: 'author',
  onError: 'binderror',
  onPlay: 'bindplay',
  onPause: 'bindpause',
  onTimeUpdate: 'bindtimeupdate',
  onEnded: 'bindended',
};
export const props = Object.values(alias);

各种组件也是利用createHostComponent生成

import * as React from 'react';
import { createHostComponent } from '@remax/runtime';
// 微信已不再维护
export const Audio: React.ComponentType = createHostComponent('audio');

createHostComponent生成React的Element

import * as React from 'react';
import { RuntimeOptions } from '@remax/framework-shared';
export default function createHostComponent<P = any>(name: string, component?: React.ComponentType<P>) {
  if (component) {
    return component;
  }
  const Component = React.forwardRef((props, ref: React.Ref<any>) => {
    const { children = [] } = props;
    let element = React.createElement(name, { ...props, ref }, children);
    element = RuntimeOptions.get('pluginDriver').onCreateHostComponentElement(element) as React.DOMElement<any, any>;
    return element;
  });
  return RuntimeOptions.get('pluginDriver').onCreateHostComponent(Component);
}

3、remax-macro 按照官方描述是基于babel-plugin-macros的宏；所谓宏是在编译时进行字符串的静态替换，而Javascript没有编译过程，babel实现宏的方式是在将代码编译为ast树之后，对ast语法树进行操作来替换原本的代码。详细文章可以看这里https://zhuanlan.zhihu.com/p/64346538；

remax这里是利用macro来进行一些宏的替换，比如useAppEvent和usePageEvent等，替换为从remax/runtime中进行引入

import { createMacro } from 'babel-plugin-macros';
import createHostComponentMacro from './createHostComponent';
import requirePluginComponentMacro from './requirePluginComponent';
import requirePluginMacro from './requirePlugin';
import usePageEventMacro from './usePageEvent';
import useAppEventMacro from './useAppEvent';
function remax({ references, state }: { references: { [name: string]: NodePath[] }; state: any }) {
  references.createHostComponent?.forEach(path => createHostComponentMacro(path, state));
  references.requirePluginComponent?.forEach(path => requirePluginComponentMacro(path, state));
  references.requirePlugin?.forEach(path => requirePluginMacro(path));
  const importer = slash(state.file.opts.filename);
  Store.appEvents.delete(importer);
  Store.pageEvents.delete(importer);
  references.useAppEvent?.forEach(path => useAppEventMacro(path, state));
  references.usePageEvent?.forEach(path => usePageEventMacro(path, state));
}
export declare function createHostComponent<P = any>(
  name: string,
  props: Array<string | [string, string]>
): React.ComponentType<P>;
export declare function requirePluginComponent<P = any>(pluginName: string): React.ComponentType<P>;
export declare function requirePlugin<P = any>(pluginName: string): P;
export declare function usePageEvent(eventName: PageEventName, callback: (...params: any[]) => any): void;
export declare function useAppEvent(eventName: AppEventName, callback: (...params: any[]) => any): void;
export default createMacro(remax);

import * as t from '@babel/types';
import { slash } from '@remax/shared';
import { NodePath } from '@babel/traverse';
import Store from '@remax/build-store';
import insertImportDeclaration from './utils/insertImportDeclaration';
const PACKAGE_NAME = '@remax/runtime';
const FUNCTION_NAME = 'useAppEvent';
function getArguments(callExpression: NodePath<t.CallExpression>, importer: string) {
  const args = callExpression.node.arguments;
  const eventName = args[0] as t.StringLiteral;
  const callback = args[1];
  Store.appEvents.set(importer, Store.appEvents.get(importer)?.add(eventName.value) ?? new Set([eventName.value]));
  return [eventName, callback];
}
export default function useAppEvent(path: NodePath, state: any) {
  const program = state.file.path;
  const importer = slash(state.file.opts.filename);
  const functionName = insertImportDeclaration(program, FUNCTION_NAME, PACKAGE_NAME);
  const callExpression = path.findParent(p => t.isCallExpression(p)) as NodePath<t.CallExpression>;
  const [eventName, callback] = getArguments(callExpression, importer);
  callExpression.replaceWith(t.callExpression(t.identifier(functionName), [eventName, callback]));
}

个人感觉这个设计有些过于复杂，可能跟remax的设计有关，在remax/runtime中，useAppEvent实际从remax-framework-shared中导出；

不过也倒是让我学到了一种对代码修改的处理方式。

4、remax-cli remax的脚手架，整个remax工程，生成到小程序的编译流程也是在这里处理。

先来看一下一个作为Page的React文件是如何与小程序的原生Page构造器关联起来的。

假设原先页面代码是这个样子，

import * as React from 'react';
import { View, Text, Image } from 'remax/wechat';
import styles from './index.css';
export default () => {
  return (
    <View className={styles.app}>
      <View className={styles.header}>
        <Image
          src="https://gw.alipayobjects.com/mdn/rms_b5fcc5/afts/img/A*OGyZSI087zkAAAAAAAAAAABkARQnAQ"
          className={styles.logo}
          alt="logo"
        />
        <View className={styles.text}>
          编辑 <Text className={styles.path}>src/pages/index/index.js</Text>开始
        </View>
      </View>
    </View>
  );
};

这部分处理在remax-cli/src/build/entries/PageEntries.ts代码中，可以看到这里是对源码进行了修改，引入了runtime中的createPageConfig函数来对齐React组件与小程序原生Page需要的属性，同时调用原生的Page构造器来实例化页面。

import * as path from 'path';
import VirtualEntry from './VirtualEntry';
export default class PageEntry extends VirtualEntry {
  outputSource() {
    return `
      import { createPageConfig } from '@remax/runtime';
      import Entry from './${path.basename(this.filename)}';
      Page(createPageConfig(Entry, '${this.name}'));
    `;
  }
}

createPageConfig来负责将React组件挂载到remax自定义的渲染容器中，同时对小程序Page的各个生命周期与remax提供的各种hook进行关联

export default function createPageConfig(Page: React.ComponentType<any>, name: string) {
  const app = getApp() as any;
  const config: any = {
    data: {
      root: {
        children: [],
      },
      modalRoot: {
        children: [],
      },
    },
    wrapperRef: React.createRef<any>(),
    lifecycleCallback: {},
    onLoad(this: any, query: any) {
      const PageWrapper = createPageWrapper(Page, name);
      this.pageId = generatePageId();
      this.lifecycleCallback = {};
      this.data = { // Page中定义的data实际是remax在内存中生成的一颗镜像树
        root: {
          children: [],
        },
        modalRoot: {
          children: [],
        },
      };
      this.query = query;
      // 生成自定义渲染器需要定义的容器
      this.container = new Container(this, 'root');
      this.modalContainer = new Container(this, 'modalRoot');
      // 这里生成页面级别的React组件
      const pageElement = React.createElement(PageWrapper, {
        page: this,
        query,
        modalContainer: this.modalContainer,
        ref: this.wrapperRef,
      });
      if (app && app._mount) {
        this.element = createPortal(pageElement, this.container, this.pageId);
        app._mount(this);
      } else {
          // 调用自定义渲染器进行渲染
        this.element = render(pageElement, this.container);
      }
      // 调用生命周期中的钩子函数
      return this.callLifecycle(Lifecycle.load, query);
    },
    onUnload(this: any) {
      this.callLifecycle(Lifecycle.unload);
      this.unloaded = true;
      this.container.clearUpdate();
      app._unmount(this);
    },

Container是按照React自定义渲染规范定义的根容器，最终是在applyUpdate方法中调用小程序原生的setData方法来更新渲染视图

applyUpdate() {
  if (this.stopUpdate || this.updateQueue.length === 0) {
    return;
  }
  const startTime = new Date().getTime();
  if (typeof this.context.$spliceData === 'function') {
    let $batchedUpdates = (callback: () => void) => {
      callback();
    };
    if (typeof this.context.$batchedUpdates === 'function') {
      $batchedUpdates = this.context.$batchedUpdates;
    }
    $batchedUpdates(() => {
      this.updateQueue.map((update, index) => {
        let callback = undefined;
        if (index + 1 === this.updateQueue.length) {
          callback = () => {
            nativeEffector.run();
            /* istanbul ignore next */
            if (RuntimeOptions.get('debug')) {
              console.log(`setData => 回调时间：${new Date().getTime() - startTime}ms`);
            }
          };
        }
        if (update.type === 'splice') {
          this.context.$spliceData(
            {
              [this.normalizeUpdatePath([...update.path, 'children'])]: [
                update.start,
                update.deleteCount,
                ...update.items,
              ],
            },
            callback
          );
        }
        if (update.type === 'set') {
          this.context.setData(
            {
              [this.normalizeUpdatePath([...update.path, update.name])]: update.value,
            },
            callback
          );
        }
      });
    });
    this.updateQueue = [];
    return;
  }
  const updatePayload = this.updateQueue.reduce<{ [key: string]: any }>((acc, update) => {
    if (update.node.isDeleted()) {
      return acc;
    }
    if (update.type === 'splice') {
      acc[this.normalizeUpdatePath([...update.path, 'nodes', update.id.toString()])] = update.items[0] || null;
      if (update.children) {
        acc[this.normalizeUpdatePath([...update.path, 'children'])] = (update.children || []).map(c => c.id);
      }
    } else {
      acc[this.normalizeUpdatePath([...update.path, update.name])] = update.value;
    }
    return acc;
  }, {});
  // 更新渲染视图
  this.context.setData(updatePayload, () => {
    nativeEffector.run();
    /* istanbul ignore next */
    if (RuntimeOptions.get('debug')) {
      console.log(`setData => 回调时间：${new Date().getTime() - startTime}ms`, updatePayload);
    }
  });
  this.updateQueue = [];
}

而对于容器的更新是在render文件中的render方法进行的，

function getPublicRootInstance(container: ReactReconciler.FiberRoot) {
  const containerFiber = container.current;
  if (!containerFiber.child) {
    return null;
  }
  return containerFiber.child.stateNode;
}
export default function render(rootElement: React.ReactElement | null, container: Container | AppContainer) {
  // Create a root Container if it doesnt exist
  if (!container._rootContainer) {
    container._rootContainer = ReactReconcilerInst.createContainer(container, false, false);
  }
  ReactReconcilerInst.updateContainer(rootElement, container._rootContainer, null, () => {
    // ignore
  });
  return getPublicRootInstance(container._rootContainer);
}

另外这里渲染的组件，其实也是经过了createPageWrapper包装了一层，主要是为了处理一些forward-ref相关操作。

现在已经把页面级别的React组件与小程序原生Page关联起来了。

对于Component的处理与这个类似，可以看remax-cli/src/build/entries/ComponentEntry.ts文件

import * as path from 'path';
import VirtualEntry from './VirtualEntry';
export default class ComponentEntry extends VirtualEntry {
  outputSource() {
    return `
      import { createComponentConfig } from '@remax/runtime';
      import Entry from './${path.basename(this.filename)}';
      Component(createComponentConfig(Entry));
    `;
  }
}

那么对于普通的组件，remax会把他们编译称为自定义组件，小程序的自定义组件是由json wxml wxss js组成，由React组件到这些文件的处理过程在remax-cli/src/build/webpack/plugins/ComponentAsset中处理，生成wxml、wxss和js文件

export default class ComponentAssetPlugin {
  builder: Builder;
  cache: SourceCache = new SourceCache();
  constructor(builder: Builder) {
    this.builder = builder;
  }
  apply(compiler: Compiler) {
    compiler.hooks.emit.tapAsync(PLUGIN_NAME, async (compilation, callback) => {
      const { options, api } = this.builder;
      const meta = api.getMeta();
      const { entries } = this.builder.entryCollection;
      await Promise.all(
        Array.from(entries.values()).map(async component => {
          if (!(component instanceof ComponentEntry)) {
            return Promise.resolve();
          }
          const chunk = compilation.chunks.find(c => {
            return c.name === component.name;
          });
          const modules = [...getModules(chunk), component.filename];
          let templatePromise;
          if (options.turboRenders) {
            // turbo page
            templatePromise = createTurboTemplate(this.builder.api, options, component, modules, meta, compilation);
          } else {
            templatePromise = createTemplate(component, options, meta, compilation, this.cache);
          }
          await Promise.all([
            await templatePromise,
            await createManifest(this.builder, component, compilation, this.cache),
          ]);
        })
      );
      callback();
    });
  }
}