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

package/dist/index.d.mts

@@ -1,7 +1,5 @@
 type ExecuteResult = Comment | HTMLScriptElement | undefined;
-/**
- * Script脚本实例类
- */
+/** Script脚本实例类 */
 declare class Script {
     async: boolean;
     code: string;
@@ -13,29 +11,16 @@ declare class Script {
     scoped: boolean;
     url: string | undefined;
     constructor({ async, code, defer, fromHtml, initial, isModule, url }: IScriptOption);
-    /**
-     * 执行脚本代码
-     * @param app 应用实例
-     * @param needReplaceScriptElement 是否需要替换script标签
-     * @returns 返回执行后的script标签或注释
-     */
+    /** 执行脚本代码 */
     executeCode(app: BaseModel, needReplaceScriptElement?: boolean): Promise<ExecuteResult>;
-    /**
-     * 内存脚本执行
-     */
+    /** 内存脚本执行 */
     executeMemoryScript(app: BaseModel, scopedCode: string): void;
-    /**
-     * 脚本标签执行
-     */
+    /** 脚本标签执行 */
     executeSourceScript(scriptElement: HTMLScriptElement, scopedCode: string): void;
-    /**
-     * 获取脚本内容
-     */
+    /** 获取脚本内容 */
     getCode(app?: BaseModel): Promise<string>;
     setCode(code: string): void;
-    /**
-     * 转换脚本内容
-     */
+    /** 转换脚本内容 */
     transformCode(app: BaseModel): string;
 }
 
@@ -131,19 +116,86 @@ 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 - 要缓存的应用实例
+     */
+    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标识
+     */
+    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 - 脚本实例
+     */
     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 - 样式实例
+     */
     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 +226,132 @@ 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;
+    /** 初始化沙箱环境 */
     constructor(app: BaseModel);
+    /** 处理代理对象的 get 操作 */
+    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 - 传递给沙箱的数据（可选）
      */
     activated(data?: Record<string, unknown>): void;
     /**
-     * 停用沙箱，清理所有副作用
+     * 停用沙箱
+     * @description 关闭沙箱环境，清理所有副作用和修改
      */
     deactivated(): void;
 }
