【AI-Review】【一般】【业务功能】【功能实现错误】示例页面未展示 enableNestedScroll + 上拉加载场景

● 问题：bindSheetConfigurator 设置了 .setHasLoadMore(false)，当 useBindSheetMode 为 true 时，onReachEnd 中的 this.refreshConfigurator?.getHasLoadMore() 为 false，上拉加载不会触发。但 PR 描述中明确说明"开启后，上拉加载改为通过 Scroll.onReachEnd 自动触发（onLoadMore 仍可用）"，示例未能展示该核心功能场景。

● 影响：一般。开发者无法从示例中了解如何在 enableNestedScroll 模式下使用上拉加载功能，可能导致误用。

● 建议：增加一个 enableNestedScroll + setHasLoadMore(true) 的示例场景，或者在现有示例中将 bindSheetConfigurator 的 setHasLoadMore 设为 true，以完整展示嵌套滚动下的上拉加载能力。

【AI-Review】【一般】【业务功能】【功能实现错误】示例页面bindSheetConfigurator设置setHasLoadMore(false)导致无法验证onReachEnd加载功能

● 问题：在示例页面 bindSheetPullRefresh.ets 和 bindSheetPullRefreshV2.ets 中，嵌套滚动模式使用的 bindSheetConfigurator 同时设置了 setHasRefresh(false) 和 setHasLoadMore(false)。而 onReachEnd 回调中的加载触发条件是 this.refreshConfigurator?.getHasLoadMore() && this.onLoadMore，由于 getHasLoadMore() 返回 false，onReachEnd 中的加载逻辑永远不会被执行。这意味着：

1. 示例页面无法验证 enableNestedScroll + onReachEnd + onLoadMore 的集成是否正常工作
2. 如果该集成存在 Bug（如加载动画显示异常、onLoadMore 不触发等），在当前示例中无法被发现
3. 用户参考此示例时，无法了解如何在嵌套滚动模式下正确使用上拉加载功能

● 影响：一般。示例页面未能完整演示嵌套滚动模式的核心功能（上拉加载 via onReachEnd），可能导致该路径的 Bug 未被覆盖，也会误导开发者认为嵌套滚动模式下不支持上拉加载。

● 建议：修改示例中嵌套滚动模式的 configurator，保留 setHasRefresh(false) 但去掉 setHasLoadMore(false)（或显式设为 true），使 onReachEnd 加载路径可被验证：

private bindSheetConfigurator: PullToRefreshConfigurator = new PullToRefreshConfigurator()
  .setHasRefresh(false);

或者，如果确实需要展示"仅滚动、无加载"的场景，建议增加第三个按钮来演示"嵌套滚动+上拉加载"模式。

【AI-Review】【一般】【基础代码问题】【代码逻辑错误】bindSheetPullRefresh 示例中 List 和 PullToRefresh 共享 scroller 导致冲突

● 问题: bindSheetPullRefresh.ets 中 sheetList() 创建了一个 List({ space: 12, scroller: this.scroller })，而外部 PullToRefresh 也使用了同一个 this.scroller。在 nestedScroll 模式下，PullToRefresh 内部创建 Scroll(this.scroller)，而 List 本身也是滚动组件且使用了同一个 scroller。这会导致 scroller 被两个滚动容器共享，scrollTo、scrollEdge、currentOffset、isAtEnd 等操作的行为将不可预测——PullToRefresh 中通过 this.scroller!.currentOffset() 获取的可能是 List 的偏移量，也可能是 Scroll 的偏移量。

● 影响: 一般。作为示例代码，可能误导使用者。在实际使用中，当 enableNestedScroll 为 true 时，不应在 customList 内部的 List 上设置 scroller，因为 PullToRefresh 已经在外部 Scroll 上使用了该 scroller。

● 建议: 在 nestedScroll 模式下，内部的 List 不应设置 scroller，因为滚动由外部的 Scroll 管理。建议在示例中区分两种模式的 List 创建方式：

@Builder
private sheetList() {
  List({ space: 12 }) {
    // nestedScroll 模式下不传 scroller
    // ...
  }
  .edgeEffect(EdgeEffect.None)
}

