@feng3d/reactivity 1.0.5 → 1.0.7

package/src/arrayInstrumentations.ts

@@ -7,11 +7,28 @@ import { isProxy, toReactive } from './reactive';
 import { ARRAY_ITERATE_KEY, TrackOpTypes } from './shared/constants';
 import { isArray, toRaw } from './shared/general';
 
+/**
+ * 数组方法增强对象。
+ *
+ * 为数组提供响应式增强的方法实现，包括：
+ * 1. 迭代器方法：Symbol.iterator、entries、keys、values
+ * 2. 查找方法：includes、indexOf、lastIndexOf、find、findIndex、findLast、findLastIndex
+ * 3. 遍历方法：forEach、map、filter、some、every、reduce、reduceRight
+ * 4. 修改方法：push、pop、shift、unshift、splice、toReversed、toSorted、toSpliced
+ * 5. 其他方法：concat、join
+ */
 export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     __proto__: null,
 
     /**
-     * 返回一个迭代器，用于遍历数组的响应式值
+     * 返回一个迭代器，用于遍历数组的响应式值。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的迭代器
+     * 2. 自动将迭代的值转换为响应式
+     * 3. 自动追踪数组的访问
+     *
+     * @returns 数组的迭代器
      */
     [Symbol.iterator]()
     {
@@ -19,7 +36,15 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 连接数组并返回新数组，处理响应式数组
+     * 连接数组并返回新数组。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式数组的连接
+     * 2. 自动将参数中的数组转换为响应式
+     * 3. 保持原始值的引用
+     *
+     * @param args 要连接的数组或值
+     * @returns 连接后的新数组
      */
     concat(...args: unknown[])
     {
@@ -29,7 +54,14 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 返回一个迭代器，用于遍历数组的键值对，并将值转换为响应式
+     * 返回一个迭代器，用于遍历数组的键值对。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的键值对迭代器
+     * 2. 自动将值转换为响应式
+     * 3. 自动追踪数组的访问
+     *
+     * @returns 数组的键值对迭代器
      */
     entries()
     {
@@ -42,7 +74,17 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 测试数组中的所有元素是否都通过了指定函数的测试
+     * 测试数组中的所有元素是否都通过了指定函数的测试。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的测试
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 如果所有元素都通过测试则返回 true，否则返回 false
      */
     every(fn: (item: unknown, index: number, array: unknown[]) => unknown,
         thisArg?: unknown,
@@ -52,7 +94,17 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 创建一个新数组，包含通过指定函数测试的所有元素
+     * 创建一个新数组，包含通过指定函数测试的所有元素。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 自动将结果转换为响应式
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 包含通过测试的元素的新数组
      */
     filter(fn: (item: unknown, index: number, array: unknown[]) => unknown,
         thisArg?: unknown,
@@ -62,7 +114,17 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 返回数组中满足指定测试函数的第一个元素
+     * 返回数组中满足指定测试函数的第一个元素。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 自动将结果转换为响应式
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 第一个满足测试的元素，如果没有则返回 undefined
      */
     find(fn: (item: unknown, index: number, array: unknown[]) => boolean,
         thisArg?: unknown,
@@ -72,7 +134,17 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 返回数组中满足指定测试函数的第一个元素的索引
+     * 返回数组中满足指定测试函数的第一个元素的索引。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的查找
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 第一个满足测试的元素的索引，如果没有则返回 -1
      */
     findIndex(fn: (item: unknown, index: number, array: unknown[]) => boolean,
         thisArg?: unknown,
@@ -82,7 +154,17 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 返回数组中满足指定测试函数的最后一个元素
+     * 返回数组中满足指定测试函数的最后一个元素。
+     *
+     * 实现了以下功能：
+     * 1. 从后向前遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 自动将结果转换为响应式
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 最后一个满足测试的元素，如果没有则返回 undefined
      */
     findLast(fn: (item: unknown, index: number, array: unknown[]) => boolean,
         thisArg?: unknown,
@@ -92,7 +174,17 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 返回数组中满足指定测试函数的最后一个元素的索引
+     * 返回数组中满足指定测试函数的最后一个元素的索引。
+     *
+     * 实现了以下功能：
+     * 1. 从后向前遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的查找
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 最后一个满足测试的元素的索引，如果没有则返回 -1
      */
     findLastIndex(fn: (item: unknown, index: number, array: unknown[]) => boolean,
         thisArg?: unknown,
@@ -101,10 +193,19 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
         return apply(this, 'findLastIndex', fn, thisArg, undefined, 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: (item: unknown, index: number, array: unknown[]) => unknown,
         thisArg?: unknown,
@@ -114,15 +215,31 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 判断数组是否包含指定元素，处理响应式值
+     * 判断数组是否包含指定元素。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式值的查找
+     * 2. 自动追踪数组的访问
+     * 3. 处理代理对象的查找
+     *
+     * @param args 要查找的元素
+     * @returns 如果数组包含该元素则返回 true，否则返回 false
      */
     includes(...args: unknown[])
     {
-        return searchProxy(this, 'includes', args);
+        return searchProxy(this, 'includes' as any, args);
     },
 
     /**
-     * 返回数组中指定元素第一次出现的索引，处理响应式值
+     * 返回数组中指定元素第一次出现的索引。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式值的查找
+     * 2. 自动追踪数组的访问
+     * 3. 处理代理对象的查找
+     *
+     * @param args 要查找的元素
+     * @returns 元素第一次出现的索引，如果没有则返回 -1
      */
     indexOf(...args: unknown[])
     {
@@ -130,17 +247,33 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 将数组的所有元素连接成一个字符串
+     * 将数组的所有元素连接成一个字符串。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式数组的连接
+     * 2. 自动追踪数组的访问
+     * 3. 保持原始值的引用
+     *
+     * @param separator 分隔符
+     * @returns 连接后的字符串
      */
     join(separator?: string)
     {
         return reactiveReadArray(this).join(separator);
     },
 
-    // keys() iterator only reads `length`, no optimisation required
+    // keys() 迭代器只读取 length，不需要优化
 
     /**
-     * 返回数组中指定元素最后一次出现的索引，处理响应式值
+     * 返回数组中指定元素最后一次出现的索引。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式值的查找
+     * 2. 自动追踪数组的访问
+     * 3. 处理代理对象的查找
+     *
+     * @param args 要查找的元素
+     * @returns 元素最后一次出现的索引，如果没有则返回 -1
      */
     lastIndexOf(...args: unknown[])
     {
@@ -148,7 +281,17 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 创建一个新数组，包含对原数组每个元素调用指定函数的结果
+     * 创建一个新数组，包含对原数组每个元素调用指定函数的结果。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行映射函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的映射
+     *
+     * @param fn 映射函数
+     * @param thisArg 映射函数的 this 值
+     * @returns 包含映射结果的新数组
      */
     map(fn: (item: unknown, index: number, array: unknown[]) => unknown,
         thisArg?: unknown,
@@ -158,7 +301,14 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 移除数组的最后一个元素并返回该元素，避免跟踪长度变化
+     * 移除数组的最后一个元素并返回该元素。
+     *
+     * 实现了以下功能：
+     * 1. 移除最后一个元素
+     * 2. 避免跟踪长度变化
+     * 3. 处理响应式值的移除
+     *
+     * @returns 被移除的元素
      */
     pop()
     {
@@ -166,7 +316,15 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 向数组末尾添加一个或多个元素，并返回新的长度，避免跟踪长度变化
+     * 向数组末尾添加一个或多个元素。
+     *
+     * 实现了以下功能：
+     * 1. 添加新元素
+     * 2. 避免跟踪长度变化
+     * 3. 处理响应式值的添加
+     *
+     * @param args 要添加的元素
+     * @returns 数组的新长度
      */
     push(...args: unknown[])
     {
@@ -174,7 +332,17 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 对数组中的每个元素执行累加器函数，并返回最终结果
+     * 对数组中的每个元素执行累加器函数。
+     *
+     * 实现了以下功能：
+     * 1. 从左到右遍历数组元素
+     * 2. 对每个元素执行累加器函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的累加
+     *
+     * @param fn 累加器函数
+     * @param args 初始值（可选）
+     * @returns 累加的结果
      */
     reduce(fn: (
         acc: unknown,
@@ -182,14 +350,24 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
         index: number,
         array: unknown[],
     ) => unknown,
-        ...args: unknown[]
+    ...args: unknown[]
     )
     {
         return reduce(this, 'reduce', fn, args);
     },
 
     /**
-     * 从右到左对数组中的每个元素执行累加器函数，并返回最终结果
+     * 从右到左对数组中的每个元素执行累加器函数。
+     *
+     * 实现了以下功能：
+     * 1. 从右到左遍历数组元素
+     * 2. 对每个元素执行累加器函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的累加
+     *
+     * @param fn 累加器函数
+     * @param args 初始值（可选）
+     * @returns 累加的结果
      */
     reduceRight(
         fn: (
@@ -205,17 +383,34 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 移除数组的第一个元素并返回该元素，避免跟踪长度变化
+     * 移除数组的第一个元素并返回该元素。
+     *
+     * 实现了以下功能：
+     * 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: (item: unknown, index: number, array: unknown[]) => unknown,
@@ -226,7 +421,15 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 通过删除或替换现有元素或添加新元素来修改数组，避免跟踪长度变化
+     * 通过删除或替换现有元素或添加新元素来修改数组。
+     *
+     * 实现了以下功能：
+     * 1. 修改数组内容
+     * 2. 避免跟踪长度变化
+     * 3. 处理响应式值的修改
+     *
+     * @param args 要删除的起始索引、要删除的元素数量和要添加的元素
+     * @returns 包含被删除元素的新数组
      */
     splice(...args: unknown[])
     {
@@ -234,7 +437,14 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 返回一个新数组，包含原数组的反转副本
+     * 返回一个新数组，包含原数组的反转副本。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的反转副本
+     * 2. 自动将结果转换为响应式
+     * 3. 保持原始值的引用
+     *
+     * @returns 反转后的新数组
      */
     toReversed()
     {
@@ -243,7 +453,15 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 返回一个新数组，包含原数组的排序副本
+     * 返回一个新数组，包含原数组的排序副本。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的排序副本
+     * 2. 自动将结果转换为响应式
+     * 3. 保持原始值的引用
+     *
+     * @param comparer 比较函数
+     * @returns 排序后的新数组
      */
     toSorted(comparer?: (a: unknown, b: unknown) => number)
     {
@@ -252,16 +470,32 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 返回一个新数组，包含原数组的切片副本
+     * 返回一个新数组，包含原数组的切片副本。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的切片副本
+     * 2. 自动将结果转换为响应式
+     * 3. 保持原始值的引用
+     *
+     * @param args 起始索引和结束索引
+     * @returns 切片后的新数组
      */
     toSpliced(...args: unknown[])
     {
         // @ts-expect-error user code may run in es2016+
-        return (reactiveReadArray(this).toSpliced as any)(...args);
+        return reactiveReadArray(this).toSpliced(...args);
     },
 
     /**
-     * 向数组开头添加一个或多个元素，并返回新的长度，避免跟踪长度变化
+     * 向数组开头添加一个或多个元素。
+     *
+     * 实现了以下功能：
+     * 1. 添加新元素
+     * 2. 避免跟踪长度变化
+     * 3. 处理响应式值的添加
+     *
+     * @param args 要添加的元素
+     * @returns 数组的新长度
      */
     unshift(...args: unknown[])
     {
@@ -269,7 +503,14 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 
     /**
-     * 返回一个迭代器，用于遍历数组的响应式值
+     * 返回一个迭代器，用于遍历数组的值。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的值迭代器
+     * 2. 自动将迭代的值转换为响应式
+     * 3. 自动追踪数组的访问
+     *
+     * @returns 数组的值迭代器
      */
     values()
     {
@@ -277,31 +518,45 @@ export const arrayInstrumentations: Record<string | symbol, Function> = <any>{
     },
 };
 
-// instrument iterators to take ARRAY_ITERATE dependency
+/**
+ * 创建数组的迭代器。
+ *
+ * 实现了以下功能：
+ * 1. 创建数组的迭代器
+ * 2. 自动将迭代的值转换为响应式
+ * 3. 自动追踪数组的访问
+ *
+ * 注意：在这里获取 ARRAY_ITERATE 依赖并不完全等同于在代理数组上调用迭代。
+ * 创建迭代器时不会访问任何数组属性：
+ * 只有在调用 .next() 时才会访问 length 和索引。
+ * 从极端情况来看，迭代器可以在一个 effect scope 中创建，
+ * 在另一个 scope 中部分迭代，然后在第三个 scope 中继续迭代。
+ * 考虑到 JS 迭代器只能读取一次，这似乎不是一个合理的用例，
+ * 所以这种跟踪简化是可以接受的。
+ *
+ * @param self 目标数组
+ * @param method 迭代器方法名
+ * @param wrapValue 值包装函数，用于将值转换为响应式
+ * @returns 数组的迭代器
+ */
 function iterator(
     self: unknown[],
     method: keyof Array<unknown>,
     wrapValue: (value: any) => unknown,
 )
 {
-    // note that taking ARRAY_ITERATE dependency here is not strictly equivalent
-    // to calling iterate on the proxified array.
-    // creating the iterator does not access any array property:
-    // it is only when .next() is called that length and indexes are accessed.
-    // pushed to the extreme, an iterator could be created in one effect scope,
-    // partially iterated in another, then iterated more in yet another.
-    // given that JS iterator can only be read once, this doesn't seem like
-    // a plausible use-case, so this tracking simplification seems ok.
     const arr = shallowReadArray(self);
     const iter = (arr[method] as any)() as IterableIterator<unknown> & {
         _next: IterableIterator<unknown>['next']
     };
+
     if (arr !== self)
     {
         iter._next = iter.next;
         iter.next = () =>
         {
             const result = iter._next();
+
             if (result.value)
             {
                 result.value = wrapValue(result.value);
@@ -315,7 +570,17 @@ function iterator(
 }
 
 /**
- * 跟踪数组的迭代操作并返回原始数组
+ * 创建数组的浅层响应式副本。
+ *
+ * 实现了以下功能：
+ * 1. 跟踪数组的迭代操作
+ * 2. 返回原始数组的引用
+ *
+ * 注意：此函数只跟踪数组的迭代操作，不会递归转换数组中的值。
+ * 主要用于优化性能，避免不必要的响应式转换。
+ *
+ * @param arr 目标数组
+ * @returns 数组的浅层响应式副本
  */
 function shallowReadArray<T>(arr: T[]): T[]
 {
@@ -324,21 +589,59 @@ function shallowReadArray<T>(arr: T[]): T[]
     return arr;
 }
 
+/**
+ * 创建数组的深层响应式副本。
+ *
+ * 实现了以下功能：
+ * 1. 跟踪数组的迭代操作
+ * 2. 递归转换所有值为响应式
+ *
+ * 注意：此函数会递归转换数组中的所有值为响应式，
+ * 包括嵌套的数组和对象。这可能会导致性能开销，
+ * 但确保了所有值都是响应式的。
+ *
+ * @param array 目标数组
+ * @returns 数组的深层响应式副本
+ */
 function reactiveReadArray<T>(array: T[]): T[]
 {
     const raw = toRaw(array);
+
     if (raw === array) return raw;
     PropertyReactivity.track(raw, TrackOpTypes.ITERATE, ARRAY_ITERATE_KEY);
 
     return raw.map(toReactive);
 }
 
-// in the codebase we enforce es2016, but user code may run in environments
-// higher than that
+/**
+ * 数组方法类型。
+ *
+ * 包括所有需要增强的数组方法。
+ * 注意：在代码库中我们强制使用 es2016，但用户代码可能在更高版本的环境中运行。
+ */
 type ArrayMethods = keyof Array<any> | 'findLast' | 'findLastIndex';
 
-// instrument functions that read (potentially) all items
-// to take ARRAY_ITERATE dependency
+/**
+ * 应用数组方法。
+ *
+ * 实现了以下功能：
+ * 1. 调用数组方法
+ * 2. 自动追踪数组的访问
+ * 3. 处理回调函数的执行
+ * 4. 处理返回值的转换
+ *
+ * 注意：如果调用的方法来自用户扩展的 Array，参数将是未知的
+ * （未知顺序和未知参数类型）。在这种情况下，我们跳过 shallowReadArray
+ * 处理，直接使用 self 调用 apply。
+ *
+ * @param self 目标数组
+ * @param method 方法名
+ * @param fn 回调函数
+ * @param thisArg 回调函数的 this 值
+ * @param wrappedRetFn 返回值包装函数，用于将返回值转换为响应式
+ * @param args 方法参数
+ * @returns 方法的执行结果
+ */
 function apply(
     self: unknown[],
     method: ArrayMethods,
@@ -364,6 +667,7 @@ function apply(
     }
 
     let wrappedFn = fn;
+
     if (arr !== self)
     {
         if (needsWrap)
@@ -386,7 +690,24 @@ function apply(
     return needsWrap && wrappedRetFn ? wrappedRetFn(result) : result;
 }
 
-// instrument reduce and reduceRight to take ARRAY_ITERATE dependency
+/**
+ * 应用数组的归约方法。
+ *
+ * 实现了以下功能：
+ * 1. 调用数组的归约方法
+ * 2. 自动追踪数组的访问
+ * 3. 处理回调函数的执行
+ * 4. 处理响应式值的归约
+ *
+ * 注意：此函数用于处理 reduce 和 reduceRight 方法，
+ * 确保在归约过程中正确处理响应式值。
+ *
+ * @param self 目标数组
+ * @param method 方法名（'reduce' 或 'reduceRight'）
+ * @param fn 归约函数
+ * @param args 方法参数，包括初始值（可选）
+ * @returns 归约的结果
+ */
 function reduce(
     self: unknown[],
     method: keyof Array<any>,
@@ -396,6 +717,7 @@ function reduce(
 {
     const arr = shallowReadArray(self);
     let wrappedFn = fn;
+
     if (arr !== self)
     {
         wrappedFn = function (this: unknown, acc, item, index)
@@ -407,7 +729,23 @@ function reduce(
     return (arr[method] as any)(wrappedFn, ...args);
 }
 
-// instrument identity-sensitive methods to account for reactive proxies
+/**
+ * 在数组中搜索元素。
+ *
+ * 实现了以下功能：
+ * 1. 处理响应式值的搜索
+ * 2. 自动追踪数组的访问
+ * 3. 处理代理对象的搜索
+ *
+ * 注意：我们首先使用原始参数（可能是响应式的）运行方法。
+ * 如果那不起作用，我们再次使用原始值运行。
+ * 这确保了在搜索响应式值时能够正确处理。
+ *
+ * @param self 目标数组
+ * @param method 方法名（'includes'、'indexOf' 或 'lastIndexOf'）
+ * @param args 搜索参数
+ * @returns 搜索的结果（布尔值或索引）
+ */
 function searchProxy(
     self: unknown[],
     method: keyof Array<any>,
@@ -415,6 +753,7 @@ function searchProxy(
 )
 {
     const arr = toRaw(self) as any;
+
     PropertyReactivity.track(arr, TrackOpTypes.ITERATE, ARRAY_ITERATE_KEY);
     // we run the method using the original args first (which may be reactive)
     const res = arr[method](...args);
@@ -430,8 +769,22 @@ function searchProxy(
     return res;
 }
 
-// instrument length-altering mutation methods to avoid length being tracked
-// which leads to infinite loops in some cases (#2137)
+/**
+ * 执行不跟踪的数组操作。
+ *
+ * 实现了以下功能：
+ * 1. 执行数组操作
+ * 2. 避免跟踪长度变化
+ * 3. 在批处理中执行操作
+ *
+ * 注意：这用于避免在某些情况下（#2137）由于跟踪长度变化而导致的无限循环。
+ * 通过使用批处理和禁用跟踪，我们可以安全地执行这些操作。
+ *
+ * @param self 目标数组
+ * @param method 方法名（'push'、'pop'、'shift'、'unshift' 或 'splice'）
+ * @param args 方法参数
+ * @returns 操作的执行结果
+ */
 function noTracking(
     self: unknown[],
     method: keyof Array<any>,
@@ -440,8 +793,8 @@ function noTracking(
 {
     const res = batchRun(() =>
         noTrack(() =>
-            (toRaw(self) as any)[method].apply(self, args)
-        )
+            (toRaw(self) as any)[method].apply(self, args),
+        ),
     );
 
     return res;