@@ -221,14 +359,10 @@ declare class SandBox {
 type SourceFuncType = () => Promise<string[]>;
 type SourceType = SourceFuncType | string[];
 
-type ContainerType$2 = HTMLElement | ShadowRoot;
-type AppCallback = (app: BaseModel) => void;
-/**
- * BK-WEWEB 微微应用模式类
- */
+/** BK-WEWEB 微应用模式类 */
 declare class MicroAppModel implements BaseModel {
     private state;
-    container?: ContainerType$2;
+    container?: ContainerType;
     data: Record<string, unknown>;
     iframe: HTMLIFrameElement | null;
     initSource: SourceType;
@@ -245,97 +379,48 @@ declare class MicroAppModel implements BaseModel {
     source?: EntrySource;
     url: string;
     constructor(props: IAppModelProps);
-    /**
-     * 激活微应用
-     */
-    activated(container: ContainerType$2, callback?: AppCallback): void;
-    /**
-     * 创建隔离iframe
-     */
+    /** 激活微应用 */
+    activated<T = unknown>(container: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 创建隔离iframe */
     createIframe(): Promise<HTMLIFrameElement>;
-    /**
-     * 停用微应用
-     */
+    /** 停用微应用 */
     deactivated(): void;
-    /**
-     * 初始化ShadowRoot容器
-     */
+    /** 初始化ShadowRoot容器 */
     initShadowRootContainer(): void;
-    /**
-     * 挂载微应用
-     */
-    mount(container?: ContainerType$2, callback?: AppCallback): void;
-    /**
-     * 错误处理
-     */
+    /** 挂载微应用 */
+    mount<T = unknown>(container?: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 错误处理 */
     onError(): void;
-    /**
-     * 挂载处理
-     */
+    /** 挂载处理 */
     onMount(): void;
-    /**
-     * 注册运行中的微应用
-     */
+    /** 注册运行中的微应用 */
     registerRunningApp(): void;
-    /**
-     * 启动微应用
-     */
+    /** 启动微应用 */
     start(): Promise<void>;
-    /**
-     * 卸载微应用
-     */
+    /** 卸载微应用 */
     unmount(needDestroy?: boolean): void;
-    /**
-     * 获取微应用缓存键
-     */
     get appCacheKey(): string;
-    /**
-     * 获取微应用状态
-     */
     get status(): ValueOfAppState;
-    /**
-     * 设置微应用状态
-     */
     set status(value: ValueOfAppState);
-    /**
-     * 初始化沙盒
-     */
+    /** 初始化沙盒 */
     private initializeSandBox;
-    /**
-     * 设置容器属性
-     */
+    /** 设置容器属性 */
     private setContainerAttribute;
-    /**
-     * 转移节点到新容器
-     */
+    /** 转移节点到新容器 */
     private transferNodes;
-    /**
-     * 设置节点属性
-     */
+    /** 设置节点属性 */
     private setupNodeProperties;
-    /**
-     * 创建iframe元素
-     */
+    /** 创建iframe元素 */
     private createIframeElement;
-    /**
-     * 构建iframe的src地址
-     */
+    /** 构建iframe源地址 */
     private buildIframeSrc;
-    /**
-     * 检查是否为Chrome用户代理
-     */
+    /** 检查是否为Chrome浏览器 */
     private isChromeUserAgent;
-    /**
-     * 处理非Chrome浏览器的iframe
-     */
+    /** 处理非Chrome浏览器iframe */
     private handleNonChromeIframe;
-    /**
-     * 渲染微应用内容
-     */
+    /** 渲染应用内容 */
     private renderAppContent;
-    /**
-     * 检查是否需要重新加载
-     */
+    /** 检查是否需要重新加载 */
     private needsReload;
 }
 
@@ -351,40 +436,26 @@ declare class EntrySource {
     scripts: Map<string, Script>;
     styles: Map<string, Style>;
     constructor(url: string);
-    /**
-     * 收集链接元素
-     */
+    /** 收集链接元素 */
     collectLink: (link: HTMLLinkElement, parent: Node, needReplaceElement?: boolean) => {
         replace: Comment | Element;
         style?: Style;
     };
-    /**
-     * 收集脚本元素
-     */
+    /** 收集脚本元素 */
     collectScript: (script: HTMLScriptElement, parent: Node, needReplaceElement?: boolean) => CollectResult | undefined;
-    /**
-     * 收集样式和脚本
-     */
+    /** 收集样式和脚本 */
     collectScriptAndStyle: (parent: HTMLElement) => void;
     getScript: (url: string) => Script | undefined;
     getStyle: (urlOrCode: string) => Style | undefined;
-    /**
-     * 导入入口资源
-     */
+    /** html entry */
     importEntry(app: BaseModel): Promise<void>;
-    /**
-     * 导入HTML入口
-     */
+    /** 微应用入口 */
     importHtmlEntry(app: MicroAppModel): Promise<void>;
-    /**
-     * 导入实例入口
-     */
+    /** 微模块入口 */
     importInstanceEntry(app: BaseModel): Promise<void>;
     setScript: (url: string, script: IScriptOption | Script) => void;
     setStyle: (url: string, style: Style) => void;
-    /**
-     * 处理样式表链接
-     */
+    /** 处理样式表链接 */
     private handleStylesheetLink;
     /**
      * 处理图标链接
@@ -455,82 +526,74 @@ type FetchOptions = Record<string, unknown>;
  */
 declare const fetchSource: (url: string, options?: FetchOptions, app?: BaseModel) => Promise<string>;
 
-/**
- * WEWEB模式枚举
- */
+/** WEWEB运行模式 */
 declare enum WewebMode {
-    /** 应用模式 */
+    /** 微应用模式 */
     APP = "app",
     /** 配置模式 */
     CONFIG = "config",
-    /** 实例模式 */
+    /** 微模块模式 */
     INSTANCE = "js"
 }
-type ContainerType$1 = HTMLElement | ShadowRoot;
+/** 容器类型 */
+type ContainerType = HTMLElement | ShadowRoot;
+/** 通用回调函数类型 */
 type CallbackFunction<T = unknown> = (instance: BaseModel, exportInstance?: T) => void;
-/**
- * 基础模型属性接口
- */
+/** 基础模型属性接口 */
 interface IBaseModelProps {
-    /** entry模式：js | config | html，默认html */
+    /** 运行模式 */
     [WewebCustomAttrs.mode]?: WewebMode;
-    /** URL地址（必选） */
+    /** 应用URL */
     [WewebCustomAttrs.url]: string;
     /** 应用ID */
     id?: string | null;
     /** 是否预加载 */
     isPreLoad?: boolean;
 }
-/**
- * 微应用模式属性配置接口
- */
+/** 微应用模式属性配置 */
 interface IAppModelProps extends IBaseModelProps {
-    /** 传递给子应用的数据，默认保存 */
+    /** 传递给子应用的数据 */
     [WewebCustomAttrs.data]?: Record<string, unknown>;
     /** 是否缓存DOM */
     [WewebCustomAttrs.keepAlive]?: boolean;
-    /** 是否启用样式隔离，默认隔离 */
+    /** 是否启用样式隔离 */
     [WewebCustomAttrs.scopeCss]?: boolean;
-    /** 是否使用沙盒隔离，默认隔离 */
+    /** 是否使用沙盒隔离 */
     [WewebCustomAttrs.scopeJs]?: boolean;
     /** 是否共享主应用路由 */
     [WewebCustomAttrs.scopeLocation]?: boolean;
-    /** 是否使用shadowDom */
+    /** 是否使用 ShadowDOM */
     [WewebCustomAttrs.setShodowDom]?: boolean;
-    /** 是否在dom上显示源码，默认不显示内存执行 */
+    /** 是否显示源码 */
     [WewebCustomAttrs.showSourceCode]?: boolean;
     /** 容器元素 */
-    container?: ContainerType$1 | null;
-    /** 初始化资源，如 ['http://www.hostname.com/a.js', 'http://www.hostname.com/b.css'] */
+    container?: ContainerType | null;
+    /** 初始化资源 */
     initSource?: SourceType;
 }
-/**
- * 微模块模式属性配置接口
- */
+/** 微模块模式属性配置 */
 interface IJsModelProps extends IBaseModelProps {
-    /** 传递给实例render方法的数据 */
+    /** 传递给模块的数据 */
     [WewebCustomAttrs.data]?: Record<string, unknown>;
-    /** 是否在dom上显示源码，默认显示 */
+    /** 是否显示源码 */
     [WewebCustomAttrs.showSourceCode]?: boolean;
     /** 容器元素 */
-    container?: ContainerType$1 | null;
-    /** 初始化资源，如 ['http://www.hostname.com/a.js', 'http://www.hostname.com/b.css'] */
+    container?: ContainerType | null;
+    /** 初始化资源 */
     initSource?: SourceType;
     /** 是否缓存DOM */
     keepAlive?: boolean;
-    /** 是否启用样式隔离，默认隔离 */
+    /** 是否启用样式隔离 */
     scopeCss?: boolean;
-    /** 是否使用沙盒隔离，默认不隔离 */
+    /** 是否使用沙盒隔离 */
     scopeJs?: boolean;
 }
-/**
- * 基础模型接口
- */
+/** 基础模型接口 */
 interface BaseModel {
     /** 应用缓存键 */
     readonly appCacheKey: string;
     /** 容器元素 */
-    container?: ContainerType$1;
+    container?: ContainerType;
     /** 初始化资源 */
     initSource?: SourceType;
     /** 是否为模块应用 */
@@ -543,7 +606,7 @@ interface BaseModel {
     name: string;
     /** 沙盒实例 */
     sandBox?: SandBox;
-    /** 是否启用样式隔离，默认隔离 */
+    /** 是否启用样式隔离 */
     scopeCss?: boolean;
     /** 是否使用JS隔离 */
     scopeJs: boolean;
@@ -555,51 +618,25 @@ interface BaseModel {
     url: string;
     /** 获取资源的函数 */
     fetchSource?: typeof fetchSource;
-    /**
-     * 激活应用
-     * @param container 容器元素
-     * @param callback 回调函数
-     */
-    activated<T = unknown>(container: ContainerType$1, callback?: CallbackFunction<T>): void;
-    /**
-     * 停用应用
-     */
+    /** 激活应用 */
+    activated<T = unknown>(container: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 停用应用 */
     deactivated(): void;
-    /**
-     * 挂载应用
-     * @param container 容器元素
-     * @param callback 回调函数
-     */
-    mount<T = unknown>(container?: ContainerType$1, callback?: CallbackFunction<T>): void;
-    /**
-     * 错误处理
-     */
+    /** 挂载应用 */
+    mount<T = unknown>(container?: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 错误处理 */
     onError(): void;
-    /**
-     * 挂载处理
-     */
+    /** 挂载处理 */
     onMount(): void;
-    /**
-     * 注册运行中的应用
-     */
+    /** 注册运行中的应用 */
     registerRunningApp(): void;
-    /**
-     * 启动应用
-     */
+    /** 启动应用 */
     start(): Promise<void>;
-    /**
-     * 卸载应用
-     * @param needDestroy 是否需要销毁
-     */
+    /** 卸载应用 */
     unmount(needDestroy?: boolean): void;
-    /**
-     * 获取应用状态
-     */
+    /** 获取应用状态 */
     get status(): ValueOfAppState;
-    /**
-     * 设置应用状态
-     * @param value 状态值
-     */
+    /** 设置应用状态 */
     set status(value: ValueOfAppState);
 }
 
@@ -617,39 +654,65 @@ declare global {
 }
 
 /**
- * 接口定义：样式选项
+ * 资源加载相关类型定义
+ * @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_DATA__: Record<string, unknown>;
     /** 标识页面是否由BK WEWEB驱动 */
     __POWERED_BY_BK_WEWEB__: boolean;
-    /** 原始 document 对象 */
+    /** 原始 document 对象的引用 */
     rawDocument: Document;
-    /** 原始 window 对象 */
+    /** 原始 window 对象的引用 */
     rawWindow: Window;
 }
 
@@ -660,16 +723,23 @@ interface IStartOption {
     webComponentTag?: string;
 }
 
+/**
+ * 激活指定应用
+ * @description 激活已失活的应用或挂载新应用，支持 keep-alive 模式的应用状态恢复
+ * @template T - 导出实例的类型
+ * @param appKey - 应用的唯一标识符
+ * @param container - 挂载容器，HTMLElement 或 ShadowRoot
+ * @param callback - 激活完成后的回调函数（可选）
+ */
 declare function activated<T>(appKey: string, container: HTMLElement | ShadowRoot, callback?: <M extends BaseModel>(instance: M, exportInstance?: T) => void): void;
 
-declare function deactivated(appKey: string): void;
-
-type ContainerType = HTMLElement | ShadowRoot;
-type InstanceCallback<T = unknown> = (instance: BaseModel, exportInstance?: T) => void;
-type MountCallback<T = unknown> = (instance: MicroInstanceModel, exportInstance: T) => void;
 /**
- * BK-WEWEB 微模块模式类
+ * deactivated 指定应用
+ * @description 将指定应用设置为失活状态，根据 keep-alive 配置决定
  */
+declare function deactivated(appKey: string): void;
+
+/** BK-WEWEB 微模块模式类 */
 declare class MicroInstanceModel implements BaseModel {
     private state;
     appCacheKey: string;
@@ -689,103 +759,133 @@ declare class MicroInstanceModel implements BaseModel {
     constructor(props: IJsModelProps & {
         fetchSource?: typeof fetchSource;
     });
-    /**
-     * 激活微模块
-     */
-    activated<T = unknown>(container: ContainerType, callback?: InstanceCallback<T>): void;
-    /**
-     * 停用微模块
-     */
+    /** 激活微模块 */
+    activated<T = unknown>(container: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 停用微模块 */
     deactivated(): void;
-    /**
-     * 挂载微模块
-     */
-    mount<T = unknown>(container?: ContainerType, callback?: MountCallback<T>): void;
-    /**
-     * 错误处理
-     */
+    /** 挂载微模块 */
+    mount<T = unknown>(container?: ContainerType, callback?: CallbackFunction<T>): void;
+    /** 错误处理 */
     onError(): void;
-    /**
-     * 挂载处理
-     */
+    /** 挂载处理 */
     onMount(): void;
-    /**
-     * 注册运行中的应用
-     */
+    /** 注册运行中的应用 */
     registerRunningApp(): void;
-    /**
-     * 启动微模块
-     */
+    /** 启动微模块 */
     start(): Promise<void>;
-    /**
-     * 卸载微模块
-     */
+    /** 卸载微模块 */
     unmount(needDestroy?: boolean): void;
-    /**
-     * 设置微模块 状态
-     */
     set status(value: ValueOfAppState);
-    /**
-     * 获取微模块 状态
-     */
     get status(): ValueOfAppState;
-    /**
-     * 初始化沙盒
-     */
+    /** 初始化沙盒 */
     private initializeSandBox;
-    /**
-     * 设置容器属性
-     */
+    /** 设置容器属性 */
     private setContainerAttribute;
-    /**
-     * 转移节点到新容器
-     */
+    /** 转移节点到新容器 */
     private transferNodes;
-    /**
-     * 设置容器
-     */
+    /** 设置容器 */
     private setupContainer;
-    /**
-     * 创建微模块 包装器
-     */
+    /** 执行样式 */
+    private executeStyles;
+    /** 创建实例包装器 */
     private createInstanceWrapper;
-    /**
-     * 渲染微模块
-     */
+    /** 渲染实例 */
     private renderInstance;
-    /**
-     * 获取脚本信息
-     */
+    /** 获取脚本信息 */
     private getScriptInfo;
-    /**
-     * 检查是否需要重新加载
-     */
+    /** 检查是否需要重新加载 */
     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 - 挂载完成后的回调函数（可选）
+ */
 declare function mount<T>(appKey: string, container?: HTMLElement | ShadowRoot, callback?: <M extends BaseModel>(instance: M, exportInstance?: T) => void): void;
 
+/**
+ * 卸载并删除指定应用
+ * @description 从缓存中完全删除指定的应用实例，释放相关资源
+ * @param url - 应用的 URL 标识符，用于定位要删除的应用
+ */
 declare function unload(url: string): void;
 
+/**
+ * 卸载指定应用
+ * @description 卸载指定的应用实例，并在没有活跃应用时重置全局方法
+ * @param appKey - 应用的唯一标识符
+ */
 declare function unmount(appKey: string): void;
 
 /**
- * @param options 加载模块的参数
- * @description 预加载实例
+ * 预加载模块实例
+ * @description 在浏览器空闲时预加载指定的模块实例，提前准备资源以提升后续加载性能
+ * @param options - 模块加载配置参数
+ * @param options.isPreLoad - 将被自动设置为 true，标识这是预加载操作
+ * @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，标识这是预加载操作
+ * @example
+ * ```typescript
+ * preLoadApp({
+ *   name: 'my-app',
+ *   entry: 'https://example.com/app/'
+ * });
+ * ```
  */
 declare function preLoadApp(options: IAppModelProps): void;
 /**
- * @param sourceList 要预加载的资源列表
- * @description 预加载资源
+ * 预加载全局资源
+ * @description 在浏览器空闲时预加载指定的全局资源列表，包括样式文件、脚本文件等
+ * @param sourceList - 要预加载的资源列表，可以是单个资源或资源数组
+ * @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;
 
@@ -793,7 +893,9 @@ declare class WeWeb {
     fetchSource?: FetchSourceType;
     webComponentTag: string;
     constructor();
+    /** 设置自定义DOM标签名 */
     setWebComponentTag(): void;
+    /** 启动WeWeb */
     start(option?: IStartOption): void;
 }
 declare const weWeb: WeWeb;