或在文档中明确说明：当 enableNestedScroll 为 true 时，customList 中的滚动组件不应使用与 PullToRefresh 相同的 scroller。

【AI-Review】【一般】【基础代码问题】【代码逻辑错误】示例代码 sheetList() 在非嵌套模式下 scroller 双重绑定，与 README 警告矛盾

● 问题：示例 bindSheetPullRefresh.ets 中，sheetList() 将同一个 this.scroller 同时传给 PullToRefresh({ scroller: this.scroller, ... }) 和内部的 List({ space: 12, scroller: this.scroller })。这正是 README 中警告要避免的场景："customList 内部不要再将同一个 scroller 绑定到 List、Scroll 或其他滚动容器"。但示例代码在非嵌套模式（useBindSheetMode=false）下恰恰是这样做的。这会给开发者传递矛盾的信息：README 说不要双重绑定，但官方示例就在双重绑定。

实际上，在非嵌套模式下，由于组件内部没有创建 Scroll 容器，scroller 只绑定到 List 一处，这是原有设计——用户传入 scroller，组件用它来检测偏移和执行 scrollEdge/scrollTo，List 也用这个 scroller 做滚动控制，两者操作的是同一个滚动容器，所以不冲突。但问题在于，当切换到嵌套滚动模式时，useBindSheetMode 从 false 变为 true，同一组件实例的 scroller 被额外绑定到了内部的 Scroll，而 sheetList() 中的 List 仍然持有该 scroller，导致双重绑定。

● 影响：一般。示例代码作为开发者参考存在设计缺陷，在模式切换场景下可能引发 scroller 冲突。同时，README 的警告措辞需要更精确——不是"不要双重绑定"，而是"在嵌套滚动模式下不要双重绑定"。

● 建议：1) 修改示例代码，为嵌套滚动模式使用独立的 scroller：

private scrollScroller: Scroller = new Scroller();  // 给内部 Scroll 用
private listScroller: Scroller = new Scroller();     // 给 List 用

2. 更新 README 中的警告说明，明确限定为嵌套滚动模式下避免双重绑定： "When enableNestedScroll is enabled, the component's internal Scroll uses the provided scroller. Do not bind the same scroller to a List, Scroll, or other scrollable container inside customList in this mode."

【AI-Review】【一般】【业务功能】【功能实现错误】示例页面在嵌套滚动模式下仍传入 onLoadMore 回调

● 问题：bindSheetPullRefresh.ets 和 bindSheetPullRefreshV2.ets 中，onLoadMore 回调始终被传入 PullToRefresh 组件，无论 useBindSheetMode（即 enableNestedScroll）的值如何。根据 README 文档说明，启用 enableNestedScroll 后 "onRefresh/onLoadMore 回调不会被触发"。示例中当 useBindSheetMode 为 true 时传入的 onLoadMore 永远不会执行，这段死代码可能误导开发者认为在嵌套滚动模式下上拉加载仍可正常工作。

● 影响：一般。示例作为开发者参考，传入无效回调会误导使用者对 enableNestedScroll 行为的理解，可能导致开发者在实际项目中错误配置。

● 建议：在嵌套滚动模式下不传入 onLoadMore，或使用条件判断：

PullToRefresh({
  data: $data,
  scroller: this.useBindSheetMode ? this.nestedScrollScroller : this.listModeScroller,
  enableNestedScroll: this.useBindSheetMode,
  refreshConfigurator: this.useBindSheetMode ? this.bindSheetConfigurator : this.defaultConfigurator,
  customList: () => { /* ... */ },
  ...(this.useBindSheetMode ? {} : {
    onLoadMore: () => { /* ... */ }
  }),
  customLoad: null,
  customRefresh: null,
})

或至少在示例中添加注释说明该回调在嵌套滚动模式下不会触发。

【AI-Review】【严重】【基础代码问题】【稳定性问题】示例页面中 data.push() 直接修改数组不触发 UI 刷新

