@blueking/bk-weweb 0.0.35-beta.1 → 0.0.35-beta.2

package/dist/index.d.mts

@@ -131,19 +131,90 @@ declare class Style {
     private observeContentChanges;
 }
 
+/**
+ * 应用缓存管理器
+ * @description 负责管理所有微应用实例的缓存、资源共享和状态跟踪
+ */
 declare class AppCache {
-    private baseSource;
-    private cache;
+    /** 基础资源源，用于主应用共享资源包 */
+    private readonly baseSource;
+    /** 应用实例缓存映射表 */
+    private readonly cache;
+    /**
+     * 构造函数
+     * @description 初始化应用缓存管理器
+     */
     constructor();
-    deleteApp(url: string): void;
+    /**
+     * 设置应用实例到缓存
+     * @description 将应用实例添加到缓存中，使用应用的缓存键作为标识
+     * @param app - 要缓存的应用实例
+     * @returns void
+     */
+    setApp(app: BaseModel): void;
+    /**
+     * 获取缓存的应用实例
+     * @description 根据名称或ID获取已缓存的应用实例
+     * @param name - 应用名称或ID，为空时返回 undefined
+     * @returns BaseModel | undefined - 应用实例或 undefined
+     */
     getApp(name?: null | string): BaseModel | undefined;
-    getBaseAppStyle(urlOrCode: string): Style | undefined;
+    /**
+     * 删除缓存的应用实例
+     * @description 从缓存中移除指定URL的应用实例
+     * @param url - 要删除的应用URL标识
+     * @returns void
+     */
+    deleteApp(url: string): void;
+    /**
+     * 获取缓存的HTML内容
+     * @description 根据URL获取已缓存的HTML内容
+     * @param url - 应用的URL
+     * @returns string - HTML内容，未找到时返回空字符串
+     */
     getCacheHtml(url: string): string;
-    getCacheScript(url: string): Script | undefined;
-    getCacheStyle(url: string): Style | undefined;
-    setApp(app: BaseModel): void;
+    /**
+     * 设置基础应用脚本
+     * @description 将脚本添加到基础资源源中，供多个应用共享
+     * @param url - 脚本的URL
+     * @param script - 脚本实例
+     * @returns void
+     */
     setBaseAppScript(url: string, script: Script): void;
+    /**
+     * 获取缓存的脚本资源
+     * @description 从基础资源源或应用缓存中获取脚本资源
+     * @param url - 脚本的URL
+     * @returns Script | undefined - 脚本实例或 undefined
+     */
+    getCacheScript(url: string): Script | undefined;
+    /**
+     * 设置基础应用样式
+     * @description 将样式添加到基础资源源中，供多个应用共享
+     * @param url - 样式的URL
+     * @param style - 样式实例
+     * @returns void
+     */
     setBaseAppStyle(url: string, style: Style): void;
+    /**
+     * 获取基础应用样式
+     * @description 从基础资源源中获取样式资源
+     * @param urlOrCode - 样式的URL或代码
+     * @returns Style | undefined - 样式实例或 undefined
+     */
+    getBaseAppStyle(urlOrCode: string): Style | undefined;
+    /**
+     * 获取缓存的样式资源
+     * @description 从基础资源源或应用缓存中获取样式资源
+     * @param url - 样式的URL
+     * @returns Style | undefined - 样式实例或 undefined
+     */
+    getCacheStyle(url: string): Style | undefined;
+    /**
+     * 检查是否存在活跃的应用
+     * @description 判断当前是否有处于非卸载状态的应用实例
+     * @returns boolean - 存在活跃应用时返回 true
+     */
     get hasActiveApp(): boolean;
 }
 
