# 子应用开发

本文介绍如何基于平台子应用框架开发前端子应用。子应用以 iframe 方式嵌入平台页面,并通过父应用提供的共享上下文、组件代理和样式同步能力,与平台保持一致的登录态、权限、主题和交互体验。

# 适用场景

当业务功能需要以前端子应用的形式接入平台,且希望复用平台已有的 React Context、Redux Store、Ant Design 全局配置、通用组件、工具函数和样式主题时,可以使用该子应用开发框架。

开发前请先获取子应用工程代码,并在子应用工程目录下执行后续命令。

# 技术栈

子应用当前主要使用以下技术:

类型 技术
构建工具 Vite、Node.js
前端框架 React、React Router、Redux
UI 组件 Ant Design、Less
开发语言 JavaScript、TypeScript

# 架构说明

子应用不独立打包 react、react-dom、react-redux 等核心运行时依赖,而是在运行时从父应用获取共享实例。这样可以避免 iframe 隔离导致的上下文丢失问题,保证子应用与父应用使用同一套 React 上下文和全局状态。

graph LR User["用户访问平台页面"] --> Parent["父应用"] Parent --> Iframe["iframe 容器"] Iframe --> Child["子应用"] Parent --> SharedContext["共享上下文<br/>React / Redux / Ant Design 配置"] SharedContext --> Child Parent --> Portal["Portal 挂载"] Portal --> Child Parent --> ParentModules["父应用开放能力<br/>组件 / Hooks / Selectors / 工具函数"] ParentModules --> Bridge["src/parent 代理层"] Bridge --> Child Parent --> Styles["样式资源与 CSS Variables"] Styles --> Child Child --> Pages["子应用页面与业务逻辑"]

# React 实例共享

子应用通过 Vite 插件处理 React 相关导入,在运行时从父应用获取共享实例。父应用需要提供对应的共享上下文入口,子应用再基于该入口使用统一的 React、Redux 和全局配置。

# Portal 挂载

当子应用检测到处于父应用 iframe 环境时,不会自行执行独立渲染,而是将应用节点交给父应用,由父应用通过 Portal 方式挂载到 iframe 内部。

sequenceDiagram participant Parent as 父应用 participant Iframe as iframe 容器 participant Child as 子应用入口 participant Portal as Portal 渲染 Parent->>Iframe: 创建 iframe 容器 Iframe->>Child: 加载子应用入口 Child->>Parent: 检测并提交 App 节点 Parent->>Portal: 使用共享 React 创建 Portal Portal->>Iframe: 将子应用渲染到 iframe 内

# 父应用模块代理

子应用通过 src/parent/ 下的代理文件使用父应用能力,包括组件、Hooks、Selectors 和工具函数。代理文件由脚本生成,开发者通常不需要手工维护。

src/parent/
├── components/index.ts
├── hooks/index.ts
├── selectors/index.ts
└── utils/index.ts
graph LR ChildCode["子应用业务代码"] --> ImportParent["@/parent 引入"] ImportParent --> Components["components<br/>组件代理"] ImportParent --> Hooks["hooks<br/>Hooks 代理"] ImportParent --> Selectors["selectors<br/>Selectors 代理"] ImportParent --> Utils["utils<br/>工具函数代理"] Components --> ParentRegistry["父应用注册能力"] Hooks --> ParentRegistry Selectors --> ParentRegistry Utils --> ParentRegistry ParentRegistry --> Runtime["运行时调用父应用实现"]

# 样式同步

子应用运行时会同步父应用的样式资源和 CSS Variables,使页面主题、字体、颜色和组件样式与平台保持一致。

样式同步效果

# 目录结构

子应用仓库的核心目录如下:

frontend_embedded/
├── scripts/
│   ├── dev.mjs
│   └── generate-parent-bridge.mjs
├── src/
│   ├── parent/
│   ├── pages/
│   ├── routes/
│   ├── App.jsx
│   └── main.jsx
├── package.json
└── vite.config.js
路径 说明
scripts/dev.mjs 联合开发启动脚本
scripts/generate-parent-bridge.mjs 父应用桥接代理文件生成脚本
src/parent/ 自动生成的父应用模块代理
src/pages/ 子应用页面目录
src/routes/ 子应用路由封装
src/App.jsx 子应用根组件
src/main.jsx 子应用入口,负责判断独立模式或父应用挂载模式
vite.config.js Vite 构建配置

# 开发环境准备

首次开发前,需要先完成平台 npm 源配置和登录。npm 制品库的配置、认证和使用方式请参考制品库快速入门及制品库使用说明。

npm install --legacy-peer-deps

# 本地启动

在子应用仓库目录下执行:

npm start

该命令会启动联合开发环境,用于同时调试子应用和父应用。

本地启动成功页面

如需指定代理路径和目标服务,可以通过环境变量配置:

CUSTOM_PROXY_PATH=/v1/test CUSTOM_PROXY_TARGET=http://127.0.0.1:8788 npm start -- --proxyHost https://平台访问地址

# 生产构建

执行以下命令生成生产环境构建产物:

npm run build

# 使用父应用能力

开发子应用时,应优先复用父应用已经提供的组件、工具函数、Hooks 和 Selectors,避免在子应用中重复实现平台通用能力。

import { Button } from '@/parent/components';
import { readableDuration } from '@/parent/utils';
import { getUserInfo } from '@/parent/selectors';

父应用组件代理支持 ref 透传,工具函数、Hooks 和 Selectors 通过代理对象在运行时调用父应用注册的能力。

# 新增页面

新增页面时,建议按照以下步骤处理:

graph LR PageDir["新增 pages 页面目录"] --> PageCode["编写页面组件与样式"] PageCode --> Services["维护接口请求逻辑"] Services --> Route["注册页面路由"] Route --> ParentApi["复用 @/parent 平台能力"] ParentApi --> Dev["启动本地开发环境"] Dev --> Verify["在父应用嵌入场景验证"]
  1. 在 src/pages/ 下新增页面目录。
  2. 在页面目录中维护页面组件、样式和接口请求逻辑。
  3. 在路由配置中注册页面路由。
  4. 优先从 @/parent/ 引入平台通用组件和能力。
  5. 启动本地开发环境,在父应用嵌入场景下验证页面表现。

# 更新父应用桥接代理

当 @ezone/subapp-toolkit 更新,或父应用暴露的组件、Hooks、Selectors、工具函数发生变化时,需要重新生成桥接代理文件。

node scripts/generate-parent-bridge.mjs

生成完成后,检查 src/parent/ 下的文件变化,并在子应用中按需引用新的能力。

# 开发注意事项

  • 不要在子应用中重复安装或打包父应用已经共享的 React 核心依赖。
  • 不要手工修改 src/parent/ 下的自动生成文件,确需更新时应重新执行生成脚本。
  • 需要复用平台能力时,优先从 @/parent/ 引入。
  • 页面样式应遵循平台现有规范,避免引入与平台主题冲突的全局样式。
  • 接口请求、登录态、权限和跳转逻辑需要在父应用嵌入环境中验证。
  • 独立模式可以用于基础调试,但最终效果应以父应用挂载场景为准。

# 常见问题

# 子应用是否可以独立运行?

可以用于基础调试,但完整的登录态、上下文、全局状态、样式和父应用能力需要在平台嵌入场景下验证。

# 父应用新增了组件,子应用为什么无法直接引用?

需要确认父应用是否已经暴露该组件,并在子应用中重新执行桥接代理生成脚本。

# 页面样式与平台不一致怎么办?

优先确认父应用样式是否已同步到子应用,再检查页面是否引入了覆盖平台主题的全局样式。