● 问题：在 bindSheetPullRefresh.ets 第93行和 bindSheetPullRefreshV2.ets 第93行的 onLoadMore 回调中，使用 this.data.push(\more ${this.data.length}`) 直接修改数组。在 ArkTS 中，@State/@Local修饰的数组变量通过push方法修改时不会触发状态变化通知，UI 不会更新显示新增的条目。虽然 PullToRefresh 组件内部通过@Link data/@Param data` 接收数据，但直接 push 仍然不会触发框架的变更检测。

● 影响：严重。上拉加载更多后，新条目不会在列表中显示，用户看到的列表不会增长，功能完全失效。

● 建议：使用数组重新赋值触发状态更新：

onLoadMore: () => {
  return new Promise<string>((resolve) => {
    setTimeout(() => {
      this.data = [...this.data, `more ${this.data.length}`];
      resolve('');
    }, 800);
  });
}

【AI-Review】【一般】【业务功能】【示例设计问题】 ● 问题: sheetColumn() Builder 使用 Column 布局来展示数据，但 Column 组件本身不可滚动。当启用嵌套滚动模式时，PullToRefresh 内部会创建一个 Scroll 组件包裹 customList，但这里的 customList 返回的是一个不可滚动的 Column，导致：1) Scroll 包裹不可滚动的内容，没有实际滚动效果；2) onLoadMore 加载更多逻辑依赖 scroller 的滚动位置检测，但 Column 不支持滚动，可能导致加载更多功能失效；3) 示例无法正确展示 nestedScroll 功能的使用场景。

● 影响: 一般。示例页面无法正确演示嵌套滚动模式的功能，可能导致开发者误用该功能。同时，同一个 scroller 对象在 sheetList() 和 sheetColumn() 两种布局中混用，在切换模式时可能导致 scroller 状态不一致。

● 建议: 修改 sheetColumn() 使用可滚动的组件，例如使用 List 或 Grid：

@Builder
private sheetColumn() {
  List({ scroller: this.scroller }) {
    ForEach(this.data, (item: string) => {
      ListItem() {
        Text(item)
          .width('100%')
          .height(100)
          .fontSize(18)
          .textAlign(TextAlign.Center)
          .backgroundColor('#95efd2')
      }
    })
  }
  .width('100%')
  .backgroundColor('#eeeeee')
  .listDirection(Axis.Vertical)
}

或者考虑为两种模式使用不同的 scroller 对象，避免状态冲突：

private listScroller: Scroller = new Scroller();
private columnScroller: Scroller = new Scroller();

这样可以更好地展示 nestedScroll 模式下 Scroll 组件与内部可滚动组件的正确协作方式。

【AI-Review】【一般】【基础代码问题】【代码逻辑错误】示例 sheetColumn 使用不可滚动 Column 导致上拉加载误触发

● 问题：bindSheetPullRefresh.ets 示例中，嵌套滚动模式下的 sheetColumn() 使用 Column 布局（不可滚动组件）。当用户向上滑动时，onActionUpdate 中的 this.scroller.isAtEnd() 对绑定到外层 Scroll 的 scroller 调用，由于 Column 内容不可滚动且外层 Scroll 内容高度有限，isAtEnd() 可能始终返回 true。这会导致在列表未真正到底时就触发上拉加载状态（IS_PULL_UP_1/IS_PULL_UP_2），用户任何向上滑动都可能误触发 onLoadMore。

● 影响：一般。示例页面中上拉加载功能在嵌套滚动模式下会被误触发，无法正确演示该功能的使用方式，可能误导开发者。

● 建议：sheetColumn() 应使用可滚动组件（如 List）替代 Column，并且根据 README 文档的说明"customList 内部不应再绑定同一个 scroller"，内层列表不应绑定 scroller：

@Builder
private sheetColumn() {
  List({ space: 12 }) {
    ForEach(this.data, (item: string) => {
      ListItem() {
        Text(item)
          .width('100%')
          .height(100)
          .fontSize(18)
          .textAlign(TextAlign.Center)
          .backgroundColor('#95efd2')
      }
    })
  }
  .width('100%')
  .backgroundColor('#eeeeee')
}

这样外层 Scroll 的 scroller 能正确获取滚动位置，isAtEnd() 和 currentOffset() 的判断才有意义。