@@ -174,46 +245,146 @@ declare const AppState: {
 type KeyOfAppState = keyof typeof AppState;
 type ValueOfAppState = (typeof AppState)[KeyOfAppState];
 
+/**
+ * BK WEWEB 支持的自定义属性枚举
+ * @description 定义了 bk-weweb 自定义元素支持的所有属性配置
+ */
 declare enum WewebCustomAttrs {
-    data = "data",// 传递给子应用的数据
-    id = "id",// 应用id
-    keepAlive = "keepAlive",// 是否缓存
-    mode = "mode",// 模式
-    scopeCss = "scopeCss",// 是否开启css隔离
-    scopeJs = "scopeJs",// 是否开启js隔离
-    scopeLocation = "scopeLocation",// 是否开启location隔离
-    setShodowDom = "setShodowDom",// 是否开启shadowDom
-    showSourceCode = "showSourceCode",// 是否显示源码
+    /** 传递给子应用的数据 */
+    data = "data",
+    /** 应用唯一标识符 */
+    id = "id",
+    /** 是否启用缓存模式 */
+    keepAlive = "keepAlive",
+    /** 应用运行模式 */
+    mode = "mode",
+    /** 是否开启 CSS 样式隔离 */
+    scopeCss = "scopeCss",
+    /** 是否开启 JavaScript 隔离 */
+    scopeJs = "scopeJs",
+    /** 是否开启 location 路由隔离 */
+    scopeLocation = "scopeLocation",
+    /** 是否启用 Shadow DOM */
+    setShodowDom = "setShodowDom",
+    /** 是否显示源码 */
+    showSourceCode = "showSourceCode",
+    /** 应用资源 URL */
     url = "url"
 }
 
 type FakeWindow = Window & Record<string, unknown>;
 
 /**
- * 微前端沙箱实现
- * 提供应用间的环境隔离，防止全局变量污染
+ * 微前端沙箱实现类
+ * @description 提供应用间的环境隔离，防止全局变量污染，支持多应用并存运行
  */
 declare class SandBox {
-    app: BaseModel;
+    readonly app: BaseModel;
+    /** 沙箱激活状态标识 */
     private active;
-    private inRawWindowKeySet;
+    /** 记录在原始 window 上新增的属性键集合 */
+    private readonly inRawWindowKeySet;
+    /** 重置文档和 body 事件的函数 */
     private resetDocumentAndBodyEvent?;
-    private resetWindowFunction;
-    private sameRawWindowKeySet;
-    fakeWindow: FakeWindow & IInjectWindowAttrs;
+    /** 重置 window 函数的方法 */
+    private readonly resetWindowFunction;
+    /** 记录与原始 window 相同的属性键集合 */
+    private readonly sameRawWindowKeySet;
+    /** 伪造的 window 对象 */
+    readonly fakeWindow: FakeWindow & IInjectWindowAttrs;
+    /** 代理的 document 对象 */
     proxyDocument: any;
-    proxyWindow: WindowProxy & IInjectWindowAttrs;
+    /** 代理的 window 对象 */
+    readonly proxyWindow: WindowProxy & IInjectWindowAttrs;
+    /** 原始 document 对象 */
     rawDocument: Record<string, any>;
-    rawWindow: Window;
-    windowSymbolKey: keyof Window;
+    /** 原始 window 对象 */
+    readonly rawWindow: Window;
+    /** 在 window 上的唯一标识键 */
+    readonly windowSymbolKey: keyof Window;
+    /**
+     * 构造函数
+     * @description 初始化沙箱环境，创建代理对象和隔离机制
+     * @param app - 关联的微应用实例
+     */
     constructor(app: BaseModel);
+    /**
+     * 处理代理对象的 get 操作
+     * @description 统一处理代理对象属性获取的复杂逻辑
+     * @param target - 目标对象
+     * @param key - 属性键
+     * @param rawWindow - 原始 window 对象
+     * @returns unknown - 属性值
+     * @private
+     */
+    private handleProxyGet;
+    /**
+     * 处理代理对象的 set 操作
+     * @description 统一处理代理对象属性设置的复杂逻辑
+     * @param target - 目标对象
+     * @param key - 属性键
+     * @param value - 属性值
+     * @param rawWindow - 原始 window 对象
+     * @returns boolean - 设置是否成功
+     * @private
+     */
+    private handleProxySet;
+    /**
+     * 判断是否应该使用 iframe 的 location
+     * @description 检查是否在 iframe 模式下访问 location 相关属性
+     * @param key - 属性键
+     * @returns boolean - 是否使用 iframe location
+     * @private
+     */
+    private shouldUseIframeLocation;
+    /**
+     * 创建 getComputedStyle 方法的代理
+     * @description 为 getComputedStyle 方法创建安全的代理实现
+     * @param rawWindow - 原始 window 对象
+     * @returns Function - 代理后的 getComputedStyle 方法
+     * @private
+     */
+    private createGetComputedStyleProxy;
+    /**
+     * 判断是否应该在目标对象上设置属性
+     * @description 检查属性设置的逻辑条件
+     * @param target - 目标对象
+     * @param key - 属性键
+     * @param rawWindow - 原始 window 对象
+     * @returns boolean - 是否在目标对象上设置
+     * @private
+     */
+    private shouldSetOnTarget;
+    /**
+     * 在目标对象上设置属性
+     * @description 安全地在目标对象上设置属性，保持描述符特性
+     * @param target - 目标对象
+     * @param key - 属性键
+     * @param value - 属性值
+     * @param rawWindow - 原始 window 对象
+     * @private
+     */
+    private setPropertyOnTarget;
+    /**
+     * 处理白名单属性
+     * @description 处理需要在原始 window 上设置的白名单属性
+     * @param key - 属性键
+     * @param value - 属性值
+     * @param rawWindow - 原始 window 对象
+     * @private
+     */
+    private handleWhiteListProperty;
     /**
      * 激活沙箱
-     * @param data 传递给沙箱的数据
+     * @description 启动沙箱环境，初始化代理对象和事件处理
+     * @param data - 传递给沙箱的数据（可选）
+     * @returns void
      */
     activated(data?: Record<string, unknown>): void;
     /**
-     * 停用沙箱，清理所有副作用
+     * 停用沙箱
+     * @description 关闭沙箱环境，清理所有副作用和修改
+     * @returns void
      */
     deactivated(): void;
 }
@@ -611,45 +782,71 @@ declare global {
     }
     interface Node {
         __BK_WEWEB_APP_KEY__?: string;
-        __KEEP_ALIVE__?: string;
+        __KEEP_ALIVE__?: boolean;
         data?: unknown;
     }
 }
 
 /**
- * 接口定义：样式选项
+ * 资源加载相关类型定义
+ * @description 定义了样式、脚本等资源的配置选项和相关类型
+ */
+/**
+ * 样式资源配置选项接口
+ * @description 定义样式文件的加载配置和属性信息
  */
 interface IStyleOption {
+    /** 样式代码内容 */
     code: string;
+    /** 是否来自 HTML 页面内联样式 */
     fromHtml: boolean;
+    /** 是否为初始样式（可选） */
     initial?: boolean;
+    /** 是否预取样式资源（可选） */
     prefetch?: boolean;
+    /** 是否预加载样式资源（可选） */
     preload?: boolean;
+    /** 样式文件的 URL 地址（可选） */
     url?: string;
 }
