@hhfenpm/miu-app

微前端 Child SDK，面向 MIU 子应用开发者。处理与 Shell 的握手、Token 获取、环境变量注入和生命周期管理。

安装

pnpm add @hhfenpm/miu-app

或通过 CDN：

<script src="miu-app.umd.js"></script>
<!-- 全局变量: window.MiuApp -->

快速开始

MiuApp.mount().then(function(ctx) {
  // ctx.env    -- 运行时环境（网关地址、配置等）
  // ctx.user   -- 当前医生信息
  // ctx.state  -- Shell 下发的全局状态快照

  ctx.getToken().then(function(token) {
    // 使用 token 调用业务接口
  });
});

独立开发模式

未被 MIU Shell 嵌入时，mount() 会立即 reject（非 iframe 环境），可用于区分环境：

MiuApp.mount().catch(function() {
  console.log('非 MIU 环境，使用本地 mock');
});

也可通过 window.__POWERED_BY_MIU__ 判断运行环境。

API

核心

| 方法 | 说明 | |------|------| | mount(config?, lifecycle?): Promise<MiuContext> | 握手挂载，返回上下文 | | destroy() | 销毁实例 |

Token & 环境

| 方法 | 说明 | |------|------| | getToken(): Promise<string> | 获取有效 Token（过期自动刷新） | | getEnv() | 获取完整运行时环境 | | getEnv(key) | 获取指定环境变量 | | getAppId(): string \| null | 获取平台唯一主键（后端 agentId），握手前返回 null | | getAppInfo(): MiuAppInfo \| null | 获取当前应用完整信息（appId/agentCode/name/version/icon），握手前返回 null |

全局状态

| 方法 | 说明 | |------|------| | getState() | 获取全局状态快照 | | setState(delta) | 合并更新全局状态 | | onStateChange(cb) | 订阅状态变化，返回取消订阅闭包 () => void |

消息通信

| 方法 | 说明 | |------|------| | send(action, payload?) | 发送消息到 Shell | | sendTo(appId, action, payload?) | 发送消息到指定应用 |

生命周期

| 方法 | 说明 | |------|------| | onActivate(cb) | 被激活为前台应用时回调 | | onDeactivate(cb) | 切换到后台时回调 |

路由同步

| 方法 | 说明 | |------|------| | router.sync(path, meta?) | 向 Shell 同步路由变化 |

事件系统

| 方法 | 说明 | |------|------| | on(event, handler) | 订阅事件 | | off(event, handler?) | 取消订阅 |

事件列表

| 事件 | 触发时机 | |------|---------| | activated | 被激活为前台应用 | | deactivated | 切换到后台 | | token:updated | 收到新 Token | | auth:expired | 全局 Auth 过期 | | env:updated | 环境变量变更 | | navigate | Shell 指令跳转 | | message | 收到消息 | | error | 握手失败 | | destroy | 即将被销毁 |

ChildConfig

mount() 第一参数，均为可选：

interface ChildConfig {
  appId?: string;              // 不传时自动从 URL 参数 __miu_app_id__ 读取
  capabilities?: string[];     // 声明子应用能力
  timeout?: number;            // @deprecated 改用 timeouts.messaging.requestTimeout
  timeouts?: ChildTimeoutConfig; // 企业级分层超时配置（profile 默认 'intranet'）
}

timeout 已废弃，仅作兼容映射到 timeouts.messaging.requestTimeout。默认超时取决于 timeouts.profile，未显式配置时为 intranet（请求超时 12000ms，IE11 自动倍增至 24000ms）。详见 Child SDK API 文档。

MiuLifecycle

mount() 第二参数，生命周期钩子（对标 qiankun mount/unmount）：

interface MiuLifecycle {
  onMount?: (ctx: MiuContext) => void | Promise<void>;   // 握手就绪后调用
  onUnmount?: () => void | Promise<void>;                // Shell 卸载时调用
}

MiuContext

mount() resolve 后返回的上下文对象：

interface MiuContext {
  appId: string;                    // 平台唯一主键（后端 agentId，ctx 构建时已解析为非空）
  app: MiuAppInfo;                  // 当前应用完整身份信息（等价 getAppInfo()）
  env?: RuntimeEnv;                 // 完整运行时环境（非 MIU 环境下为 undefined）
  user?: RuntimeEnv['user'];        // 当前医生信息（env.user 的别名）
  state: Record<string, unknown>;   // Shell 下发的全局状态快照
  getToken(): Promise<string>;      // 获取有效 Token（过期自动刷新）
}

详见 Child SDK API 文档

浏览器兼容性

IE11、Edge、Chrome、Firefox、Safari 最近 2 个版本。

产物为纯 ES5 UMD，零运行时第三方依赖。