【AI-Review】【一般】【基础代码问题】【代码逻辑错误】示例中 sheetColumn() 缺少 .height('100%')，嵌套滚动模式下 Scroll 包裹不可滚动内容导致上拉加载失效

● 问题：bindSheetPullRefresh.ets 示例中，sheetList() 设置了 .height('100%')，但 sheetColumn() 未设置高度。当启用嵌套滚动模式（enableNestedScroll: true）时，组件内部 Scroll(this.scroller) 包裹 sheetColumn() 返回的 Column。由于 Column 没有设置高度，它只会按内容高度渲染。如果数据较少未填满 Scroll 可视区域，Scroll 内容不可滚动，导致：1) scroller.isAtEnd() 可能始终返回 true；2) 但 listOffsetOld 和 listOffsetNew 始终为 0（因为无法滚动），listOffsetOld != 0 条件不满足，上拉加载实际不会触发。虽然该检测逻辑避免了误触发，但示例中提供的 onLoadMore 回调在嵌套滚动模式下实质上是死代码，容易误导开发者。

● 影响：一般。示例代码作为开发者参考，存在功能缺陷可能误导使用者认为上拉加载在嵌套滚动模式下可以正常工作。同时 sheetColumn() 与 sheetList() 的布局设置不一致，增加了理解难度。

● 建议：为 sheetColumn() 添加 .height('100%') 以确保 Column 填满 Scroll 可视区域，或者改用 List 等可滚动组件替代 Column 以正确展示嵌套滚动模式下的上拉加载功能：

@Builder
private sheetColumn() {
  Column({ space: 12 }) {
    ForEach(this.data, (item: string) => {
      Text(item)
        .width('100%')
        .height(100)
        .fontSize(18)
        .textAlign(TextAlign.Center)
        .backgroundColor('#95efd2')
    })
  }
  .width('100%')
  .height('100%')
  .backgroundColor('#eeeeee')
}

【AI-Review】【一般】【基础代码问题】【性能和效率问题】sheetColumn()使用Column而非List，大数据量下无懒加载

● 问题：bindSheetPullRefresh.ets 和 bindSheetPullRefreshV2.ets 中的 sheetColumn() Builder 使用 Column + ForEach 渲染所有列表项。Column 不支持懒加载，当数据量增大时，所有列表项会一次性全部创建和渲染，导致内存占用增加和首帧渲染耗时增长。而 sheetList() 使用了 List 组件，天然支持懒加载。

● 影响：一般。在数据量较小（如demo中的5项）时影响不大，但作为公开示例代码，可能误导开发者认为 Column 是推荐的实现方式。在实际业务中数据量可能较大，导致性能问题。

● 建议：将 sheetColumn() 改为使用 List 组件实现，以保持与 sheetList() 一致的懒加载能力，同时也能正确配合 Scroll 的 onReachEnd 触发上拉加载：

@Builder
private sheetColumn() {
  List({ space: 12 }) {
    ForEach(this.data, (item: string) => {
      ListItem() {
        Text(item)
          .width('100%')
          .height(100)
          .fontSize(18)
          .textAlign(TextAlign.Center)
          .backgroundColor('#95efd2')
      }
    })
  }
  .width('100%')
  .backgroundColor('#eeeeee')
  .listDirection(Axis.Vertical)
}

或者，如果 sheetColumn 是为了展示非 List 场景（如 Column 布局），则应在注释中明确说明这是受限场景的演示，并提醒开发者大数据量时应使用 List。

【AI-Review】【建议】【基础代码问题】【验证问题】bindSheetPullRefresh 示例中 sheetColumn 缺少高度约束

● 问题: 在 sheetColumn() Builder 中（第 110-123 行），Column 仅设置了 .width('100%') 而未设置 .height('100%')。当 enableNestedScroll=true 时，此 Column 作为 PullToRefresh 内部 Scroll 的子内容。如果数据项不足以填满 Sheet 可视区域，Column 的高度将仅等于内容高度，导致 .backgroundColor('#eeeeee') 不会填充整个可视区域，出现底部空白。相比之下，sheetList() 的 List 设置了 .height('100%')，两者表现不一致。