+/**
+ * 脚本资源配置选项接口
+ * @description 定义脚本文件的加载配置和属性信息
+ */
 interface IScriptOption {
+    /** 是否为异步加载脚本 */
     async: boolean;
+    /** 脚本代码内容 */
     code: string;
+    /** 是否为延迟执行脚本 */
     defer: boolean;
+    /** 是否从 HTML 页面中提取的脚本 */
     fromHtml: boolean;
+    /** 是否为初始脚本（可选） */
     initial?: boolean;
+    /** 是否为 ES6 模块类型脚本 */
     isModule: boolean;
+    /** 脚本文件的 URL 地址（可选） */
     url?: string;
 }
 
 /**
- * 注入window 属性的接口
+ * 沙箱环境配置类型定义
+ */
+/**
+ * 注入到子应用 window 对象的属性接口
+ * @description 定义了 BK WEWEB 平台注入到子应用环境中的必要属性
  */
 interface IInjectWindowAttrs {
-    /** BK WEWEB平台的应用key */
+    /** BK WEWEB平台的应用唯一标识 */
     __BK_WEWEB_APP_KEY__: string;
-    /** BK WEWEB的附加数据 */
+    /** BK WEWEB的附加数据，可包含配置信息、用户数据等 */
     __BK_WEWEB_DATA__: Record<string, unknown>;
-    /** 标识页面是否由BK WEWEB驱动 */
+    /** 标识页面是否由BK WEWEB驱动的布尔值 */
     __POWERED_BY_BK_WEWEB__: boolean;
-    /** 原始 document 对象 */
+    /** 原始 document 对象的引用 */
     rawDocument: Document;
-    /** 原始 window 对象 */
+    /** 原始 window 对象的引用 */
     rawWindow: Window;
 }
 
@@ -660,8 +857,23 @@ interface IStartOption {
     webComponentTag?: string;
 }
 
+/**
+ * 激活指定应用
+ * @description 激活已失活的应用或挂载新应用，支持 keep-alive 模式的应用状态恢复
+ * @template T - 导出实例的类型
+ * @param appKey - 应用的唯一标识符
+ * @param container - 挂载容器，HTMLElement 或 ShadowRoot
+ * @param callback - 激活完成后的回调函数（可选）
+ * @returns void
+ */
 declare function activated<T>(appKey: string, container: HTMLElement | ShadowRoot, callback?: <M extends BaseModel>(instance: M, exportInstance?: T) => void): void;
 
