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

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/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.12
+ * Version: v0.2.2-beta.13
  */
 
 import * as EFFECTS from '@galacean/effects';
@@ -91867,6 +91867,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;
@@ -91939,7 +91963,7 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
                 return;
             }
             if (_this.contentInteractionFrame !== undefined) {
-                cancelAnimationFrame(_this.contentInteractionFrame);
+                cancelHTMLOverlayFrame(_this.contentInteractionFrame);
                 _this.contentInteractionFrame = undefined;
             }
             _this.pendingContentInteractionEvent = undefined;
@@ -92000,11 +92024,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;
@@ -92034,7 +92058,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) {
@@ -92053,9 +92077,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();
         });
@@ -92064,6 +92088,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;
@@ -92071,7 +92129,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();
@@ -92238,13 +92296,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;
@@ -92259,8 +92314,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);
         });
@@ -92500,14 +92559,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;
@@ -92931,6 +92996,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;
@@ -92990,6 +93069,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){
@@ -93182,7 +93265,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);
         });
@@ -93266,7 +93349,7 @@ var HTMLOverlayManager = /*#__PURE__*/ function() {
         }
         var frame = this.state.autoHeightFrames.get(id);
         if (frame !== undefined) {
-            cancelAnimationFrame(frame);
+            cancelHTMLOverlayFrame(frame);
             this.state.autoHeightFrames.delete(id);
         }
     };
@@ -93284,7 +93367,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)) {
@@ -93370,7 +93464,7 @@ function formatCssNumber(value) {
 }
 function nextAnimationFrame() {
     return new Promise(function(resolve) {
-        requestAnimationFrame(function() {
+        requestHTMLOverlayFrame(function() {
             resolve();
         });
     });
@@ -93939,12 +94033,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() {
@@ -96168,6 +96279,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 卡片创建信息