@vvfx/sdk 0.2.2-beta.16 → 0.2.2-beta.17

package/dist/config.d.ts

@@ -4,6 +4,7 @@ import type { CardHTML } from './types';
 import type { CardItem } from './sdk-item/card-item';
 export type SDKMode = 'editor' | 'template';
 export type CardTypeHTMLResolver = (item: CardItem) => CardHTML | undefined;
+export type CardAutoHeightAnchor = 'top' | 'center';
 /**
  * @description SDK功能配置
  */
@@ -147,6 +148,10 @@ export type CardTypeConfig = {
      * @description 是否根据 HTML 挂载内容的自然高度自动更新卡片高度
      */
     autoHeight?: boolean;
+    /**
+     * @description autoHeight 更新卡片高度时的锚点。top 保持上边缘不动，center 保持中心点不动。未配置时默认 top。
+     */
+    autoHeightAnchor?: CardAutoHeightAnchor;
     /**
      * @description HTML 内容是否跟随卡片 scale 缩放，关闭后 HTML 按最终显示尺寸重新布局
      */

package/dist/html-overlay/anchor-navigation-runtime.d.ts

@@ -0,0 +1 @@
+export declare function withCardHTMLAnchorNavigationGuard(html: string, allowAnchorNavigation?: boolean): string;

package/dist/html-overlay/manager.d.ts

@@ -1,6 +1,6 @@
 import type { Box2 } from '../math';
 import { type SnapdomOptions } from '@zumer/snapdom';
-import type { CardTypeConfig } from '../config';
+import type { CardAutoHeightAnchor, CardTypeConfig } from '../config';
 import type { EventEmitter } from '../shared';
 import type { SDKEvents } from '../sdk';
 import { type SDKItem } from '../sdk-item';
@@ -11,6 +11,10 @@ type CardRasterizeOptions = {
     pixelRatio?: number;
     snapdomOptions?: SnapdomOptions;
 };
+type SetCardItemHeightOptions = {
+    anchor: CardAutoHeightAnchor;
+    previousHeight: number;
+};
 type HTMLOverlayManagerOptions = {
     container: HTMLElement;
     emitter: EventEmitter<SDKEvents>;
@@ -25,7 +29,7 @@ type HTMLOverlayManagerOptions = {
         translation: [number, number];
     }) => void;
     viewportFit: (box: Box2) => void;
-    setCardItemHeight: (id: string, height: number) => void;
+    setCardItemHeight: (id: string, height: number, options: SetCardItemHeightOptions) => void;
     getSelectedItemIds: () => string[];
     getPreSelectedItemId: () => string | undefined;
     getSelectionEdgeStyle: () => {
@@ -55,6 +59,9 @@ export declare class HTMLOverlayManager {
     dispose(): void;
     scheduleRender(): void;
     invalidateCardHTML(id: string): void;
+    getHtmlCardWindow(id: string): Window | null | undefined;
+    patchCardHTML(id: string, patch: unknown): boolean;
+    dispatchHtmlCardEvent(id: string, type: string, detail?: unknown): boolean;
     rasterizeCard(id: string, options: CardRasterizeOptions): Promise<string | undefined>;
     private initEvents;
     private initDOMEvents;
@@ -106,8 +113,10 @@ export declare class HTMLOverlayManager {
     private getEditingFitZoom;
     private isEventInsideOverlay;
     private renderOverlayHTML;
+    private createPatchContext;
     private observeContentInteractionZones;
     private applyHTMLRootConfig;
+    private makeSelectionOverlayTransparent;
     private renderOverlayContent;
     private chainCleanups;
     private cleanupOverlayContent;
@@ -122,6 +131,7 @@ export declare class HTMLOverlayManager {
     private getChildrenNaturalHeight;
     private cleanupAutoHeight;
     private applyAutoHeight;
+    private getAutoHeightAnchor;
     private getAutoHeightItemHeight;
     private isAutoHeightMessage;
     private isAutoHeightEnabled;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { SDKOptions, SDKInputParam, PageData, PageProperty, ViewProperty, ActiveData, ViewParam, BaseItemProperty, SpriteItemProperty, TextItemProperty, VideoItemProperty, GeneratorItemProperty, FrameItemProperty, FrameLayoutMode, SpriteCreateInfo, TextCreateInfo, GroupCreateInfo, VideoCreateInfo, GeneratorCreateInfo, EffectsCreateInfo, FrameCreateInfo, CardCreateInfo, CardItemProperty, CardItemTransformInfo, CardHTML, CardHTMLContent, CardHTMLInlineContent, CardHTMLDOMRendererContent, CardHTMLDocumentContent, CardHTMLDocumentMessage, CardHTMLShellContent, CardHTMLShellRenderer, CardHTMLShellRendererContext, CardHTMLShellRendererResult, CardHTMLDOMRenderer, CardHTMLContentCleanup, CardHTMLRenderCleanup, CardHTMLRootConfig, CardHTMLRootStyle, ItemCreateInfo, } from './types';
-export type { SDKConfig, SDKMode, CardTypeConfig, CardConfig, CardTypeHTMLResolver, } from './config';
+export type { SDKOptions, SDKInputParam, PageData, PageProperty, ViewProperty, ActiveData, ViewParam, BaseItemProperty, SpriteItemProperty, TextItemProperty, VideoItemProperty, GeneratorItemProperty, FrameItemProperty, FrameLayoutMode, SpriteCreateInfo, TextCreateInfo, GroupCreateInfo, VideoCreateInfo, GeneratorCreateInfo, EffectsCreateInfo, FrameCreateInfo, CardCreateInfo, CardItemProperty, CardItemTransformInfo, CardHTML, CardHTMLContent, CardHTMLInlineContent, CardHTMLDOMRendererContent, CardHTMLDocumentContent, CardHTMLDocumentMessage, CardHTMLShellContent, CardHTMLShellRenderer, CardHTMLShellRendererContext, CardHTMLShellRendererResult, CardHTMLDOMRenderer, CardHTMLContentCleanup, CardHTMLRenderCleanup, CardHTMLPatchContext, CardHTMLPatchHandler, CardHTMLWindowEventMessage, CardHTMLRootConfig, CardHTMLRootStyle, ItemCreateInfo, } from './types';
+export type { SDKConfig, SDKMode, CardTypeConfig, CardConfig, CardAutoHeightAnchor, CardTypeHTMLResolver, } from './config';
 export type { SDKItem } from './sdk-item';
 export { BaseItem, SpriteItem, TextItem, VideoItem, GroupItem, GeneratorItem, EffectsItem, FrameItem, CardItem, isBaseItem, isSpriteItem, isTextItem, isVideoItem, isGroupItem, isGeneratorItem, isEffectsItem, isFrameItem, isCardItem, SDKItemType, } from './sdk-item';
 export type { SDKItemOptions, SpriteItemOptions, TextItemOptions, VideoItemOptions, GroupItemOptions, GeneratorItemOptions, EffectsItemOptions, FrameItemOptions, CardItemOptions, } from './sdk-item';

package/dist/index.js

@@ -3,7 +3,7 @@
  * Description: TODO
  * Author: Ant Group CO., Ltd.
  * Contributors: 赤芍,何即,不择,意绮
- * Version: v0.2.2-beta.16
+ * Version: v0.2.2-beta.17
  */
 
 import * as EFFECTS from '@galacean/effects';
@@ -91691,6 +91691,17 @@ function withCardHTMLViewportStyle(html) {
     return "<!doctype html><html><head>" + viewportStyle + "</head><body>" + html + "</body></html>";
 }
 
+function withCardHTMLAnchorNavigationGuard(html, allowAnchorNavigation) {
+    if (allowAnchorNavigation === true) {
+        return html;
+    }
+    var script = "\n<script data-vvfx-card-html-anchor-navigation-guard>\n(() => {\n  document.addEventListener('click', event => {\n    const target = event.target;\n    if (!(target instanceof Element)) {\n      return;\n    }\n\n    const anchor = target.closest('a[href]');\n    if (!anchor) {\n      return;\n    }\n\n    event.preventDefault();\n  }, true);\n})();\n</script>";
+    if (/<\/body>/i.test(html)) {
+        return html.replace(/<\/body>/i, "" + script + "</body>");
+    }
+    return "" + html + script;
+}
+
 function renderDocumentContent(overlay, content, options) {
     var _files_get;
     var iframe = document.createElement('iframe');
@@ -91709,7 +91720,7 @@ function renderDocumentContent(overlay, content, options) {
         iframe.setAttribute('sandbox', content.sandbox);
     }
     var entryHtml = (_files_get = files.get(entry)) != null ? _files_get : '';
-    iframe.srcdoc = withCardHTMLAutoHeightBridge(withCardHTMLViewportStyle(transformHTMLDocument(entry, entryHtml, createFileUrl)), options == null ? void 0 : options.autoHeightId);
+    iframe.srcdoc = withCardHTMLAutoHeightBridge(withCardHTMLAnchorNavigationGuard(withCardHTMLViewportStyle(transformHTMLDocument(entry, entryHtml, createFileUrl)), content.allowAnchorNavigation), options == null ? void 0 : options.autoHeightId);
     overlay.appendChild(iframe);
     return function() {
         messageCleanup();
@@ -91868,6 +91879,30 @@ var EDITING_VIEWPORT_PADDING = 48;
 var EDITING_VIEWPORT_BOX_SCALE = 1.1;
 var AUTO_HEIGHT_EPSILON = 0.5;
 var CARD_RASTERIZE_READY_TIMEOUT = 3000;
+var CARD_HTML_EVENT_MESSAGE_SOURCE = 'vvfx-card-html-event';
+var requestHTMLOverlayFrame = function requestHTMLOverlayFrame(callback) {
+    if (typeof requestAnimationFrame === 'function') {
+        try {
+            return requestAnimationFrame(callback);
+        } catch (unused) {
+        // Some non-browser test runtimes install a RAF polyfill that depends on window.
+        }
+    }
+    return setTimeout(function() {
+        callback(Date.now());
+    }, 16);
+};
+var cancelHTMLOverlayFrame = function cancelHTMLOverlayFrame(frame) {
+    if (typeof cancelAnimationFrame === 'function') {
+        try {
+            cancelAnimationFrame(frame);
+            return;
+        } catch (unused) {
+        // Fall back to clearTimeout for frames created by requestHTMLOverlayFrame.
+        }
+    }
+    clearTimeout(frame);
+};
 var HTMLOverlayManager = /*#__PURE__*/ function() {
     function HTMLOverlayManager(options) {
         var _this = this;
@@ -91940,7 +91975,7 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
                 return;
             }
             if (_this.contentInteractionFrame !== undefined) {
-                cancelAnimationFrame(_this.contentInteractionFrame);
+                cancelHTMLOverlayFrame(_this.contentInteractionFrame);
                 _this.contentInteractionFrame = undefined;
             }
             _this.pendingContentInteractionEvent = undefined;
@@ -92001,11 +92036,11 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
     _proto.dispose = function dispose() {
         var _this_state_layer;
         if (this.state.updateFrame !== undefined) {
-            cancelAnimationFrame(this.state.updateFrame);
+            cancelHTMLOverlayFrame(this.state.updateFrame);
             this.state.updateFrame = undefined;
         }
         if (this.contentInteractionFrame !== undefined) {
-            cancelAnimationFrame(this.contentInteractionFrame);
+            cancelHTMLOverlayFrame(this.contentInteractionFrame);
             this.contentInteractionFrame = undefined;
         }
         this.pendingContentInteractionEvent = undefined;
@@ -92035,7 +92070,7 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
         });
         this.state.autoHeightCleanups.clear();
         this.state.autoHeightFrames.forEach(function(frame) {
-            cancelAnimationFrame(frame);
+            cancelHTMLOverlayFrame(frame);
         });
         this.state.autoHeightFrames.clear();
         this.eventCleanups.forEach(function(cleanup) {
@@ -92054,9 +92089,9 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
     _proto.scheduleRender = function scheduleRender() {
         var _this = this;
         if (this.state.updateFrame !== undefined) {
-            cancelAnimationFrame(this.state.updateFrame);
+            cancelHTMLOverlayFrame(this.state.updateFrame);
         }
-        this.state.updateFrame = requestAnimationFrame(function() {
+        this.state.updateFrame = requestHTMLOverlayFrame(function() {
             _this.state.updateFrame = undefined;
             _this.render();
         });
@@ -92065,6 +92100,40 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
         this.cleanupOverlayContent(id);
         this.invalidateContentInteractionZones(id);
     };
+    _proto.getHtmlCardWindow = function getHtmlCardWindow(id) {
+        var contentOverlay = this.state.contentElements.get(id);
+        var iframe = contentOverlay == null ? void 0 : contentOverlay.querySelector('iframe');
+        return iframe == null ? void 0 : iframe.contentWindow;
+    };
+    _proto.patchCardHTML = function patchCardHTML(id, patch) {
+        var html = this.state.contents.get(id);
+        if (!html) {
+            return false;
+        }
+        var patchHandler = html.content.patch;
+        if (!patchHandler) {
+            return false;
+        }
+        var context = this.createPatchContext(id, html);
+        return patchHandler(patch, context) !== false;
+    };
+    _proto.dispatchHtmlCardEvent = function dispatchHtmlCardEvent(id, type, detail) {
+        var targetWindow = this.getHtmlCardWindow(id);
+        try {
+            if (!targetWindow || typeof targetWindow.postMessage !== 'function') {
+                return false;
+            }
+            targetWindow.postMessage({
+                detail: detail,
+                payload: detail,
+                source: CARD_HTML_EVENT_MESSAGE_SOURCE,
+                type: type
+            }, '*');
+            return true;
+        } catch (unused) {
+            return false;
+        }
+    };
     _proto.rasterizeCard = function rasterizeCard(id, options) {
         return _async_to_generator(function() {
             var contentOverlay, capture, _ref, _options_pixelRatio, image, error;
@@ -92072,7 +92141,7 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
                 switch(_state.label){
                     case 0:
                         if (this.state.updateFrame !== undefined) {
-                            cancelAnimationFrame(this.state.updateFrame);
+                            cancelHTMLOverlayFrame(this.state.updateFrame);
                             this.state.updateFrame = undefined;
                         }
                         this.render();
@@ -92239,13 +92308,10 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
             var overlay = _this.getOrCreateOverlay(item.id, parentOverlay, elements);
             var contentOverlay = _this.getOrCreateContentOverlay(item.id, overlay);
             var selectionOverlay = _this.getOrCreateSelectionOverlay(item.id, selectionLayer);
-            if (!_this.state.contents.has(item.id)) {
-                _this.renderOverlayHTML(item.id, contentOverlay, html);
-            }
-            _this.applyHTMLRootConfig(overlay, html);
             var offsetX = frameBox && !frameBox.isEmpty() ? frameBox.min.x : 0;
             var offsetY = frameBox && !frameBox.isEmpty() ? frameBox.min.y : 0;
             var boxStyle = getCardOverlayBoxStyle(itemBox, item.property.width, item.property.height, offsetX, offsetY, _this.isAutoScaleEnabled(item));
+            _this.applyHTMLRootConfig(overlay, html);
             overlay.style.left = boxStyle.left;
             overlay.style.top = boxStyle.top;
             overlay.style.width = boxStyle.width;
@@ -92260,8 +92326,12 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
             selectionOverlay.style.transform = selectionBoxStyle.transform;
             selectionOverlay.style.transformOrigin = '0 0';
             _this.applyHTMLRootConfig(selectionOverlay, html);
+            _this.makeSelectionOverlayTransparent(selectionOverlay);
             _this.syncOverlaySelection(item.id, overlay, selectionOverlay);
             _this.syncContentScale(item.id, boxStyle.contentWidth, boxStyle.contentHeight);
+            if (!_this.state.contents.has(item.id)) {
+                _this.renderOverlayHTML(item.id, contentOverlay, html);
+            }
             _this.syncAutoHeight(item.id, _this.isAutoHeightEnabled(item));
             _this.syncContentInteraction(item.id);
         });
@@ -92501,14 +92571,20 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
         if (this.contentInteractionFrame !== undefined) {
             return;
         }
-        this.contentInteractionFrame = requestAnimationFrame(function() {
-            _this.contentInteractionFrame = undefined;
-            var pendingEvent = _this.pendingContentInteractionEvent;
-            _this.pendingContentInteractionEvent = undefined;
-            if (pendingEvent) {
-                _this.syncActiveContentInteraction(pendingEvent);
-            }
-        });
+        try {
+            this.contentInteractionFrame = requestAnimationFrame(function() {
+                _this.contentInteractionFrame = undefined;
+                var pendingEvent = _this.pendingContentInteractionEvent;
+                _this.pendingContentInteractionEvent = undefined;
+                if (pendingEvent) {
+                    _this.syncActiveContentInteraction(pendingEvent);
+                }
+            });
+        } catch (unused) {
+            this.contentInteractionFrame = undefined;
+            this.pendingContentInteractionEvent = undefined;
+            this.syncActiveContentInteraction(event);
+        }
     };
     _proto.setActiveContentInteraction = function setActiveContentInteraction(zone) {
         var _this = this;
@@ -92932,6 +93008,20 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
         });
         this.state.contents.set(id, html);
     };
+    _proto.createPatchContext = function createPatchContext(id, html) {
+        var _this = this;
+        return {
+            id: id,
+            html: html,
+            content: html.content,
+            container: this.state.contentMountElements.get(id),
+            contentWindow: this.getHtmlCardWindow(id),
+            refresh: function refresh() {
+                _this.invalidateCardHTML(id);
+                _this.scheduleRender();
+            }
+        };
+    };
     _proto.observeContentInteractionZones = function observeContentInteractionZones(id, contentContainer) {
         var _this = this;
         var _this_state_contentInteractionZoneCleanups_get;
@@ -92991,6 +93081,10 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
             });
         });
     };
+    _proto.makeSelectionOverlayTransparent = function makeSelectionOverlayTransparent(selectionOverlay) {
+        selectionOverlay.style.background = 'transparent';
+        selectionOverlay.style.backgroundColor = 'transparent';
+    };
     _proto.renderOverlayContent = function renderOverlayContent(overlay, content, options) {
         var _this = this;
         switch(content.kind){
@@ -93005,7 +93099,9 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
                     entry: 'index.html',
                     files: {
                         'index.html': content.html
-                    }
+                    },
+                    allowAnchorNavigation: content.allowAnchorNavigation,
+                    sandbox: content.sandbox
                 }, {
                     autoHeightId: (options == null ? void 0 : options.autoHeight) ? options.id : undefined,
                     onAutoHeight: (options == null ? void 0 : options.autoHeight) ? function(height) {
@@ -93183,7 +93279,7 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
         if (this.state.autoHeightFrames.has(id)) {
             return;
         }
-        var frame = requestAnimationFrame(function() {
+        var frame = requestHTMLOverlayFrame(function() {
             _this.state.autoHeightFrames.delete(id);
             _this.measureAutoHeight(id);
         });
@@ -93267,7 +93363,7 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
         }
         var frame = this.state.autoHeightFrames.get(id);
         if (frame !== undefined) {
-            cancelAnimationFrame(frame);
+            cancelHTMLOverlayFrame(frame);
             this.state.autoHeightFrames.delete(id);
         }
     };
@@ -93285,7 +93381,18 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
         if (Math.abs(nextHeight - item.property.height) <= AUTO_HEIGHT_EPSILON) {
             return;
         }
-        this.options.setCardItemHeight(id, nextHeight);
+        this.options.setCardItemHeight(id, nextHeight, {
+            anchor: this.getAutoHeightAnchor(item),
+            previousHeight: item.property.height
+        });
+    };
+    _proto.getAutoHeightAnchor = function getAutoHeightAnchor(item) {
+        var _ref;
+        var _this_options_resolveCardTypeConfig;
+        if (!isCardItem(item)) {
+            return 'top';
+        }
+        return (_ref = (_this_options_resolveCardTypeConfig = this.options.resolveCardTypeConfig(item)) == null ? void 0 : _this_options_resolveCardTypeConfig.autoHeightAnchor) != null ? _ref : 'top';
     };
     _proto.getAutoHeightItemHeight = function getAutoHeightItemHeight(item, contentHeight) {
         if (!isCardItem(item) || this.isAutoScaleEnabled(item)) {
@@ -93371,7 +93478,7 @@ function formatCssNumber(value) {
 }
 function nextAnimationFrame() {
     return new Promise(function(resolve) {
-        requestAnimationFrame(function() {
+        requestHTMLOverlayFrame(function() {
             resolve();
         });
     });
@@ -93940,12 +94047,29 @@ var SDK = /*#__PURE__*/ function() {
                     bottom: HTML_CARD_EDITING_VIEWPORT_PADDING
                 }, box);
             },
-            setCardItemHeight: function setCardItemHeight(id, height) {
+            setCardItemHeight: function setCardItemHeight(id, height, options) {
+                var item = _this.getSDKItem(id);
+                if (!isCardItem(item) || options.anchor === 'center') {
+                    void _this.setItemProperty({
+                        itemId: id,
+                        type: SDKItemType.CARD,
+                        propertyName: 'height',
+                        propertyValue: height
+                    });
+                    return;
+                }
+                var _item_property_position = item.property.position, x = _item_property_position[0], y = _item_property_position[1];
+                var deltaY = (height - options.previousHeight) / 2;
                 void _this.setItemProperty({
                     itemId: id,
                     type: SDKItemType.CARD,
-                    propertyName: 'height',
-                    propertyValue: height
+                    property: {
+                        height: height,
+                        position: [
+                            x,
+                            y + deltaY
+                        ]
+                    }
                 });
             },
             getSelectedItemIds: function getSelectedItemIds() {
@@ -94079,7 +94203,7 @@ var SDK = /*#__PURE__*/ function() {
             _this._gestureHandler.dispose();
             setTimeout(function() {
                 return _async_to_generator(function() {
-                    var _this_pageData, _this_pageData1, itemExtension;
+                    var itemExtension, _this_pageData, _this_pageData1, createInfos;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -94088,6 +94212,10 @@ var SDK = /*#__PURE__*/ function() {
                                 this._gestureHandler = new GestureHandler(this._container);
                                 this.syncCanvasLayerOrder();
                                 itemExtension = {};
+                                if (!(SDK.config.mode === 'template')) return [
+                                    3,
+                                    2
+                                ];
                                 (_this_pageData = this.pageData) == null ? void 0 : _this_pageData.items.forEach(function(item) {
                                     itemExtension[item.id] = item.getAllExtension();
                                 });
@@ -94103,6 +94231,20 @@ var SDK = /*#__PURE__*/ function() {
                                         item.setExtensions(extension);
                                     }
                                 });
+                                return [
+                                    3,
+                                    4
+                                ];
+                            case 2:
+                                createInfos = this.getItemCreateInfos();
+                                return [
+                                    4,
+                                    this.runByCreateInfos(createInfos)
+                                ];
+                            case 3:
+                                _state.sent();
+                                _state.label = 4;
+                            case 4:
                                 this._eventEmitter.emit('viewRebuildFinish');
                                 return [
                                     2
@@ -94952,6 +95094,55 @@ var SDK = /*#__PURE__*/ function() {
             });
         }).call(this);
     };
+    _proto.runByCreateInfos = function runByCreateInfos(createInfos) {
+        return _async_to_generator(function() {
+            var _this__pageData_activeData_view, _this__pageData_activeData_view1, viewSize, scene, targetViewProperty;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        assertExist$1(this._pageData, 'You must call SDK#run() first');
+                        this._pageData.property.zoom = 1;
+                        this._pageData.property.translation = [
+                            0,
+                            0
+                        ];
+                        this._pageDataUtils.init();
+                        return [
+                            4,
+                            this._gestureHandler.init(this._pageDataUtils, this._eventEmitter)
+                        ];
+                    case 1:
+                        _state.sent();
+                        viewSize = [
+                            this._playerContainer.offsetWidth,
+                            this._playerContainer.offsetHeight
+                        ];
+                        scene = getBasicScene(viewSize);
+                        targetViewProperty = this.getViewProperty((_this__pageData_activeData_view = this._pageData.activeData.view) != null ? _this__pageData_activeData_view : 0);
+                        if (targetViewProperty) {
+                            targetViewProperty.scene = scene;
+                        }
+                        return [
+                            4,
+                            this._pageDataUtils.loadScene((_this__pageData_activeData_view1 = this._pageData.activeData.view) != null ? _this__pageData_activeData_view1 : 0)
+                        ];
+                    case 2:
+                        _state.sent();
+                        return [
+                            4,
+                            this.addItemByCreateInfos(createInfos)
+                        ];
+                    case 3:
+                        _state.sent();
+                        this._pageDataUtils.refreshPageTime(this._pageData.time);
+                        this._eventEmitter.emit('pageDataChange', this.pageData);
+                        return [
+                            2
+                        ];
+                }
+            });
+        }).call(this);
+    };
     _proto.reloadPageDataByScene = function reloadPageDataByScene(scene) {
         return _async_to_generator(function() {
             var _ref, _this__pageData_activeData_view, _ref1, _ref2, _loadScene_compositions_find, _this_player_getCompositions_, _this_player_getCompositions_1, loadScene, response, error;
@@ -95646,7 +95837,11 @@ var SDK = /*#__PURE__*/ function() {
             return item.id;
         })) != null ? _ref : [];
         ids.forEach(function(id) {
-            var createInfo = _this._pageDataUtils.getItemCreateInfo(id, true);
+            var _this__pageDataUtils_getItemCreateInfo;
+            var _this_pageData_items_find, _this_pageData;
+            var createInfo = (_this__pageDataUtils_getItemCreateInfo = _this._pageDataUtils.getItemCreateInfo(id, true)) != null ? _this__pageDataUtils_getItemCreateInfo : (_this_pageData = _this.pageData) == null ? void 0 : (_this_pageData_items_find = _this_pageData.items.find(function(item) {
+                return item.id === id;
+            })) == null ? void 0 : _this_pageData_items_find.toCreateInfo(true);
             if (createInfo) {
                 createInfos.push(createInfo);
             }
@@ -96184,6 +96379,38 @@ var SDK = /*#__PURE__*/ function() {
         return true;
     };
     /**
+   * @description 获取指定 HTML 卡片当前 iframe 的 window。
+   * @description 仅 inline/document 或自行渲染 iframe 的 DOM 内容会返回 window。
+   * @param id 卡片元素 ID
+   * @returns HTML iframe window
+   */ _proto.getHtmlCardWindow = function getHtmlCardWindow(id) {
+        var _this__htmlOverlayManager;
+        return (_this__htmlOverlayManager = this._htmlOverlayManager) == null ? void 0 : _this__htmlOverlayManager.getHtmlCardWindow(id);
+    };
+    /**
+   * @description 向指定 HTML 卡片发送增量 patch。
+   * @description 当卡片内容配置了 CardHTMLPatchHandler 时，可用于局部更新 HTML，而不必整卡 refresh。
+   * @param id 卡片元素 ID
+   * @param patch patch 负载，由卡片内容自己的 patch handler 解释
+   * @returns 是否被 patch handler 处理
+   */ _proto.patchCardHTML = function patchCardHTML(id, patch) {
+        var _ref;
+        var _this__htmlOverlayManager;
+        return (_ref = (_this__htmlOverlayManager = this._htmlOverlayManager) == null ? void 0 : _this__htmlOverlayManager.patchCardHTML(id, patch)) != null ? _ref : false;
+    };
+    /**
+   * @description 向指定 HTML 卡片 iframe 派发事件。
+   * @description 通过 postMessage 投递事件，跨源/同源行为一致，消息 source 为 vvfx-card-html-event。
+   * @param id 卡片元素 ID
+   * @param type 事件名称
+   * @param detail 事件 detail
+   * @returns 是否成功派发或投递
+   */ _proto.dispatchHtmlCardEvent = function dispatchHtmlCardEvent(id, type, detail) {
+        var _ref;
+        var _this__htmlOverlayManager;
+        return (_ref = (_this__htmlOverlayManager = this._htmlOverlayManager) == null ? void 0 : _this__htmlOverlayManager.dispatchHtmlCardEvent(id, type, detail)) != null ? _ref : false;
+    };
+    /**
    * @description 创建卡片元素
    * @description 底层以透明 SpriteItem 形式渲染，支持 cardType 属性
    * @param createInfo 卡片创建信息