@vvfx/sdk 0.2.2-beta.11 → 0.2.2-beta.13

package/dist/sdk.d.ts

@@ -527,6 +527,30 @@ export declare class SDK {
      * @returns 是否成功触发刷新
      */
     refreshCardHTML(id: string): boolean;
+    /**
+     * @description 获取指定 HTML 卡片当前 iframe 的 window。
+     * @description 仅 inline/document 或自行渲染 iframe 的 DOM 内容会返回 window。
+     * @param id 卡片元素 ID
+     * @returns HTML iframe window
+     */
+    getHtmlCardWindow(id: string): Window | null | undefined;
+    /**
+     * @description 向指定 HTML 卡片发送增量 patch。
+     * @description 当卡片内容配置了 CardHTMLPatchHandler 时，可用于局部更新 HTML，而不必整卡 refresh。
+     * @param id 卡片元素 ID
+     * @param patch patch 负载，由卡片内容自己的 patch handler 解释
+     * @returns 是否被 patch handler 处理
+     */
+    patchCardHTML(id: string, patch: unknown): boolean;
+    /**
+     * @description 向指定 HTML 卡片 iframe 派发事件。
+     * @description 通过 postMessage 投递事件，跨源/同源行为一致，消息 source 为 vvfx-card-html-event。
+     * @param id 卡片元素 ID
+     * @param type 事件名称
+     * @param detail 事件 detail
+     * @returns 是否成功派发或投递
+     */
+    dispatchHtmlCardEvent(id: string, type: string, detail?: unknown): boolean;
     /**
      * @description 创建卡片元素
      * @description 底层以透明 SpriteItem 形式渲染，支持 cardType 属性

package/dist/types.d.ts

@@ -82,6 +82,42 @@ export type CardHTMLContentCleanup = (container: HTMLElement) => void;
  * @description Card HTML 覆盖层 DOM 渲染函数。SDK 会传入 overlay 容器；卸载逻辑请使用 content.cleanup。
  */
 export type CardHTMLDOMRenderer = (container: HTMLElement) => void;
+export type CardHTMLPatchContext = {
+    /**
+     * @description 当前卡片元素 ID。
+     */
+    id: string;
+    /**
+     * @description 当前 HTML 覆盖层配置。
+     */
+    html: CardHTML;
+    /**
+     * @description 当前 HTML 内容配置。
+     */
+    content: CardHTMLContent;
+    /**
+     * @description 当前内容挂载容器；未完成挂载时可能不存在。
+     */
+    container?: HTMLElement;
+    /**
+     * @description 当前内容 iframe window；host DOM 内容或尚未完成 iframe 加载时可能不存在。
+     */
+    contentWindow?: Window | null;
+    /**
+     * @description 重新解析并挂载当前卡片 HTML。
+     */
+    refresh: () => void;
+};
+export type CardHTMLPatchHandler = (patch: unknown, context: CardHTMLPatchContext) => boolean | undefined;
+/**
+ * @description SDK#dispatchHtmlCardEvent 通过 postMessage 投递给 HTML iframe 的消息结构。
+ */
+export type CardHTMLWindowEventMessage = {
+    source: 'vvfx-card-html-event';
+    type: string;
+    detail?: unknown;
+    payload?: unknown;
+};
 /**
  * @description Card HTML 单文件字符串内容。SDK 会通过 iframe srcdoc 渲染。
  */
@@ -94,6 +130,10 @@ export type CardHTMLInlineContent = {
      * @description HTML 字符串内容
      */
     html: string;
+    /**
+     * @description 增量 patch 处理器。可用于将运行时事件派发给 iframe，或直接更新外部状态后触发刷新；返回 false 表示未处理，返回 true 或无返回值表示已接收。
+     */
+    patch?: CardHTMLPatchHandler;
     /**
      * @description 内容卸载时调用的清理函数；SDK 会传入当前内容挂载容器。
      */
@@ -115,6 +155,10 @@ export type CardHTMLDOMRendererContent = {
      * @description DOM 渲染函数
      */
     render: CardHTMLDOMRenderer;
+    /**
+     * @description 增量 patch 处理器。适合 React/Vue/原生 DOM 内容接收局部更新；返回 false 表示未处理，返回 true 或无返回值表示已接收。
+     */
+    patch?: CardHTMLPatchHandler;
     /**
      * @description 内容卸载时调用的清理函数；SDK 会传入 render 接收到的同一个容器。
      */
@@ -169,6 +213,10 @@ export type CardHTMLDocumentContent = {
      * @description iframe 消息回调。仅接收来自当前 iframe 且 source 为 vvfx-card-html 的消息。
      */
     onMessage?: (message: CardHTMLDocumentMessage) => void;
+    /**
+     * @description 增量 patch 处理器。可结合 contentWindow.postMessage 投递给文档运行时；返回 false 表示未处理，返回 true 或无返回值表示已接收。
+     */
+    patch?: CardHTMLPatchHandler;
     /**
      * @description 内容卸载时调用的清理函数；SDK 会传入当前内容挂载容器。
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vvfx/sdk",
   "description": "TODO",
-  "version": "0.2.2-beta.11",
+  "version": "0.2.2-beta.13",
   "main": "./dist/index.mjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",