vite-plugin-taro-runtime 0.7.13 → 0.8.0-beta.0

package/dist/runtime/dom/event-target.js

@@ -1,8 +1,15 @@
 import { hooks, isObject, warn, isArray } from '@tarojs/shared';
 
 class TaroEventTarget {
-    constructor() {
-        this.__handlers = {};
+    // Each target retains one mutable table, initialized on first mutable access.
+    get __handlers() {
+        return this._handlers ??= {};
+    }
+    set __handlers(value) {
+        this._handlers = value;
+    }
+    getEventHandlers(type) {
+        return this._handlers?.[type];
     }
     addEventListener(type, handler, options) {
         type = type.toLowerCase();
@@ -44,6 +51,11 @@ class TaroEventTarget {
         else {
             this.__handlers[type] = [handler];
         }
+        // 用原有处理器数组判断首次订阅：第二个及后续处理器共用同一个原生入口。
+        // 通知发生在数组写入后，host 可直接读取已完成的逻辑状态。
+        if (this.__handlers[type].length === 1) {
+            this.delegateEventListener(type, true);
+        }
     }
     removeEventListener(type, handler) {
         type = type.toLowerCase();
@@ -56,7 +68,7 @@ class TaroEventTarget {
         if (!handler) {
             return;
         }
-        const handlers = this.__handlers[type];
+        const handlers = this.getEventHandlers(type);
         if (!isArray(handlers)) {
             return;
         }
@@ -65,16 +77,32 @@ class TaroEventTarget {
                 return true;
         });
         process.env.NODE_ENV !== 'production' && warn(index === -1, `事件: '${type}' 没有注册在 DOM 中，因此不会被移除。`);
+        if (index === -1) {
+            return;
+        }
         handlers.splice(index, 1);
+        // 最后一个处理器移除后再通知解绑；长度判断复用现有数组，为 O(1)。
+        if (handlers.length === 0) {
+            this.delegateEventListener(type, false);
+        }
     }
+    /**
+     * 处理器数组从空变为非空时 subscribed=true，最后一个处理器移除后为 false。
+     * type 是 Taro 已规范化的小写逻辑事件名；regionchange 已展开为 begin/end，
+     * 平台原生事件名及其订阅关系由 host 对接。
+     * 模板通过既有模板绑定接收事件，因此默认实现为空；原生 host 在此控制订阅开关，
+     * 业务处理器仍由 __handlers 保存，once、包装函数和移除匹配继续由 Taro 负责。
+     * 原生回调可通过 eventHandler(event, logicalNode) 进入共享派发流程。
+     */
+    delegateEventListener(_type, _subscribed) { }
     isAnyEventBinded() {
-        const handlers = this.__handlers;
-        const isAnyEventBinded = Object.keys(handlers).find(key => handlers[key].length);
+        const handlers = this._handlers;
+        const isAnyEventBinded = handlers && Object.keys(handlers).find(key => handlers[key].length);
         return Boolean(isAnyEventBinded);
     }
     isOnlyClickBinded() {
-        const handlers = this.__handlers;
-        const isOnlyClickBinded = handlers.tap && Object.keys(handlers).length === 1;
+        const handlers = this._handlers;
+        const isOnlyClickBinded = handlers?.tap && Object.keys(handlers).length === 1;
         return Boolean(isOnlyClickBinded);
     }
 }

package/dist/runtime/dom/event.d.ts

@@ -17,11 +17,18 @@ declare class TaroEvent {
     stopPropagation(): void;
     stopImmediatePropagation(): void;
     preventDefault(): void;
+    /** Template lookup policy; native hosts return null to use SDK target records. */
+    getTargetElement(target: MpEvent['target'] | undefined, useTargetDataset: boolean): TaroElement | null;
     get target(): any;
     get currentTarget(): any;
 }
 declare function createEvent(event: MpEvent | string, node?: TaroElement): TaroEvent;
-declare function eventHandler(event: MpEvent): any;
+/**
+ * 共用平台归一化、事件 hooks、批处理及表单处理的原生事件入口。
+ * currentNode 可传入已知 Taro 逻辑节点以跳过入口 ID 查询；省略时按原有事件索引查找。
+ * target/currentTarget 按 host 的 getTargetElement 策略读取模板索引或 SDK 数据。
+ */
+declare function eventHandler(event: MpEvent, currentNode?: TaroElement): any;
 declare function eventHandlerTTDom(ele: any, listener: (event: MpEvent, element: any) => void, event: MpEvent): void;
 
 export { TaroEvent, createEvent, eventHandler, eventHandlerTTDom };

package/dist/runtime/dom/event.js

@@ -28,15 +28,23 @@ class TaroEvent {
     preventDefault() {
         this.defaultPrevented = true;
     }
+    /** Template events resolve logical datasets; native hosts use SDK target records. */
+    getTargetElement(target, useTargetDataset) {
+        const id = (useTargetDataset && target?.targetDataset?.sid) || target?.dataset?.sid || target?.id || null;
+        return env.document.getElementById(id);
+    }
     get target() {
-        var _a, _b, _c, _d, _e;
+        var _a, _e;
         const cacheTarget = this.cacheTarget;
         if (!cacheTarget) {
             const target = Object.create(((_a = this.mpEvent) === null || _a === void 0 ? void 0 : _a.target) || null);
-            const currentEle = env.document.getElementById(((_b = target.dataset) === null || _b === void 0 ? void 0 : _b.sid) || target.id || null);
-            // Note：优先判断冒泡场景alipay的targetDataset的sid, 不然冒泡场景target属性吐出不对，其余拿取当前绑定id
-            const element = env.document.getElementById(((_c = target.targetDataset) === null || _c === void 0 ? void 0 : _c.sid) || ((_d = target.dataset) === null || _d === void 0 ? void 0 : _d.sid) || target.id || null);
-            target.dataset = Object.assign(Object.assign({}, (currentEle !== null ? currentEle.dataset : EMPTY_OBJ)), (element !== null ? element.dataset : EMPTY_OBJ));
+            const currentEle = this.getTargetElement(target, false);
+            // Alipay's targetDataset identifies the bubbling target separately from its wrapper.
+            const element = this.getTargetElement(target, true);
+            // 索引命中时仍以逻辑 dataset 为准，保留对象值及支付宝两层数据的合并顺序。
+            // 索引未命中只表示无法取得逻辑节点，不能丢弃平台已提供的数据。
+            // 两个来源分别兜底，复用原有 Object.assign 和缓存；不补建索引或遍历节点树。
+            target.dataset = Object.assign(Object.assign({}, (currentEle !== null ? currentEle.dataset : target.dataset || EMPTY_OBJ)), (element !== null ? element.dataset : target.targetDataset || EMPTY_OBJ));
             for (const key in (_e = this.mpEvent) === null || _e === void 0 ? void 0 : _e.detail) {
                 target[key] = this.mpEvent.detail[key];
             }
@@ -48,18 +56,22 @@ class TaroEvent {
         }
     }
     get currentTarget() {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+        var _a, _h;
         const cacheCurrentTarget = this.cacheCurrentTarget;
         if (!cacheCurrentTarget) {
-            const doc = env.document;
             const currentTarget = Object.create(((_a = this.mpEvent) === null || _a === void 0 ? void 0 : _a.currentTarget) || null);
-            const element = doc.getElementById(((_b = currentTarget.dataset) === null || _b === void 0 ? void 0 : _b.sid) || currentTarget.id || null);
-            const targetElement = doc.getElementById(((_e = (_d = (_c = this.mpEvent) === null || _c === void 0 ? void 0 : _c.target) === null || _d === void 0 ? void 0 : _d.dataset) === null || _e === void 0 ? void 0 : _e.sid) || ((_g = (_f = this.mpEvent) === null || _f === void 0 ? void 0 : _f.target) === null || _g === void 0 ? void 0 : _g.id) || null);
-            if (element === null || (element && element === targetElement)) {
+            const element = this.getTargetElement(currentTarget, false);
+            const targetElement = this.getTargetElement(this.mpEvent?.target, false);
+            // 已知逻辑节点相同才沿用 target；未命中时，只有同一原始对象能证明身份相同。
+            // 两个 null 查询结果、空 ID 或相同的未解析 ID 都不能证明两个事件目标相同。
+            // 无平台事件时保留手动构造事件的共享目标；这里只比较已有引用，不新增查询或状态。
+            if (element !== null ? element === targetElement : !this.mpEvent || this.mpEvent.currentTarget === this.mpEvent.target) {
                 this.cacheCurrentTarget = this.target;
                 return this.target;
             }
-            currentTarget.dataset = element.dataset;
+            // 保留已知逻辑 dataset 的引用；未命中时使用当前接收目标自己的平台 dataset。
+            // detail 合并和惰性缓存继续复用下方流程，不把接收目标替换成触发目标。
+            currentTarget.dataset = element !== null ? element.dataset : currentTarget.dataset || EMPTY_OBJ;
             for (const key in (_h = this.mpEvent) === null || _h === void 0 ? void 0 : _h.detail) {
                 currentTarget[key] = this.mpEvent.detail[key];
             }
@@ -100,7 +112,27 @@ function getEventCBResult(event) {
     return result;
 }
 // 小程序的事件代理回调函数
-function eventHandler(event) {
+/**
+ * Taro 节点维护逻辑树、属性和业务监听器；TT 原生节点负责显示并接收平台事件。
+ *
+ * 模板中的多个原生节点共用此入口。eventHandler(event) 在平台事件归一化后，
+ * 根据事件中的 sid/id 从 Taro 已有索引取得接收节点，再进入统一的事件派发流程。
+ * 这里的索引查询不是整棵树的遍历。
+ *
+ * DOM host 为某个原生节点注册回调时，已经持有对应的 Taro 逻辑节点，可以直接传入：
+ *     nativeNode.addEventListener(nativeEventName, event => eventHandler(event, taroNode));
+ * eventHandler(event, taroNode) 使用这个已知接收节点，省去入口的一次 ID 读取和索引查询。
+ * currentNode 是 Taro 节点，不是 TT 原生节点；该参数是可选的，原生事件携带正确的
+ * sid/id 时也可以使用单参数入口。它只是利用已知对象，并非 DOM 渲染的必要条件。
+ *
+ * 两种入口共用平台归一化、事件构造、hooks、冒泡批处理、回调返回值，以及 React
+ * 事件优先级和受控输入恢复。node.dispatchEvent() 只是其中靠后的环节，直接调用它
+ * 会绕过外围处理，因此 host 应从这里进入已有事件流程。
+ *
+ * 可选参数只改变接收节点的取得方式，不增加持久状态或循环，也不代表显著性能提升。
+ * target/currentTarget 通过 getTargetElement 选择模板索引或原生 SDK 数据。
+ */
+function eventHandler(event, currentNode) {
     var _a, _b;
     // Note: ohos 上事件没有设置 type、detail 类型 setter 方法，且部分事件（例如 load 等）缺失 target 导致事件错误
     event.type === undefined && Object.defineProperty(event, 'type', {
@@ -112,8 +144,7 @@ function eventHandler(event) {
     event.currentTarget = event.currentTarget || event.target || Object.assign({}, event);
     hooks.call('modifyMpEventImpl', event);
     const currentTarget = event.currentTarget;
-    const id = ((_a = currentTarget.dataset) === null || _a === void 0 ? void 0 : _a.sid /** sid */) || currentTarget.id /** uid */ || ((_b = event.detail) === null || _b === void 0 ? void 0 : _b.id) || '';
-    const node = env.document.getElementById(id);
+    const node = currentNode || env.document.getElementById(((_a = currentTarget.dataset) === null || _a === void 0 ? void 0 : _a.sid /** sid */) || currentTarget.id /** uid */ || ((_b = event.detail) === null || _b === void 0 ? void 0 : _b.id) || '');
     if (node) {
         const dispatch = () => {
             const e = createEvent(event, node);

package/dist/runtime/dom/nearest-ctx.d.ts

@@ -4,6 +4,8 @@ import { TaroRootElement } from './root.js';
 
 declare function isNearestCtxEnv(): boolean;
 declare function getNearestCtx(node: TaroNode): MpInstance | null | undefined;
+declare function getCachedNearestCtx(node: TaroNode): MpInstance | null | undefined;
+declare function invalidateNearestCtx(node: TaroNode): void;
 declare function bumpNearestCtxEpochForRoot(root: TaroRootElement | null | undefined): void;
 
-export { bumpNearestCtxEpochForRoot, getNearestCtx, isNearestCtxEnv };
+export { bumpNearestCtxEpochForRoot, getCachedNearestCtx, getNearestCtx, invalidateNearestCtx, isNearestCtxEnv };

package/dist/runtime/dom/nearest-ctx.js

@@ -1,8 +1,12 @@
+// Template context reads reuse values until a root epoch change invalidates them.
 const nearestCtxCache = new WeakMap();
 function isNearestCtxEnv() {
     return process.env.TARO_ENV === 'weapp' || process.env.TARO_ENV === 'jd';
 }
 function getNearestCtx(node) {
+    return node._scope;
+}
+function getCachedNearestCtx(node) {
     if (!isNearestCtxEnv()) {
         return undefined;
     }
@@ -36,6 +40,11 @@ function resolveNearestCtxValue(node, root) {
     }
     return (_a = root.ctx) !== null && _a !== void 0 ? _a : null;
 }
+function invalidateNearestCtx(node) {
+    if (isNearestCtxEnv()) {
+        node.delegateContextInvalidation();
+    }
+}
 function bumpNearestCtxEpochForRoot(root) {
     if (!isNearestCtxEnv() || root == null) {
         return;
@@ -45,5 +54,5 @@ function bumpNearestCtxEpochForRoot(root) {
     }
 }
 
-export { bumpNearestCtxEpochForRoot, getNearestCtx, isNearestCtxEnv };
+export { bumpNearestCtxEpochForRoot, getCachedNearestCtx, getNearestCtx, invalidateNearestCtx, isNearestCtxEnv };
 //# sourceMappingURL=nearest-ctx.js.map

package/dist/runtime/dom/node.d.ts

@@ -19,12 +19,17 @@ declare class TaroNode extends TaroEventTarget {
     parentNode: TaroNode | null;
     childNodes: TaroNode[];
     constructor();
-    private hydrate;
-    /** Delegates a complete child-list update, including the final reset after element textContent changes. */
+    /**
+     * 子列表整体更新通知，包括 textContent 完成逐项变更后的最终通知。
+     * isClean=true 对应空列表，否则模板默认延迟序列化当前子节点；逻辑树已由调用方修改。
+     * 已通过逐项委托同步原生关系的 host 可将此作为完成通知。
+     */
     delegateChildReset(isClean?: boolean): void;
     private updateSingleChild;
     get _root(): TaroRootElement | null;
     get _scope(): MpInstance | null | undefined;
+    /** Invalidate template context caches after presentation or a context lifecycle change. */
+    delegateContextInvalidation(): void;
     protected findIndex(refChild: TaroNode): number;
     get _path(): string;
     get nextSibling(): TaroNode | null;
@@ -73,13 +78,16 @@ declare class TaroNode extends TaroEventTarget {
      */
     removeChild<T extends TaroNode>(child: T, options?: RemoveChildOptions): T;
     /**
-     * Delegates an insertion after Taro updates its tree, including detached parents.
-     * The index is the insertion offset when refChild is supplied. The default prepares template payloads.
+     * 逻辑插入完成后调用，包含未挂载的父节点；默认准备模板 payload。
+     * this 为新父节点，refChild 为空表示追加；index 仅在存在 refChild 时表示插入位置。
+     * isReplace 表示替换的插入阶段，旧 refChild 随后另行移除；host 此处只同步插入。
+     * previousIndex 为同父节点移动前的位置；移动仅通知插入，模板默认延迟更新完整子列表。
      */
-    delegateChildInsertion(newChild: TaroNode, refChild: TaroNode | null | undefined, index: number, isReplace: boolean | undefined): void;
+    delegateChildInsertion(newChild: TaroNode, refChild: TaroNode | null | undefined, index: number, isReplace: boolean | undefined, previousIndex?: number): void;
     /**
-     * Delegates a removal after logical detachment and event identity cleanup.
-     * Every removal is forwarded; options.doUpdate only suppresses the default template update.
+     * 逻辑解绑及按 cleanRef 清理事件索引后调用；this 为原父节点，child.parentNode 已为空。
+     * 每次实际移除都会通知，options.doUpdate=false 仅抑制默认模板更新。
+     * host 使用 child 同步原生解绑，逻辑树和事件索引仍由 Taro 维护。
      */
     delegateChildRemoval(child: TaroNode, options: RemoveChildOptions): void;
     remove(options?: RemoveChildOptions): void;

package/dist/runtime/dom/node.js

@@ -6,7 +6,7 @@ import { hydrate } from '../hydrate.js';
 import { incrementId, isComment, extend } from '../utils/index.js';
 import { eventSource } from './event-source.js';
 import { TaroEventTarget } from './event-target.js';
-import { getNearestCtx, bumpNearestCtxEpochForRoot } from './nearest-ctx.js';
+import { getCachedNearestCtx, bumpNearestCtxEpochForRoot } from './nearest-ctx.js';
 
 const CHILDNODES = "cn" /* Shortcuts.Childnodes */;
 const nodeId = incrementId();
@@ -15,12 +15,18 @@ class TaroNode extends TaroEventTarget {
         super();
         this.parentNode = null;
         this.childNodes = [];
-        this.hydrate = (node) => () => hydrate(node);
         this.uid = '_' + nodeId(); // dom 节点 id，开发者可修改
         this.sid = this.uid; // dom 节点全局唯一 id，不可被修改
         eventSource.set(this.sid, this);
     }
-    /** Delegates a complete child-list update; the default hydrates lazily or emits an empty list. */
+    /**
+     * 通知整个子列表的最终呈现状态；包括 textContent 完成逐项删除/插入后的整表通知。
+     * isClean 为 true 时，模板 payload 的值为空列表；否则在 flush 时序列化当前子节点。
+     * 逻辑树的修改已经由调用方完成，此方法只准备呈现更新，不负责清空或重建逻辑树。
+     * 默认实现保留过滤注释节点、延迟 hydrate 和 cn 路径更新。
+     * 已通过逐项插入/移除委托同步原生树的 host，可将此处作为完成通知，
+     * 避免把同一逻辑变更再次执行为整树遍历或原生节点重建。
+     */
     delegateChildReset(isClean) {
         const cleanChildNodes = () => [];
         const rerenderChildNodes = () => {
@@ -40,7 +46,7 @@ class TaroNode extends TaroEventTarget {
                 return;
             this.enqueueUpdate({
                 path: child._path,
-                value: this.hydrate(child)
+                value: () => hydrate(child)
             });
         });
     }
@@ -49,7 +55,11 @@ class TaroNode extends TaroEventTarget {
         return ((_a = this.parentNode) === null || _a === void 0 ? void 0 : _a._root) || null;
     }
     get _scope() {
-        return getNearestCtx(this);
+        return getCachedNearestCtx(this);
+    }
+    /** Called after child presentation and at Page/component context lifecycle boundaries. */
+    delegateContextInvalidation() {
+        bumpNearestCtxEpochForRoot(this._root);
     }
     findIndex(refChild) {
         const index = this.childNodes.indexOf(refChild);
@@ -95,8 +105,13 @@ class TaroNode extends TaroEventTarget {
      */
     // eslint-disable-next-line accessor-pairs
     set textContent(text) {
-        const removedNodes = this.childNodes.slice();
-        const addedNodes = [];
+        // Capture old children only for registered observers; added nodes fill this operation-local record.
+        const record = MutationObserver.hasObservers ? {
+            type: "childList" /* MutationRecordType.CHILD_LIST */,
+            target: this,
+            removedNodes: this.childNodes.slice(),
+            addedNodes: []
+        } : null;
         // Handle old children' data structure & ref
         while (this.firstChild) {
             this.removeChild(this.firstChild, { doUpdate: false });
@@ -105,18 +120,17 @@ class TaroNode extends TaroEventTarget {
             this.delegateChildReset(true);
         }
         else {
-            const newText = env.document.createTextNode(text);
-            addedNodes.push(newText);
+            const newText = this.ownerDocument.createTextNode(text);
+            if (record) {
+                record.addedNodes.push(newText);
+            }
             this.appendChild(newText);
             this.delegateChildReset();
         }
         // @Todo: appendChild 会多触发一次
-        MutationObserver.record({
-            type: "childList" /* MutationRecordType.CHILD_LIST */,
-            target: this,
-            removedNodes,
-            addedNodes
-        });
+        if (record) {
+            MutationObserver.record(record);
+        }
     }
     /**
      * @doc https://developer.mozilla.org/zh-CN/docs/Web/API/Node/insertBefore
@@ -127,6 +141,10 @@ class TaroNode extends TaroEventTarget {
      *   3. insert D before C, D has the different parent of C
      */
     insertBefore(newChild, refChild, isReplace) {
+        if (newChild === refChild) {
+            this.findIndex(refChild);
+            return newChild;
+        }
         if (newChild.nodeName === DOCUMENT_FRAGMENT) {
             newChild.childNodes.reduceRight((previousValue, currentValue) => {
                 this.insertBefore(currentValue, previousValue);
@@ -134,10 +152,15 @@ class TaroNode extends TaroEventTarget {
             }, refChild);
             return newChild;
         }
-        // Parent release newChild
-        //   - cleanRef: false (No need to clean eventSource, because newChild is about to be inserted)
-        //   - update: true (Need to update parent.childNodes, because parent.childNodes is reordered)
-        newChild.remove({ cleanRef: false });
+        const previousIndex = newChild.parentNode === this ? this.findIndex(newChild) : undefined;
+        if (previousIndex !== undefined) {
+            // Reorder the sibling array in place, retaining parent and event identity for the native move.
+            this.childNodes.splice(previousIndex, 1);
+        }
+        else {
+            newChild.remove({ cleanRef: false });
+        }
+        // The insertion index is assigned after removal so forward moves use the anchor's current position.
         let index = 0;
         // Data structure
         newChild.parentNode = this;
@@ -152,22 +175,22 @@ class TaroNode extends TaroEventTarget {
         }
         // Delegation runs after the logical insertion, including on detached parents.
         // Its default implementation prepares template payloads; native hosts can replace it before any serialization work.
-        this.delegateChildInsertion(newChild, refChild, index, isReplace);
-        if (this._root) {
-            bumpNearestCtxEpochForRoot(this._root);
+        this.delegateChildInsertion(newChild, refChild, index, isReplace, previousIndex);
+        this.delegateContextInvalidation();
+        if (MutationObserver.hasObservers) {
+            MutationObserver.record({
+                type: "childList" /* MutationRecordType.CHILD_LIST */,
+                target: this,
+                addedNodes: [newChild],
+                removedNodes: isReplace
+                    ? [refChild] /** replaceChild */
+                    : [],
+                nextSibling: isReplace
+                    ? refChild.nextSibling /** replaceChild */
+                    : (refChild || null), /** insertBefore & appendChild */
+                previousSibling: newChild.previousSibling
+            });
         }
-        MutationObserver.record({
-            type: "childList" /* MutationRecordType.CHILD_LIST */,
-            target: this,
-            addedNodes: [newChild],
-            removedNodes: isReplace
-                ? [refChild] /** replaceChild */
-                : [],
-            nextSibling: isReplace
-                ? refChild.nextSibling /** replaceChild */
-                : (refChild || null), /** insertBefore & appendChild */
-            previousSibling: newChild.previousSibling
-        });
         return newChild;
     }
     /**
@@ -192,6 +215,9 @@ class TaroNode extends TaroEventTarget {
     replaceChild(newChild, oldChild) {
         if (oldChild.parentNode !== this)
             return;
+        if (newChild === oldChild) {
+            return oldChild;
+        }
         // Insert the newChild
         this.insertBefore(newChild, oldChild, true);
         // Destroy the oldChild
@@ -209,7 +235,7 @@ class TaroNode extends TaroEventTarget {
      */
     removeChild(child, options = {}) {
         const { cleanRef, doUpdate } = options;
-        if (cleanRef !== false && doUpdate !== false) {
+        if (cleanRef !== false && doUpdate !== false && MutationObserver.hasObservers) {
             // appendChild/replaceChild/insertBefore 不应该触发
             // @Todo: 但其实如果 newChild 的父节点是另一颗子树的节点，应该是要触发的
             MutationObserver.record({
@@ -230,17 +256,28 @@ class TaroNode extends TaroEventTarget {
         }
         // Forward every removal. doUpdate controls template batching, not whether the logical child was removed.
         this.delegateChildRemoval(child, options);
-        if (this._root) {
-            bumpNearestCtxEpochForRoot(this._root);
-        }
+        this.delegateContextInvalidation();
         return child;
     }
-    /** Delegates an insertion after Taro has updated parentNode and childNodes. */
-    delegateChildInsertion(newChild, refChild, index, isReplace) {
+    /**
+     * 在 Taro 更新 parentNode/childNodes 后委托插入，父节点尚未挂载时也会调用。
+     * this 是新父节点；newChild 是已插入的逻辑节点；refChild 为空表示追加。
+     * index 仅在有 refChild 时表示逻辑插入位置，追加分支中的值不表示末尾索引。
+     * isReplace 表示 replaceChild 的插入阶段：refChild 此时仍在树中，随后由原方法
+     * 单独移除。原生 host 此处执行插入，旧节点的移除由移除委托接收。
+     * previousIndex 是同父节点移动前的位置；移动仅通知插入，保留 parentNode 和事件身份。
+     * 默认实现对移动延迟更新完整子列表，其余插入保留局部更新/整表更新选择。
+     * 原有上下文缓存失效和插入 MutationObserver 记录仍由调用方在委托之后完成。
+     */
+    delegateChildInsertion(newChild, refChild, index, isReplace, previousIndex) {
         const childNodesLength = this.childNodes.length;
         // Serialization
         if (this._root) {
-            if (!refChild) {
+            if (previousIndex !== undefined) {
+                // A move changes existing slots, including append and replacement. Hydrate the final list at flush.
+                this.delegateChildReset();
+            }
+            else if (!refChild) {
                 // appendChild
                 const isOnlyChild = childNodesLength === 1;
                 if (isOnlyChild) {
@@ -249,7 +286,7 @@ class TaroNode extends TaroEventTarget {
                 else {
                     this.enqueueUpdate({
                         path: newChild._path,
-                        value: this.hydrate(newChild)
+                        value: () => hydrate(newChild)
                     });
                 }
             }
@@ -257,7 +294,7 @@ class TaroNode extends TaroEventTarget {
                 // replaceChild
                 this.enqueueUpdate({
                     path: newChild._path,
-                    value: this.hydrate(newChild)
+                    value: () => hydrate(newChild)
                 });
             }
             else {
@@ -284,7 +321,14 @@ class TaroNode extends TaroEventTarget {
             }
         }
     }
-    /** Delegates a removal after logical detachment and event identity cleanup. */
+    /**
+     * 在逻辑解绑及按 cleanRef 执行事件索引清理后委托移除。
+     * this 仍是原父节点，child.parentNode 已为 null；_child 供原生 host 定位被移除的节点，
+     * 模板默认实现只需要读取父节点当前的子列表，因此不使用该参数。
+     * options 是调用方原有选项；doUpdate: false 仅抑制默认模板整表更新，
+     * 常用于移动、替换和 textContent 的批量操作。每次实际解绑仍会通知 host。
+     * cleanRef 的处理属于 Taro，host 只同步原生关系；上下文缓存失效由调用方随后完成。
+     */
     delegateChildRemoval(_child, options) {
         if (this._root && options.doUpdate !== false) {
             this.delegateChildReset();

package/dist/runtime/dom/style.d.ts

@@ -9,8 +9,13 @@ declare class Style {
     private setCssVariables;
     get cssText(): string;
     set cssText(str: string);
-    /** Delegates after logical style changes and cssText batching, before the default template payload is prepared. */
-    delegateStyleUpdate(): void;
+    /**
+     * 单项变更传入属性名与赋值；null/undefined/空字符串表示清除。
+     * 普通属性名为 camelCase，CSS 变量及连字符前缀保留原名。
+     * cssText 的同步批量赋值完成后不传参数调用一次，表示整体替换。
+     * this 为 Style，可读取 _element 和完整 cssText；默认准备模板 st 更新。
+     */
+    delegateStyleUpdate(styleKey?: string, value?: string | number | null): void;
     setProperty(propertyName: string, value?: string | null): void;
     removeProperty(propertyName: string): string;
     getPropertyValue(propertyName: string): any;

package/dist/runtime/dom/style.js

@@ -4,6 +4,9 @@ import { MutationObserver } from '../dom-external/mutation-observer/index.js';
 import { styleProperties } from './style_properties.js';
 
 function recordCss(obj) {
+    if (!MutationObserver.hasObservers) {
+        return;
+    }
     MutationObserver.record({
         type: "attributes" /* MutationRecordType.ATTRIBUTES */,
         target: obj._element,
@@ -25,7 +28,7 @@ function setStyle(newVal, styleKey) {
         this._usedStyleProp.add(styleKey);
         this._value[styleKey] = newVal;
     }
-    !this._pending && this.delegateStyleUpdate();
+    !this._pending && this.delegateStyleUpdate(styleKey, newVal);
 }
 function initStyle(ctor, styleProperties) {
     const properties = {};
@@ -110,8 +113,17 @@ class Style {
         this._pending = false;
         this.delegateStyleUpdate();
     }
-    /** Delegates the completed style mutation; cssText assignments finish their synchronous batch before calling it. */
-    delegateStyleUpdate() {
+    /**
+     * 单项样式写入在逻辑值和 mutation 记录更新后调用；相同值沿用原有提前返回。
+     * styleKey 为 setStyle 收到的属性名（普通属性为 camelCase，CSS 变量及连字符前缀保留原名），
+     * value 为该次赋值；null/undefined/空字符串表示清除。原生 host 可直接转发这一个属性。
+     * cssText 赋值使用 Taro 已有的 _pending 同步批处理，完成后不传参数调用一次，表示整体替换；
+     * 清空 cssText 也走此入口。setProperty/removeProperty/CSS 变量复用同一套样式存储。
+     * this 是 Style，this._element 是所属 Taro 元素；整体替换可读取已规范化的 this.cssText。
+     * 默认模板实现统一准备完整 st payload，因此不使用单项参数。
+     * 单项委托本身无需遍历样式；Taro 的 mutation 旧值记录及具体 SDK 的序列化成本仍独立存在。
+     */
+    delegateStyleUpdate(_styleKey, _value) {
         const element = this._element;
         if (element._root) {
             element.enqueueUpdate({
@@ -136,7 +148,8 @@ class Style {
         }
     }
     removeProperty(propertyName) {
-        propertyName = isCssVariable(propertyName) ? propertyName : toCamelCase(propertyName);
+        // Prefer stored keys while preserving dashed access to registered camelCase vendor setters.
+        propertyName = isCssVariable(propertyName) || this._usedStyleProp.has(propertyName) ? propertyName : toCamelCase(propertyName);
         if (!this._usedStyleProp.has(propertyName)) {
             return '';
         }
@@ -145,7 +158,8 @@ class Style {
         return value;
     }
     getPropertyValue(propertyName) {
-        propertyName = isCssVariable(propertyName) ? propertyName : toCamelCase(propertyName);
+        // CSS variables retain their spelling; other names resolve through a stored key or camelCase.
+        propertyName = isCssVariable(propertyName) || this._usedStyleProp.has(propertyName) ? propertyName : toCamelCase(propertyName);
         const value = this[propertyName];
         if (!value) {
             return '';

package/dist/runtime/dom/text.d.ts

@@ -13,8 +13,9 @@ declare class TaroText extends TaroNode {
     set data(text: string);
     get data(): string;
     /**
-     * Delegates a text update after Taro records the mutation and stores the logical value.
-     * The default prepares the template payload; textContent, nodeValue and data share this boundary.
+     * characterData 记录及逻辑值写入后调用，text 为最新文本。
+     * textContent、nodeValue、data setter 共用此入口；初值由节点创建路径处理。
+     * 默认准备模板 v 更新，host 可改为原生文本更新。
      */
     delegateTextUpdate(text: string): void;
 }

package/dist/runtime/dom/text.js

@@ -9,11 +9,13 @@ class TaroText extends TaroNode {
         this._value = value;
     }
     set textContent(text) {
-        MutationObserver.record({
-            target: this,
-            type: "characterData" /* MutationRecordType.CHARACTER_DATA */,
-            oldValue: this._value
-        });
+        if (MutationObserver.hasObservers) {
+            MutationObserver.record({
+                target: this,
+                type: "characterData" /* MutationRecordType.CHARACTER_DATA */,
+                oldValue: this._value
+            });
+        }
         this._value = text;
         this.delegateTextUpdate(text);
     }
@@ -32,7 +34,12 @@ class TaroText extends TaroNode {
     get data() {
         return this._value;
     }
-    /** Delegates the logical value after its mutation record; hosts can replace template payload preparation. */
+    /**
+     * Taro 已记录 characterData mutation 并写入 _value，text 是更新后的逻辑文本。
+     * textContent、nodeValue 和 data setter 共用此入口；构造时的初值由节点创建路径处理。
+     * 默认实现准备文本 v 路径的模板 payload；原生 host 可直接更新对应原生文本节点，
+     * 保持逻辑文本值、节点身份和 mutation 记录仍由 Taro 管理。
+     */
     delegateTextUpdate(text) {
         this.enqueueUpdate({
             path: `${this._path}.${"v" /* Shortcuts.Text */}`,