● 影响: 建议。在数据项较少时，Sheet 内嵌套滚动模式的背景色不会填满可视区域，视觉效果不一致。

● 建议: 为 sheetColumn() 的 Column 添加 .height('100%')，使其与 sheetList() 的视觉效果保持一致。同时 PullToRefreshV2 版本的 demo（bindSheetPullRefreshV2.ets）也存在同样的问题。

【AI-Review】【建议】【基础代码问题】【验证问题】PullToRefresh V1 中 enableNestedScroll 无响应式装饰器，动态变更不会触发 UI 更新

● 问题: 在 PullToRefresh（V1 @Component）中，enableNestedScroll 声明为普通可选属性 enableNestedScroll?: boolean = false，没有使用 @Prop 或 @State 装饰器。这意味着如果父组件动态改变 enableNestedScroll 的值（例如通过状态绑定切换模式），PullToRefresh 内部的 useNestedScrollMode() 不会重新计算，UI 不会从 Column 模式切换到 Scroll 模式。

对比 PullToRefreshV2（@ComponentV2）中使用了 @Param enableNestedScroll?: boolean = false，V2 版本能正确响应变化。

● 影响: 建议。在 bindSheetPullRefresh 示例中，useBindSheetMode 是动态切换的，但通过 enableNestedScroll: this.useBindSheetMode 传给 PullToRefresh V1 时，V1 组件不会响应这个变化。当前示例使用的是 V1 组件，实际效果是每次打开 Sheet 时都是初始模式的值，切换按钮只在重新打开 Sheet 时生效。

● 建议: 将 PullToRefresh V1 中的 enableNestedScroll 添加 @Prop 装饰器：

@Prop enableNestedScroll?: boolean = false;

这样父组件动态改变时，组件能正确响应并切换渲染模式。

【AI-Review】【严重】【基础代码问题】【代码逻辑错误】PullToRefresh V1 中 enableNestedScroll 无状态装饰器，无法响应父组件更新

● 问题：在 PullToRefresh（V1 @Component）中，enableNestedScroll 声明为普通可选属性 enableNestedScroll?: boolean = false，没有 @Prop 或 @Link 装饰器。而 V2 组件 PullToRefreshV2 中相同属性使用了 @Param enableNestedScroll?: boolean = false。V1 中，如果父组件动态改变 enableNestedScroll 的值（例如通过状态变量绑定），PullToRefresh 组件内部不会感知到变化，build() 中的 if (this.enableNestedScroll === true) 分支不会重新渲染，导致组件行为与预期不一致。

● 影响：严重。V1 组件中 enableNestedScroll 实际上变成了只读初始值，后续任何动态变更都不会生效。这与 V2 组件的行为不一致，违反了 V1/V2 提供一致能力的设计目标。开发者在 V1 中动态切换 enableNestedScroll 时会得到静默失败的结果。

● 建议：将 V1 组件中的 enableNestedScroll 声明为 @Prop enableNestedScroll?: boolean = false，确保能响应父组件的状态变更。与 V2 的 @Param 保持对等的能力。

【AI-Review】【一般】【稳定性问题】【资源管理问题】timer 未在组件销毁时清理

● 问题：组件中使用 setInterval 创建的 timer，在 closeRefresh() 和 closeLoad() 方法中通过 clearInterval(this.timer) 清理。但是组件缺少 aboutToDisappear 生命周期方法，如果组件在动画执行期间被销毁（例如页面跳转、Sheet 关闭），timer 可能未被清理，导致内存泄漏或后台继续执行无用逻辑。

● 影响：一般。可能导致内存泄漏，特别是在频繁切换页面或快速关闭 Sheet 的场景下。

● 建议：添加 aboutToDisappear 方法，在组件销毁时清理 timer：

aboutToDisappear() {
  if (this.timer !== undefined) {
    clearInterval(this.timer);
    this.timer = undefined;
  }
}

同时，在 closeRefresh() 和 closeLoad() 方法中，清理后将 timer 设置为 undefined，避免重复清理。

【AI-Review】【一般】【基础代码问题】【验证问题】enableNestedScroll 与 hasRefresh/hasLoadMore 不兼容时缺乏运行时校验

