@feng3d/reactivity 1.0.5 → 1.0.7

package/dist/index.js

@@ -6,33 +6,42 @@ class Reactivity {
    * 获取当前节点值。
    *
    * 取值时将会建立与父节点的依赖关系。
+   * 当其他响应式节点访问此值时，会自动建立依赖关系。
    */
   get value() {
     this.track();
     return this._value;
   }
   /**
-   * 捕捉。
+   * 建立依赖关系。
    *
-   * 建立与父节点的依赖关系。
+   * 当其他节点访问当前节点的值时，会调用此方法。
+   * 将当前节点与访问者（父节点）建立依赖关系。
+   *
+   * 如果当前没有活动的响应式节点，或者不应该跟踪依赖，则不会建立依赖关系。
    */
   track() {
-    if (!Reactivity.activeReactivity || !_shouldTrack)
-      return;
+    if (!Reactivity.activeReactivity || !_shouldTrack) return;
     const parent = Reactivity.activeReactivity;
     if (parent) {
       this._parents.set(parent, parent._version);
     }
   }
   /**
-   * 触发。
+   * 触发更新。
+   *
+   * 当节点值发生变化时，会调用此方法。
+   * 通知所有依赖此节点的父节点进行更新。
    *
-   * 冒泡到所有父节点，设置失效子节点字典。
+   * 更新过程：
+   * 1. 遍历所有父节点
+   * 2. 检查父节点的版本号是否匹配
+   * 3. 触发父节点的更新
+   * 4. 将当前节点添加到父节点的失效子节点集合中
    */
   trigger() {
     this._parents.forEach((version, parent) => {
-      if (parent._version !== version)
-        return;
+      if (parent._version !== version) return;
       parent.trigger();
       parent._children.set(this, this._value);
     });
@@ -95,8 +104,9 @@ function computed(func) {
 }
 class ComputedReactivity extends Reactivity {
   /**
-   * 创建计算依赖。
-   * @param func 检测的可能包含响应式的函数。
+   * 创建计算反应式节点。
+   *
+   * @param func 计算函数，可以访问其他响应式数据，并返回计算结果
    */
   constructor(func) {
     super();
@@ -107,11 +117,12 @@ class ComputedReactivity extends Reactivity {
     this._func = func;
   }
   /**
-   * 获取值。
+   * 获取计算属性的值。
    *
-   * 取值时将会建立与父节点的依赖关系。
-   *
-   * 同时会检查子节点是否发生变化，如果发生变化，则重新计算。
+   * 取值时会：
+   * 1. 检查是否需要重新计算
+   * 2. 建立与父节点的依赖关系
+   * 3. 返回当前值
    */
   get value() {
     this.runIfDirty();
@@ -119,11 +130,11 @@ class ComputedReactivity extends Reactivity {
     return this._value;
   }
   /**
-   * 触发。
+   * 触发更新。
    *
-   * 冒泡到所有父节点，设置失效子节点字典。
-   *
-   * 把触发节点添加到失效子节点字典队列中。
+   * 当依赖发生变化时，会调用此方法。
+   * 如果当前正在执行计算，会将更新延迟到计算完成后。
+   * 否则，立即通知所有父节点进行更新。
    */
   trigger() {
     if (Reactivity.activeReactivity === this) {
@@ -132,7 +143,14 @@ class ComputedReactivity extends Reactivity {
     super.trigger();
   }
   /**
-   * 执行当前节点。
+   * 执行计算。
+   *
+   * 执行计算函数，更新当前值。
+   * 在计算过程中会：
+   * 1. 强制启用依赖跟踪
+   * 2. 保存并设置当前活动节点
+   * 3. 执行计算函数
+   * 4. 恢复活动节点
    */
   run() {
     forceTrack(() => {
@@ -144,9 +162,13 @@ class ComputedReactivity extends Reactivity {
     });
   }
   /**
-   * 检查当前节点是否脏。
+   * 检查并执行计算。
+   *
+   * 检查当前节点是否需要重新计算：
+   * 1. 如果脏标记为 true，需要重新计算
+   * 2. 如果子节点发生变化，需要重新计算
    *
-   * 如果脏，则执行计算。
+   * 重新计算后会清除脏标记。
    */
   runIfDirty() {
     this._isDirty = this._isDirty || this.isChildrenChanged();
@@ -156,17 +178,26 @@ class ComputedReactivity extends Reactivity {
     }
   }
   /**
-   * 判断子节点是否发生变化。
+   * 检查子节点是否发生变化。
+   *
+   * 遍历所有子节点，检查它们的值是否发生变化。
+   * 如果发生变化，返回 true，否则返回 false。
+   *
+   * 在检查过程中会：
+   * 1. 临时禁用依赖跟踪
+   * 2. 检查每个子节点的值
+   * 3. 如果子节点没有变化，重新建立依赖关系
+   * 4. 清空子节点集合
+   *
+   * @returns 是否有子节点发生变化
    */
   isChildrenChanged() {
-    if (this._children.size === 0)
-      return false;
+    if (this._children.size === 0) return false;
     let isChanged = false;
     const preReactiveNode = Reactivity.activeReactivity;
     Reactivity.activeReactivity = null;
     this._children.forEach((value, node) => {
-      if (isChanged)
-        return;
+      if (isChanged) return;
       if (node.value !== value) {
         isChanged = true;
         return;
@@ -182,52 +213,6 @@ class ComputedReactivity extends Reactivity {
     return isChanged;
   }
 }
-function effect(fn) {
-  return new EffectReactivity(fn);
-}
-const _EffectReactivity = class _EffectReactivity2 extends ComputedReactivity {
-  constructor(func) {
-    super(func);
-    this._isEnable = true;
-    this.runIfDirty();
-  }
-  pause() {
-    this._isEnable = false;
-  }
-  resume() {
-    if (this._isEnable)
-      return;
-    this._isEnable = true;
-    if (_EffectReactivity2.pausedQueueEffects.has(this)) {
-      _EffectReactivity2.pausedQueueEffects.delete(this);
-      this.trigger();
-    }
-  }
-  trigger() {
-    batchRun(() => {
-      super.trigger();
-      if (this._isEnable) {
-        batch(this, Reactivity.activeReactivity === this);
-      } else {
-        _EffectReactivity2.pausedQueueEffects.add(this);
-      }
-    });
-  }
-  /**
-   * 执行当前节点。
-   *
-   * 当暂停时将会直接执行被包装的函数。
-   */
-  run() {
-    if (this._isEnable) {
-      super.run();
-    } else {
-      this._func(this._value);
-    }
-  }
-};
-_EffectReactivity.pausedQueueEffects = /* @__PURE__ */ new WeakSet();
-let EffectReactivity = _EffectReactivity;
 var ReactiveFlags = /* @__PURE__ */ ((ReactiveFlags2) => {
   ReactiveFlags2["IS_REACTIVE"] = "__v_isReactive";
   ReactiveFlags2["RAW"] = "__v_raw";
@@ -280,8 +265,7 @@ function targetTypeMap(rawType) {
   }
 }
 function getTargetType(value) {
-  if (!Object.isExtensible(value))
-    return TargetType.INVALID;
+  if (!Object.isExtensible(value)) return TargetType.INVALID;
   return targetTypeMap(toRawType(value));
 }
 const toTypeString = (value) => Object.prototype.toString.call(value);
@@ -296,10 +280,231 @@ function toRaw(observed) {
 // @__NO_SIDE_EFFECTS__
 function makeMap(str) {
   const map = /* @__PURE__ */ Object.create(null);
-  for (const key of str.split(","))
-    map[key] = 1;
+  for (const key of str.split(",")) map[key] = 1;
   return (val) => val in map;
 }
+let activeEffectScope;
+class EffectScope {
+  /**
+   * 构造函数
+   * @param detached 是否创建分离的作用域
+   */
+  constructor(detached = false) {
+    this.detached = detached;
+    this._active = true;
+    this._on = 0;
+    this.effects = [];
+    this.cleanups = [];
+    this._isPaused = false;
+    this.parent = activeEffectScope;
+    if (!detached && activeEffectScope) {
+      this.index = (activeEffectScope.scopes || (activeEffectScope.scopes = [])).push(
+        this
+      ) - 1;
+    }
+  }
+  /**
+   * 获取作用域是否处于活动状态
+   */
+  get active() {
+    return this._active;
+  }
+  /**
+   * 暂停作用域
+   *
+   * 暂停当前作用域及其所有子作用域和效果
+   */
+  pause() {
+    if (this._active) {
+      this._isPaused = true;
+      let i, l;
+      if (this.scopes) {
+        for (i = 0, l = this.scopes.length; i < l; i++) {
+          this.scopes[i].pause();
+        }
+      }
+      for (i = 0, l = this.effects.length; i < l; i++) {
+        this.effects[i].pause();
+      }
+    }
+  }
+  /**
+   * 恢复作用域
+   *
+   * 恢复当前作用域及其所有子作用域和效果
+   */
+  resume() {
+    if (this._active) {
+      if (this._isPaused) {
+        this._isPaused = false;
+        let i, l;
+        if (this.scopes) {
+          for (i = 0, l = this.scopes.length; i < l; i++) {
+            this.scopes[i].resume();
+          }
+        }
+        for (i = 0, l = this.effects.length; i < l; i++) {
+          this.effects[i].resume();
+        }
+      }
+    }
+  }
+  /**
+   * 在作用域中运行函数
+   * @param fn 要运行的函数
+   * @returns 函数的返回值
+   */
+  run(fn) {
+    if (this._active) {
+      const currentEffectScope = activeEffectScope;
+      try {
+        activeEffectScope = this;
+        return fn();
+      } finally {
+        activeEffectScope = currentEffectScope;
+      }
+    }
+  }
+  /**
+   * 激活作用域
+   * 仅应在非分离的作用域上调用
+   * @internal
+   */
+  on() {
+    if (++this._on === 1) {
+      this.prevScope = activeEffectScope;
+      activeEffectScope = this;
+    }
+  }
+  /**
+   * 停用作用域
+   * 仅应在非分离的作用域上调用
+   * @internal
+   */
+  off() {
+    if (this._on > 0 && --this._on === 0) {
+      activeEffectScope = this.prevScope;
+      this.prevScope = void 0;
+    }
+  }
+  /**
+   * 停止作用域
+   *
+   * 停止当前作用域及其所有子作用域和效果，并执行清理函数
+   * @param fromParent 是否由父作用域调用
+   */
+  stop(fromParent) {
+    if (this._active) {
+      this._active = false;
+      let i, l;
+      for (i = 0, l = this.effects.length; i < l; i++) {
+        this.effects[i].stop();
+      }
+      this.effects.length = 0;
+      for (i = 0, l = this.cleanups.length; i < l; i++) {
+        this.cleanups[i]();
+      }
+      this.cleanups.length = 0;
+      if (this.scopes) {
+        for (i = 0, l = this.scopes.length; i < l; i++) {
+          this.scopes[i].stop(true);
+        }
+        this.scopes.length = 0;
+      }
+      if (!this.detached && this.parent && !fromParent) {
+        const last = this.parent.scopes.pop();
+        if (last && last !== this) {
+          this.parent.scopes[this.index] = last;
+          last.index = this.index;
+        }
+      }
+      this.parent = void 0;
+    }
+  }
+}
+function effectScope(detached) {
+  return new EffectScope(detached);
+}
+function getCurrentScope() {
+  return activeEffectScope;
+}
+function onScopeDispose(fn, failSilently = false) {
+  if (activeEffectScope) {
+    activeEffectScope.cleanups.push(fn);
+  }
+}
+function effect(fn) {
+  return new EffectReactivity(fn);
+}
+const _EffectReactivity = class _EffectReactivity extends ComputedReactivity {
+  constructor(func) {
+    super(func);
+    this._isEnable = true;
+    if (activeEffectScope && activeEffectScope.active) {
+      activeEffectScope.effects.push(this);
+    }
+    this.runIfDirty();
+  }
+  /**
+   * 暂停效果。
+   *
+   * 暂停后，当依赖发生变化时不会自动执行。
+   */
+  pause() {
+    this._isEnable = false;
+  }
+  /**
+   * 恢复效果。
+   *
+   * 恢复后，当依赖发生变化时会自动执行。
+   */
+  resume() {
+    if (this._isEnable) return;
+    this._isEnable = true;
+    if (_EffectReactivity.pausedQueueEffects.has(this)) {
+      _EffectReactivity.pausedQueueEffects.delete(this);
+      this.trigger();
+    }
+  }
+  /**
+   * 停止效果。
+   *
+   * 停止后，效果将不再响应依赖的变化。
+   */
+  stop() {
+    this._isEnable = false;
+    _EffectReactivity.pausedQueueEffects.delete(this);
+  }
+  /**
+   * 触发效果执行。
+   *
+   * 当依赖发生变化时，会调用此方法。
+   */
+  trigger() {
+    batchRun(() => {
+      super.trigger();
+      if (this._isEnable) {
+        batch(this, Reactivity.activeReactivity === this);
+      } else {
+        _EffectReactivity.pausedQueueEffects.add(this);
+      }
+    });
+  }
+  /**
+   * 执行当前节点。
+   *
+   * 当暂停时将会直接执行被包装的函数。
+   */
+  run() {
+    if (this._isEnable) {
+      super.run();
+    } else {
+      this._func(this._value);
+    }
+  }
+};
+_EffectReactivity.pausedQueueEffects = /* @__PURE__ */ new WeakSet();
+let EffectReactivity = _EffectReactivity;
 function property(target, key) {
   let depsMap = PropertyReactivity._targetMap.get(target);
   if (!depsMap) {
@@ -313,19 +518,7 @@ function property(target, key) {
   }
   return dep;
 }
-class PropertyReactivity extends Reactivity {
-  constructor(target, key) {
-    super();
-    this._target = target;
-    this._key = key;
-    if (target instanceof Map || target instanceof WeakMap) {
-      this._value = target.get(key);
-    } else if (target instanceof Set || target instanceof WeakSet) {
-      this._value = target.has(key);
-    } else {
-      this._value = target[key];
-    }
-  }
+const _PropertyReactivity = class _PropertyReactivity extends Reactivity {
   /**
    * 获取当前节点值。
    *
@@ -341,11 +534,22 @@ class PropertyReactivity extends Reactivity {
     } else if (isSymbol(this._key)) {
       v = ~~this._value + 1;
     }
-    if (v === this._value)
-      return;
+    if (v === this._value) return;
     this.trigger();
     this._value = v;
   }
+  constructor(target, key) {
+    super();
+    this._target = target;
+    this._key = key;
+    if (target instanceof Map || target instanceof WeakMap) {
+      this._value = target.get(key);
+    } else if (target instanceof Set || target instanceof WeakSet) {
+      this._value = target.has(key);
+    } else {
+      this._value = target[key];
+    }
+  }
   triggerIfChanged() {
   }
   /**
@@ -358,8 +562,7 @@ class PropertyReactivity extends Reactivity {
    * @returns
    */
   static track(target, type, key) {
-    if (!Reactivity.activeReactivity)
-      return;
+    if (!Reactivity.activeReactivity) return;
     const dep = property(target, key);
     dep.track();
   }
@@ -375,8 +578,7 @@ class PropertyReactivity extends Reactivity {
    */
   static trigger(target, type, key, newValue, oldValue) {
     const depsMap = this._targetMap.get(target);
-    if (!depsMap)
-      return;
+    if (!depsMap) return;
     const run = (dep) => {
       if (dep) {
         dep.value = newValue;
@@ -431,18 +633,34 @@ class PropertyReactivity extends Reactivity {
       }
     });
   }
-}
-PropertyReactivity._targetMap = /* @__PURE__ */ new WeakMap();
+};
+_PropertyReactivity._targetMap = /* @__PURE__ */ new WeakMap();
+let PropertyReactivity = _PropertyReactivity;
 const arrayInstrumentations = {
   __proto__: null,
   /**
-   * 返回一个迭代器，用于遍历数组的响应式值
+   * 返回一个迭代器，用于遍历数组的响应式值。
+   *
+   * 实现了以下功能：
+   * 1. 创建数组的迭代器
+   * 2. 自动将迭代的值转换为响应式
+   * 3. 自动追踪数组的访问
+   *
+   * @returns 数组的迭代器
    */
   [Symbol.iterator]() {
     return iterator(this, Symbol.iterator, toReactive);
   },
   /**
-   * 连接数组并返回新数组，处理响应式数组
+   * 连接数组并返回新数组。
+   *
+   * 实现了以下功能：
+   * 1. 处理响应式数组的连接
+   * 2. 自动将参数中的数组转换为响应式
+   * 3. 保持原始值的引用
+   *
+   * @param args 要连接的数组或值
+   * @returns 连接后的新数组
    */
   concat(...args) {
     return reactiveReadArray(this).concat(
@@ -450,7 +668,14 @@ const arrayInstrumentations = {
     );
   },
   /**
-   * 返回一个迭代器，用于遍历数组的键值对，并将值转换为响应式
+   * 返回一个迭代器，用于遍历数组的键值对。
+   *
+   * 实现了以下功能：
+   * 1. 创建数组的键值对迭代器
+   * 2. 自动将值转换为响应式
+   * 3. 自动追踪数组的访问
+   *
+   * @returns 数组的键值对迭代器
    */
   entries() {
     return iterator(this, "entries", (value) => {
@@ -459,148 +684,357 @@ const arrayInstrumentations = {
     });
   },
   /**
-   * 测试数组中的所有元素是否都通过了指定函数的测试
+   * 测试数组中的所有元素是否都通过了指定函数的测试。
+   *
+   * 实现了以下功能：
+   * 1. 遍历数组元素
+   * 2. 对每个元素执行测试函数
+   * 3. 自动追踪数组的访问
+   * 4. 处理响应式值的测试
+   *
+   * @param fn 测试函数
+   * @param thisArg 测试函数的 this 值
+   * @returns 如果所有元素都通过测试则返回 true，否则返回 false
    */
   every(fn, thisArg) {
     return apply(this, "every", fn, thisArg, void 0, arguments);
   },
   /**
-   * 创建一个新数组，包含通过指定函数测试的所有元素
+   * 创建一个新数组，包含通过指定函数测试的所有元素。
+   *
+   * 实现了以下功能：
+   * 1. 遍历数组元素
+   * 2. 对每个元素执行测试函数
+   * 3. 自动追踪数组的访问
+   * 4. 自动将结果转换为响应式
+   *
+   * @param fn 测试函数
+   * @param thisArg 测试函数的 this 值
+   * @returns 包含通过测试的元素的新数组
    */
   filter(fn, thisArg) {
     return apply(this, "filter", fn, thisArg, (v) => v.map(toReactive), arguments);
   },
   /**
-   * 返回数组中满足指定测试函数的第一个元素
+   * 返回数组中满足指定测试函数的第一个元素。
+   *
+   * 实现了以下功能：
+   * 1. 遍历数组元素
+   * 2. 对每个元素执行测试函数
+   * 3. 自动追踪数组的访问
+   * 4. 自动将结果转换为响应式
+   *
+   * @param fn 测试函数
+   * @param thisArg 测试函数的 this 值
+   * @returns 第一个满足测试的元素，如果没有则返回 undefined
    */
   find(fn, thisArg) {
     return apply(this, "find", fn, thisArg, toReactive, arguments);
   },
   /**
-   * 返回数组中满足指定测试函数的第一个元素的索引
+   * 返回数组中满足指定测试函数的第一个元素的索引。
+   *
+   * 实现了以下功能：
+   * 1. 遍历数组元素
+   * 2. 对每个元素执行测试函数
+   * 3. 自动追踪数组的访问
+   * 4. 处理响应式值的查找
+   *
+   * @param fn 测试函数
+   * @param thisArg 测试函数的 this 值
+   * @returns 第一个满足测试的元素的索引，如果没有则返回 -1
    */
   findIndex(fn, thisArg) {
     return apply(this, "findIndex", fn, thisArg, void 0, arguments);
   },
   /**
-   * 返回数组中满足指定测试函数的最后一个元素
+   * 返回数组中满足指定测试函数的最后一个元素。
+   *
+   * 实现了以下功能：
+   * 1. 从后向前遍历数组元素
+   * 2. 对每个元素执行测试函数
+   * 3. 自动追踪数组的访问
+   * 4. 自动将结果转换为响应式
+   *
+   * @param fn 测试函数
+   * @param thisArg 测试函数的 this 值
+   * @returns 最后一个满足测试的元素，如果没有则返回 undefined
    */
   findLast(fn, thisArg) {
     return apply(this, "findLast", fn, thisArg, toReactive, arguments);
   },
   /**
-   * 返回数组中满足指定测试函数的最后一个元素的索引
+   * 返回数组中满足指定测试函数的最后一个元素的索引。
+   *
+   * 实现了以下功能：
+   * 1. 从后向前遍历数组元素
+   * 2. 对每个元素执行测试函数
+   * 3. 自动追踪数组的访问
+   * 4. 处理响应式值的查找
+   *
+   * @param fn 测试函数
+   * @param thisArg 测试函数的 this 值
+   * @returns 最后一个满足测试的元素的索引，如果没有则返回 -1
    */
   findLastIndex(fn, thisArg) {
     return apply(this, "findLastIndex", fn, thisArg, void 0, arguments);
   },
-  // flat, flatMap could benefit from ARRAY_ITERATE but are not straight-forward to implement
+  // flat, flatMap 可以从 ARRAY_ITERATE 中受益，但实现起来不太直接
   /**
-   * 对数组中的每个元素执行指定函数
+   * 对数组中的每个元素执行指定函数。
+   *
+   * 实现了以下功能：
+   * 1. 遍历数组元素
+   * 2. 对每个元素执行回调函数
+   * 3. 自动追踪数组的访问
+   * 4. 处理响应式值的遍历
+   *
+   * @param fn 回调函数
+   * @param thisArg 回调函数的 this 值
    */
   forEach(fn, thisArg) {
     return apply(this, "forEach", fn, thisArg, void 0, arguments);
   },
   /**
-   * 判断数组是否包含指定元素，处理响应式值
+   * 判断数组是否包含指定元素。
+   *
+   * 实现了以下功能：
+   * 1. 处理响应式值的查找
+   * 2. 自动追踪数组的访问
+   * 3. 处理代理对象的查找
+   *
+   * @param args 要查找的元素
+   * @returns 如果数组包含该元素则返回 true，否则返回 false
    */
   includes(...args) {
     return searchProxy(this, "includes", args);
   },
   /**
-   * 返回数组中指定元素第一次出现的索引，处理响应式值
+   * 返回数组中指定元素第一次出现的索引。
+   *
+   * 实现了以下功能：
+   * 1. 处理响应式值的查找
+   * 2. 自动追踪数组的访问
+   * 3. 处理代理对象的查找
+   *
+   * @param args 要查找的元素
+   * @returns 元素第一次出现的索引，如果没有则返回 -1
    */
   indexOf(...args) {
     return searchProxy(this, "indexOf", args);
   },
   /**
-   * 将数组的所有元素连接成一个字符串
+   * 将数组的所有元素连接成一个字符串。
+   *
+   * 实现了以下功能：
+   * 1. 处理响应式数组的连接
+   * 2. 自动追踪数组的访问
+   * 3. 保持原始值的引用
+   *
+   * @param separator 分隔符
+   * @returns 连接后的字符串
    */
   join(separator) {
     return reactiveReadArray(this).join(separator);
   },
-  // keys() iterator only reads `length`, no optimisation required
+  // keys() 迭代器只读取 length，不需要优化
   /**
-   * 返回数组中指定元素最后一次出现的索引，处理响应式值
+   * 返回数组中指定元素最后一次出现的索引。
+   *
+   * 实现了以下功能：
+   * 1. 处理响应式值的查找
+   * 2. 自动追踪数组的访问
+   * 3. 处理代理对象的查找
+   *
+   * @param args 要查找的元素
+   * @returns 元素最后一次出现的索引，如果没有则返回 -1
    */
   lastIndexOf(...args) {
     return searchProxy(this, "lastIndexOf", args);
   },
   /**
-   * 创建一个新数组，包含对原数组每个元素调用指定函数的结果
+   * 创建一个新数组，包含对原数组每个元素调用指定函数的结果。
+   *
+   * 实现了以下功能：
+   * 1. 遍历数组元素
+   * 2. 对每个元素执行映射函数
+   * 3. 自动追踪数组的访问
+   * 4. 处理响应式值的映射
+   *
+   * @param fn 映射函数
+   * @param thisArg 映射函数的 this 值
+   * @returns 包含映射结果的新数组
    */
   map(fn, thisArg) {
     return apply(this, "map", fn, thisArg, void 0, arguments);
   },
   /**
-   * 移除数组的最后一个元素并返回该元素，避免跟踪长度变化
+   * 移除数组的最后一个元素并返回该元素。
+   *
+   * 实现了以下功能：
+   * 1. 移除最后一个元素
+   * 2. 避免跟踪长度变化
+   * 3. 处理响应式值的移除
+   *
+   * @returns 被移除的元素
    */
   pop() {
     return noTracking(this, "pop");
   },
   /**
-   * 向数组末尾添加一个或多个元素，并返回新的长度，避免跟踪长度变化
+   * 向数组末尾添加一个或多个元素。
+   *
+   * 实现了以下功能：
+   * 1. 添加新元素
+   * 2. 避免跟踪长度变化
+   * 3. 处理响应式值的添加
+   *
+   * @param args 要添加的元素
+   * @returns 数组的新长度
    */
   push(...args) {
     return noTracking(this, "push", args);
   },
   /**
-   * 对数组中的每个元素执行累加器函数，并返回最终结果
+   * 对数组中的每个元素执行累加器函数。
+   *
+   * 实现了以下功能：
+   * 1. 从左到右遍历数组元素
+   * 2. 对每个元素执行累加器函数
+   * 3. 自动追踪数组的访问
+   * 4. 处理响应式值的累加
+   *
+   * @param fn 累加器函数
+   * @param args 初始值（可选）
+   * @returns 累加的结果
    */
   reduce(fn, ...args) {
     return reduce(this, "reduce", fn, args);
   },
   /**
-   * 从右到左对数组中的每个元素执行累加器函数，并返回最终结果
+   * 从右到左对数组中的每个元素执行累加器函数。
+   *
+   * 实现了以下功能：
+   * 1. 从右到左遍历数组元素
+   * 2. 对每个元素执行累加器函数
+   * 3. 自动追踪数组的访问
+   * 4. 处理响应式值的累加
+   *
+   * @param fn 累加器函数
+   * @param args 初始值（可选）
+   * @returns 累加的结果
    */
   reduceRight(fn, ...args) {
     return reduce(this, "reduceRight", fn, args);
   },
   /**
-   * 移除数组的第一个元素并返回该元素，避免跟踪长度变化
+   * 移除数组的第一个元素并返回该元素。
+   *
+   * 实现了以下功能：
+   * 1. 移除第一个元素
+   * 2. 避免跟踪长度变化
+   * 3. 处理响应式值的移除
+   *
+   * @returns 被移除的元素
    */
   shift() {
     return noTracking(this, "shift");
   },
-  // slice could use ARRAY_ITERATE but also seems to beg for range tracking
+  // slice 可以使用 ARRAY_ITERATE，但似乎也需要范围追踪
   /**
-   * 测试数组中的某些元素是否通过了指定函数的测试
+   * 测试数组中的某些元素是否通过了指定函数的测试。
+   *
+   * 实现了以下功能：
+   * 1. 遍历数组元素
+   * 2. 对每个元素执行测试函数
+   * 3. 自动追踪数组的访问
+   * 4. 处理响应式值的测试
+   *
+   * @param fn 测试函数
+   * @param thisArg 测试函数的 this 值
+   * @returns 如果有元素通过测试则返回 true，否则返回 false
    */
   some(fn, thisArg) {
     return apply(this, "some", fn, thisArg, void 0, arguments);
   },
   /**
-   * 通过删除或替换现有元素或添加新元素来修改数组，避免跟踪长度变化
+   * 通过删除或替换现有元素或添加新元素来修改数组。
+   *
+   * 实现了以下功能：
+   * 1. 修改数组内容
+   * 2. 避免跟踪长度变化
+   * 3. 处理响应式值的修改
+   *
+   * @param args 要删除的起始索引、要删除的元素数量和要添加的元素
+   * @returns 包含被删除元素的新数组
    */
   splice(...args) {
     return noTracking(this, "splice", args);
   },
   /**
-   * 返回一个新数组，包含原数组的反转副本
+   * 返回一个新数组，包含原数组的反转副本。
+   *
+   * 实现了以下功能：
+   * 1. 创建数组的反转副本
+   * 2. 自动将结果转换为响应式
+   * 3. 保持原始值的引用
+   *
+   * @returns 反转后的新数组
    */
   toReversed() {
     return reactiveReadArray(this).toReversed();
   },
   /**
-   * 返回一个新数组，包含原数组的排序副本
+   * 返回一个新数组，包含原数组的排序副本。
+   *
+   * 实现了以下功能：
+   * 1. 创建数组的排序副本
+   * 2. 自动将结果转换为响应式
+   * 3. 保持原始值的引用
+   *
+   * @param comparer 比较函数
+   * @returns 排序后的新数组
    */
   toSorted(comparer) {
     return reactiveReadArray(this).toSorted(comparer);
   },
   /**
-   * 返回一个新数组，包含原数组的切片副本
+   * 返回一个新数组，包含原数组的切片副本。
+   *
+   * 实现了以下功能：
+   * 1. 创建数组的切片副本
+   * 2. 自动将结果转换为响应式
+   * 3. 保持原始值的引用
+   *
+   * @param args 起始索引和结束索引
+   * @returns 切片后的新数组
    */
   toSpliced(...args) {
     return reactiveReadArray(this).toSpliced(...args);
   },
   /**
-   * 向数组开头添加一个或多个元素，并返回新的长度，避免跟踪长度变化
+   * 向数组开头添加一个或多个元素。
+   *
+   * 实现了以下功能：
+   * 1. 添加新元素
+   * 2. 避免跟踪长度变化
+   * 3. 处理响应式值的添加
+   *
+   * @param args 要添加的元素
+   * @returns 数组的新长度
    */
   unshift(...args) {
     return noTracking(this, "unshift", args);
   },
   /**
-   * 返回一个迭代器，用于遍历数组的响应式值
+   * 返回一个迭代器，用于遍历数组的值。
+   *
+   * 实现了以下功能：
+   * 1. 创建数组的值迭代器
+   * 2. 自动将迭代的值转换为响应式
+   * 3. 自动追踪数组的访问
+   *
+   * @returns 数组的值迭代器
    */
   values() {
     return iterator(this, "values", toReactive);
@@ -627,8 +1061,7 @@ function shallowReadArray(arr) {
 }
 function reactiveReadArray(array) {
   const raw = toRaw(array);
-  if (raw === array)
-    return raw;
+  if (raw === array) return raw;
   PropertyReactivity.track(raw, TrackOpTypes.ITERATE, ARRAY_ITERATE_KEY);
   return raw.map(toReactive);
 }
@@ -683,7 +1116,7 @@ function noTracking(self, method, args = []) {
   );
   return res;
 }
-var _a;
+var _a, _b;
 function ref(value) {
   if (isRef(value)) {
     return value;
@@ -693,22 +1126,45 @@ function ref(value) {
 function isRef(r) {
   return r ? r[ReactiveFlags.IS_REF] === true : false;
 }
-class RefReactivity extends Reactivity {
+class RefReactivity extends (_b = Reactivity, _a = ReactiveFlags.IS_REF, _b) {
+  /**
+   * 创建引用反应式节点。
+   *
+   * @param value 要包装的值
+   */
   constructor(value) {
     super();
     this[_a] = true;
     this._rawValue = toRaw(value);
     this._value = toReactive(value);
   }
+  /**
+   * 获取引用的值。
+   *
+   * 取值时会：
+   * 1. 建立依赖关系
+   * 2. 返回当前值
+   */
   get value() {
     this.track();
     return this._value;
   }
+  /**
+   * 设置引用的值。
+   *
+   * 设置值时会：
+   * 1. 比较新旧值是否发生变化
+   * 2. 如果值发生变化，则：
+   *    - 触发更新通知
+   *    - 更新原始值
+   *    - 更新响应式值
+   *
+   * @param v 要设置的新值
+   */
   set value(v) {
     const oldValue = this._rawValue;
     const newValue = toRaw(v);
-    if (!hasChanged(oldValue, newValue))
-      return;
+    if (!hasChanged(oldValue, newValue)) return;
     batchRun(() => {
       this.trigger();
       this._rawValue = newValue;
@@ -716,15 +1172,22 @@ class RefReactivity extends Reactivity {
     });
   }
 }
-_a = ReactiveFlags.IS_REF;
 class BaseReactiveHandler {
   /**
    * 获取对象的属性值。
    *
-   * @param target 对象本身
-   * @param key 属性名
-   * @param receiver 代理对象
-   * @returns
+   * 实现了以下功能：
+   * 1. 响应式对象标识检查
+   * 2. 原始对象获取
+   * 3. 数组方法拦截
+   * 4. 属性依赖追踪
+   * 5. 值的自动解包
+   * 6. 对象的自动响应式转换
+   *
+   * @param target 被代理的原始对象
+   * @param key 要获取的属性名
+   * @param receiver 代理对象本身
+   * @returns 获取到的属性值
    */
   get(target, key, receiver) {
     if (key === ReactiveFlags.IS_REACTIVE) {
@@ -764,11 +1227,18 @@ class BaseReactiveHandler {
 class MutableReactiveHandler extends BaseReactiveHandler {
   /**
    * 设置对象的属性值。
-   * @param target 被代理的对象。
-   * @param key 属性名。
-   * @param value 新值。
-   * @param receiver 代理对象。
-   * @returns 设置是否成功。
+   *
+   * 实现了以下功能：
+   * 1. 值的原始化处理
+   * 2. ref 值的特殊处理
+   * 3. 属性变更通知
+   * 4. 数组长度的特殊处理
+   *
+   * @param target 被代理的原始对象
+   * @param key 要设置的属性名
+   * @param value 要设置的新值
+   * @param receiver 代理对象本身
+   * @returns 设置是否成功
    */
   set(target, key, value, receiver) {
     let oldValue = target[key];
@@ -797,9 +1267,13 @@ class MutableReactiveHandler extends BaseReactiveHandler {
   /**
    * 删除对象的属性。
    *
-   * @param target 被代理的对象。
-   * @param key 属性名。
-   * @returns 删除是否成功。
+   * 实现了以下功能：
+   * 1. 属性删除操作
+   * 2. 删除后的变更通知
+   *
+   * @param target 被代理的原始对象
+   * @param key 要删除的属性名
+   * @returns 删除是否成功
    */
   deleteProperty(target, key) {
     const hadKey = hasOwn(target, key);
@@ -810,6 +1284,17 @@ class MutableReactiveHandler extends BaseReactiveHandler {
     }
     return result;
   }
+  /**
+   * 检查对象是否包含某个属性。
+   *
+   * 实现了以下功能：
+   * 1. 属性存在性检查
+   * 2. 属性访问依赖追踪
+   *
+   * @param target 被代理的原始对象
+   * @param key 要检查的属性名
+   * @returns 属性是否存在
+   */
   has(target, key) {
     const result = Reflect.has(target, key);
     if (!isSymbol(key) || !builtInSymbols.has(key)) {
@@ -817,6 +1302,16 @@ class MutableReactiveHandler extends BaseReactiveHandler {
     }
     return result;
   }
+  /**
+   * 获取对象的所有属性名。
+   *
+   * 实现了以下功能：
+   * 1. 属性遍历
+   * 2. 遍历操作的依赖追踪
+   *
+   * @param target 被代理的原始对象
+   * @returns 对象的所有属性名数组
+   */
   ownKeys(target) {
     PropertyReactivity.track(
       target,
@@ -828,8 +1323,7 @@ class MutableReactiveHandler extends BaseReactiveHandler {
 }
 const mutableHandlers = new MutableReactiveHandler();
 function hasOwnProperty(key) {
-  if (!isSymbol(key))
-    key = String(key);
+  if (!isSymbol(key)) key = String(key);
   const obj = toRaw(this);
   PropertyReactivity.track(obj, TrackOpTypes.HAS, key);
   return obj.hasOwnProperty(key);
@@ -858,6 +1352,17 @@ function createInstrumentationGetter() {
 }
 function createInstrumentations() {
   const instrumentations = {
+    /**
+     * 获取 Map 中的值。
+     *
+     * 实现了以下功能：
+     * 1. 支持原始键和响应式键的查找
+     * 2. 自动追踪键的访问
+     * 3. 自动将返回值转换为响应式
+     *
+     * @param key 要查找的键
+     * @returns 找到的值，如果不存在则返回 undefined
+     */
     get(key) {
       const target = this[ReactiveFlags.RAW];
       const rawTarget = toRaw(target);
@@ -876,11 +1381,28 @@ function createInstrumentations() {
         target.get(key);
       }
     },
+    /**
+     * 获取集合的大小。
+     *
+     * 实现了以下功能：
+     * 1. 追踪集合大小的访问
+     * 2. 返回集合的实际大小
+     */
     get size() {
       const target = this[ReactiveFlags.RAW];
       PropertyReactivity.track(toRaw(target), TrackOpTypes.ITERATE, ITERATE_KEY);
       return Reflect.get(target, "size", target);
     },
+    /**
+     * 检查集合是否包含某个值。
+     *
+     * 实现了以下功能：
+     * 1. 支持原始键和响应式键的检查
+     * 2. 自动追踪键的检查
+     *
+     * @param key 要检查的键
+     * @returns 如果集合包含该键则返回 true，否则返回 false
+     */
     has(key) {
       const target = this[ReactiveFlags.RAW];
       const rawTarget = toRaw(target);
@@ -891,6 +1413,17 @@ function createInstrumentations() {
       PropertyReactivity.track(rawTarget, TrackOpTypes.HAS, rawKey);
       return key === rawKey ? target.has(key) : target.has(key) || target.has(rawKey);
     },
+    /**
+     * 遍历集合中的所有元素。
+     *
+     * 实现了以下功能：
+     * 1. 追踪集合的遍历操作
+     * 2. 自动将遍历的值转换为响应式
+     * 3. 保持回调函数的 this 上下文
+     *
+     * @param callback 遍历回调函数
+     * @param thisArg 回调函数的 this 值
+     */
     forEach(callback, thisArg) {
       const observed = this;
       const target = observed[ReactiveFlags.RAW];
@@ -899,13 +1432,24 @@ function createInstrumentations() {
       PropertyReactivity.track(rawTarget, TrackOpTypes.ITERATE, ITERATE_KEY);
       return target.forEach(
         (value, key) => (
-          // important: make sure the callback is
-          // 1. invoked with the reactive map as `this` and 3rd arg
-          // 2. the value received should be a corresponding reactive/readonly.
+          // 重要：确保回调函数
+          // 1. 使用响应式 map 作为 this 和第三个参数
+          // 2. 接收到的值应该是相应的响应式/只读版本
           callback.call(thisArg, wrap(value), wrap(key), observed)
         )
       );
     },
+    /**
+     * 向 Set 中添加值。
+     *
+     * 实现了以下功能：
+     * 1. 自动将值转换为原始值
+     * 2. 避免重复添加
+     * 3. 触发添加操作的通知
+     *
+     * @param value 要添加的值
+     * @returns 集合本身，支持链式调用
+     */
     add(value) {
       value = toRaw(value);
       const target = toRaw(this);
@@ -917,6 +1461,18 @@ function createInstrumentations() {
       }
       return this;
     },
+    /**
+     * 设置 Map 中的值。
+     *
+     * 实现了以下功能：
+     * 1. 自动将值转换为原始值
+     * 2. 支持原始键和响应式键的设置
+     * 3. 触发添加或修改操作的通知
+     *
+     * @param key 要设置的键
+     * @param value 要设置的值
+     * @returns 集合本身，支持链式调用
+     */
     set(key, value) {
       value = toRaw(value);
       const target = toRaw(this);
@@ -935,6 +1491,16 @@ function createInstrumentations() {
       }
       return this;
     },
+    /**
+     * 从集合中删除值。
+     *
+     * 实现了以下功能：
+     * 1. 支持原始键和响应式键的删除
+     * 2. 触发删除操作的通知
+     *
+     * @param key 要删除的键
+     * @returns 如果删除成功则返回 true，否则返回 false
+     */
     delete(key) {
       const target = toRaw(this);
       const { has, get } = getProto(target);
@@ -950,6 +1516,16 @@ function createInstrumentations() {
       }
       return result;
     },
+    /**
+     * 清空集合。
+     *
+     * 实现了以下功能：
+     * 1. 清空集合中的所有元素
+     * 2. 触发清空操作的通知
+     * 3. 在开发模式下保存旧值用于调试
+     *
+     * @returns 如果清空成功则返回 true，否则返回 false
+     */
     clear() {
       const target = toRaw(this);
       const hadItems = target.size !== 0;
@@ -993,7 +1569,7 @@ function createIterableMethod(method) {
       isKeyOnly ? MAP_KEY_ITERATE_KEY : ITERATE_KEY
     );
     return {
-      // iterator protocol
+      // 迭代器协议
       next() {
         const { value, done } = innerIterator.next();
         return done ? { value, done } : {
@@ -1001,7 +1577,7 @@ function createIterableMethod(method) {
           done
         };
       },
-      // iterable protocol
+      // 可迭代协议
       [Symbol.iterator]() {
         return this;
       }
@@ -1045,18 +1621,18 @@ function isProxy(value) {
   return value ? !!value[ReactiveFlags.RAW] : false;
 }
 export {
-  ComputedReactivity as ComputedDep,
-  Reactivity as Dep,
-  EffectReactivity as EffectDep,
-  RefReactivity,
+  EffectScope,
   batchRun,
   computed,
   effect,
+  effectScope,
   forceTrack,
+  getCurrentScope,
   isProxy,
   isReactive,
   isRef,
   noTrack,
+  onScopeDispose,
   reactive,
   ref,
   toRaw