+/**
+ * 失活指定应用
+ * @description 将指定应用设置为失活状态，根据 keep-alive 配置决定是失活还是卸载
+ * @param appKey - 应用的唯一标识符
+ * @returns void
+ */
 declare function deactivated(appKey: string): void;
 
 type ContainerType = HTMLElement | ShadowRoot;
@@ -763,29 +975,101 @@ declare class MicroInstanceModel implements BaseModel {
     private needsReload;
 }
 
+/**
+ * 根据配置模式加载相应的应用或模块实例
+ * @description 统一的加载入口，根据模式参数决定加载应用还是模块实例
+ * @param props - 基础模型配置参数
+ * @returns Promise<BaseModel> - 返回加载的模型实例
+ */
 declare function load(props: IBaseModelProps): Promise<BaseModel>;
+/**
+ * 加载微应用
+ * @description 加载或获取已存在的微应用实例，并启动应用
+ * @param props - 应用模型配置参数
+ * @returns Promise<MicroAppModel> - 返回微应用模型实例
+ */
 declare function loadApp(props: IAppModelProps): Promise<MicroAppModel>;
+/**
+ * 加载模块实例
+ * @description 加载或获取已存在的模块实例，支持状态监听和异步等待
+ * @param props - 模块实例配置参数
+ * @returns Promise<MicroInstanceModel> - 返回模块实例模型
+ */
 declare function loadInstance(props: IJsModelProps): Promise<MicroInstanceModel>;
 
+/**
+ * 挂载应用到指定容器
+ * @description 将已加载的应用挂载到指定的 DOM 容器或 ShadowRoot 中
+ * @template T - 导出实例的类型
+ * @param appKey - 应用的唯一标识符
+ * @param container - 挂载容器，可以是 HTMLElement 或 ShadowRoot（可选）
+ * @param callback - 挂载完成后的回调函数（可选）
+ * @returns void
+ */
 declare function mount<T>(appKey: string, container?: HTMLElement | ShadowRoot, callback?: <M extends BaseModel>(instance: M, exportInstance?: T) => void): void;
 
+/**
+ * 卸载并删除指定应用
+ * @description 从缓存中完全删除指定的应用实例，释放相关资源
+ * @param url - 应用的 URL 标识符，用于定位要删除的应用
+ * @returns void
+ */
 declare function unload(url: string): void;
 
+/**
+ * 卸载指定应用
+ * @description 卸载指定的应用实例，并在没有活跃应用时重置全局方法
+ * @param appKey - 应用的唯一标识符
+ * @returns void
+ */
 declare function unmount(appKey: string): void;
 
 /**
- * @param options 加载模块的参数
- * @description 预加载实例
+ * 预加载模块实例
+ * @description 在浏览器空闲时预加载指定的模块实例，提前准备资源以提升后续加载性能
+ * @param options - 模块加载配置参数
+ * @param options.isPreLoad - 将被自动设置为 true，标识这是预加载操作
+ * @returns void
+ * @example
+ * ```typescript
+ * preLoadInstance({
+ *   name: 'my-module',
+ *   url: 'https://example.com/module.js'
+ * });
+ * ```
  */
 declare function preLoadInstance(options: IJsModelProps): void;
 /**
- * @param options 加载应用的参数
- * @description 预加载应用
+ * 预加载微应用
+ * @description 在浏览器空闲时预加载指定的微应用，提前准备应用资源以提升后续加载性能
+ * @param options - 应用加载配置参数
+ * @param options.isPreLoad - 将被自动设置为 true，标识这是预加载操作
+ * @returns void
+ * @example
+ * ```typescript
+ * preLoadApp({
+ *   name: 'my-app',
+ *   entry: 'https://example.com/app/'
+ * });
+ * ```
  */
 declare function preLoadApp(options: IAppModelProps): void;
 /**
- * @param sourceList 要预加载的资源列表
- * @description 预加载资源
+ * 预加载全局资源
+ * @description 在浏览器空闲时预加载指定的全局资源列表，包括样式文件、脚本文件等
+ * @param sourceList - 要预加载的资源列表，可以是单个资源或资源数组
+ * @returns void
+ * @example
+ * ```typescript
+ * // 预加载单个资源
+ * preLoadSource('https://example.com/style.css');
+ *
+ * // 预加载多个资源
+ * preLoadSource([
+ *   'https://example.com/style.css',
+ *   'https://example.com/script.js'
+ * ]);
+ * ```
  */
 declare function preLoadSource(sourceList: SourceType): void;