● 问题: 当 enableNestedScroll=true 且 hasRefresh=true 或 hasLoadMore=true 时，组件不会给出任何提示，但 PanGesture 被 early-return 完全禁用，导致刷新/加载更多功能静默失效。用户可能花费大量时间调试才能发现此配置组合不可用。

● 影响: 一般。配置不兼容时功能静默失效，降低库的可用性和调试体验。虽然 README 提到需配合 setHasRefresh(false) 使用，但作为公开 API 的三方库，运行时校验是必要的防御性编程。

● 建议: 在 aboutToAppear 中添加配置校验，当检测到不兼容配置时输出警告日志。例如在 PullToRefresh.ets 的 aboutToAppear 方法中，当 enableNestedScroll 为 true 时检查 refreshConfigurator 的 hasRefresh 和 hasLoadMore，若为 true 则通过 LogUtil 输出警告信息，提示用户调用 setHasRefresh(false) 或 setHasLoadMore(false)。PullToRefreshV2.ets 中也应添加同样的校验逻辑。

【AI-Review】【严重】【基础代码问题】【稳定性问题】组件缺少 aboutToDisappear 清理 timer

● 问题: PullToRefresh 组件在 onActionEnd 中使用 setInterval 创建了 this.timer（约第 447 行），但组件中没有 aboutToDisappear 生命周期方法来清除这个定时器。当组件被销毁时（例如 bindSheet 关闭），setInterval 仍会继续执行回调，尝试访问已销毁组件的 this.value、this.trYTop 等状态变量，可能导致异常或内存泄漏。PullToRefreshV2 同样存在此问题。

● 影响: 严重。在 bindSheet 场景下关闭 Sheet 后，定时器仍在运行，每 10ms 执行一次回调，持续修改已销毁组件的状态，可能导致运行时异常或不可预期的行为。对于频繁打开/关闭 Sheet 的用户，还可能累积多个未清除的定时器。

● 建议: 添加 aboutToDisappear 生命周期方法，清除所有定时器：

aboutToDisappear() {
  if (this.timer !== undefined) {
    clearInterval(this.timer);
    this.timer = undefined;
  }
}

同时，在 onRefresh().then() 和 onLoadMore().then() 的回调中，应在执行前检查组件是否已销毁，避免在组件销毁后修改状态。

【AI-Review】【严重】【基础代码问题】【资源使用问题】aboutToDisappear 未追踪和清理 setTimeout，组件销毁后可能执行回调

● 问题: 新增的 aboutToDisappear()（第 100-106 行）仅清理了 this.timer（setInterval），但代码中存在两处未被追踪的 setTimeout：

1. closeRefresh() 中的 setTimeout（第 690 行）— 在刷新完成后延迟重置状态
2. onActionEnd 中 onRefresh().then() 内的 setTimeout（第 502 行）— 在刷新成功后延迟关闭

这些 setTimeout 没有被存储到变量中，也无法在 aboutToDisappear 中清除。当组件销毁后（如 Sheet 关闭），这些 setTimeout 仍会执行，尝试设置 this.state、this.refreshText 等状态，导致对已销毁组件的无效操作。

● 影响: 严重。组件销毁后 setTimeout 回调仍执行，可能引发运行时异常。在 bindSheet 快速开关场景下尤其容易触发。

● 建议: 将所有 setTimeout 的返回值保存到实例变量中，并在 aboutToDisappear 中统一清除：

private refreshTimeout?: number;

// closeRefresh 中
this.refreshTimeout = setTimeout(() => {
  if (this.isDestroyed) return;
  this.state = IS_FREE;
  this.refreshText = '';
}, this.refreshConfigurator.getAnimDuration());

// aboutToDisappear 中
aboutToDisappear() {
  this.isDestroyed = true;
  if (this.timer !== undefined) {
    clearInterval(this.timer);
    this.timer = undefined;
  }
  if (this.refreshTimeout !== undefined) {
    clearTimeout(this.refreshTimeout);
    this.refreshTimeout = undefined;
  }
}

PullToRefreshV2.ets（第 688 行同样有未追踪的 setTimeout）也需要同步修复。