d92b8384创建于 1月30日历史提交

ArkUI Scroll 组件完整知识库

文档版本：v1.0 更新时间：2026-01-30 源码版本：OpenHarmony ace_engine (master 分支) 作者：基于 CLAUDE.md 规范自动生成

📚 目录

概述
完整调用链
目录结构
核心类继承关系
Pattern层详解
Model层详解
LayoutAlgorithm层详解
属性系统
事件处理
滚动控制
特殊功能
缓存机制
执行流程
完整API清单
关键实现细节
滚动边缘效果
使用示例
调试指南
常见问题
附录

概述

组件定位

Scroll 组件是 OpenHarmony ArkUI 框架中的滚动容器组件，提供单轴滚动、二维自由滚动、分页滚动、滚动对齐等多种滚动形式，是 ArkUI 中最常用的容器组件之一。

技术栈：

前端：ArkTS/TypeScript
桥接层：ScrollModelNG
核心层：NG Pattern 架构 (ScrollPattern)
布局算法：ScrollLayoutAlgorithm
渲染层：Rosen + Skia

代码规模：

总文件数：约 50 个文件
核心代码：约 20,000+ 行 C++ 代码
涉及 4 个架构层次

功能特性

Scroll 组件支持：

多种滚动模式：
- 单轴滚动（垂直/水平）
- 二维自由滚动 (Axis::FREE)
- 分页滚动 (enablePaging)
- 滚动对齐 (scrollSnap)
滚动条：内置滚动条（支持状态显示/隐藏、位置、厚度、颜色定制）
边缘效果：Spring（弹性）、Fade（淡入淡出）、None（无效果）
缩放支持：双指缩放功能
滚动事件：onScroll、onReachStart、onReachEnd、onScrollStart、onScrollStop、onWillScroll、onDidScroll
性能优化：布局缓存、测量缓存（LRU 淘汰策略）
无障碍支持：完整的 Accessibility 支持

设计模式

Scroll 组件采用 NG Pattern 架构：

前端 (ArkTS)
    ↓ (Model Layer)
ScrollModelNG (scroll_model_ng.cpp)
    ↓ (NG Pattern Layer)
ScrollPattern (scroll_pattern.cpp)
    ├─ ScrollablePattern (基类 - 手势处理)
    └─ FreeScrollController (自由滚动控制器)
    ├─ ZoomController (缩放控制器)
    └─ ScrollBar2D (二维滚动条)
    ↓ (NG LayoutAlgorithm Layer)
ScrollLayoutAlgorithm (scroll_layout_algorithm.cpp)
    ↓
渲染显示

核心概念

滚动坐标系：

currentOffset_ = 0           → 在顶部
currentOffset_ > 0           → 内容向上偏移（显示上方内容）
currentOffset_ < 0           → 内容向下偏移（显示下方内容）
currentOffset_ = -scrollableDistance_  → 在底部

关键距离：

viewPortLength_：视口长度（可见区域大小）
scrollableDistance_：可滚动距离（内容尺寸 - 视口尺寸）
viewPortExtent_：内容总尺寸

完整调用链

1. 从 ArkTS 到 Pattern 的调用链

调用链图

┌─────────────────────────────────────────────────────────┐
│ 前端 ArkTS                                                │
│                                                          │
│ Scroll() {                                              │
│   Scroll({ scroller: this.scroller }) {                 │
│     Text("Item 1")                                      │
│     Text("Item 2")                                      │
│   }                                                     │
│   .width('100%')                                        │
│   .height('100%')                                       │
│   .scrollable(ScrollDirection.Vertical)                │
│   .scrollBar(BarState.Auto)                             │
│   .onScroll((xOffset, yOffset) => {                     │
│     console.info(`onScroll: ${xOffset}, ${yOffset}`)    │
│   })                                                    │
│ }                                                       │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ Model Layer (NG)                                         │
│                                                          │
│ class ScrollModelNG                                      │
│   源码：frameworks/core/components_ng/pattern/scroll/     │
│         scroll_model_ng.cpp                               │
│                                                          │
│ 关键方法：                                                │
│ - Create() - 创建 Scroll 节点                           │
│ - SetScrollDirection() - 设置滚动方向                     │
│ - SetScrollBar() - 设置滚动条状态                        │
│ - SetOnScroll() - 注册滚动事件                           │
│                                                          │
│ 执行流程：                                                 │
│ 1. 创建 FrameNode (V2::SCROLL_ETS_TAG)                  │
│ 2. 创建 ScrollPattern                                    │
│ 3. 应用布局属性 (ScrollLayoutProperty)                   │
│ 4. 注册事件 (ScrollEventHub)                             │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ Pattern Layer (业务逻辑)                                  │
│                                                          │
│ class ScrollPattern : public ScrollablePattern           │
│   源码：frameworks/core/components_ng/pattern/scroll/     │
│         scroll_pattern.cpp                                 │
│                                                          │
│ 核心职责：                                                │
│ - 滚动位置管理 (currentOffset_, scrollableDistance_)     │
│ - 创建布局算法 (CreateLayoutAlgorithm)                   │
│ - 处理滚动事件 (OnScrollCallback)                        │
│ - 管理滚动条 (ScrollBar)                                 │
│ - 管理边缘效果 (EdgeEffect)                               │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ LayoutAlgorithm Layer (布局计算)                          │
│                                                          │
│ class ScrollLayoutAlgorithm : public LayoutAlgorithm     │
│   源码：frameworks/core/components_ng/pattern/scroll/     │
│         scroll_layout_algorithm.cpp                       │
│                                                          │
│ 核心方法：                                                │
│ - Measure() - 测量子节点                                 │
│ - Layout() - 应用滚动偏移                                │
│ - CalcContentOffset() - 计算内容偏移                      │
│ - UseInitialOffset() - 应用初始偏移                      │
└─────────────────────────────────────────────────────────┘
                          ↓
                    [滚动显示在屏幕上]

2. 滚动操作完整调用链

用户滑动手势 → 偏移量更新

用户手指滑动
    ↓
PanGestureRecognizer (识别滑动手势)
    ↓
ScrollablePattern::HandleScrollDelta()
    ↓
ScrollPattern::UpdateCurrentOffset(float offset, int32_t source)
    ↓
① ValidateOffset() - 验证偏移量是否合法
② 调整偏移量（考虑边界、边缘效果）
③ 更新 currentOffset_
④ FireObserverTwoDimensionOnWillScroll() - 触发 onWillScroll
⑤ 更新布局（请求新帧）
⑥ FireOnDidScroll() - 触发 onDidScroll
    ↓
OnScrollEndCallback() - 滚动结束
    ↓
FireOnReachStart() / FireOnReachEnd() - 如果到达边界

ScrollTo() API 调用链

scroller.scrollTo() (ArkTS)
    ↓
ScrollPositionController::ScrollTo()
    ↓
ScrollPattern::ScrollTo(float position)
    ↓
① ValidateOffset() - 验证目标位置
② JumpToPosition() - 跳转到指定位置
③ UpdateCurrentOffset() - 更新偏移量
④ 请求重新布局
    ↓
[滚动到目标位置]

目录结构

完整目录树

frameworks/core/components_ng/pattern/scroll/
├── scroll_pattern.h                    # ScrollPattern 主类定义
├── scroll_pattern.cpp                  # ScrollPattern 实现
├── scroll_layout_algorithm.h           # 布局算法定义
├── scroll_layout_algorithm.cpp         # 布局算法实现
├── scroll_layout_property.h            # 布局属性定义
├── scroll_paint_method.h               # 绘制方法
├── scroll_paint_method.cpp             # 绘制方法实现
├── scroll_event_hub.h                  # 事件中心
├── scroll_accessibility_property.h     # 无障碍属性
├── scroll_content_modifier.h           # 内容修饰器
├── scroll_content_modifier.cpp         # 内容修饰器实现
├── scroll_edge_effect.h                # 边缘效果接口
│
├── Model 层
├── scroll_model_ng.h                   # NG Model 定义
├── scroll_model_ng.cpp                 # NG Model 实现
├── scroll_model.h                      # 基础 Model 接口
├── scroll_model.cpp                    # 基础 Model 实现
├── scroll_model_static.h               # 静态 Model
├── scroll_model_static.cpp             # 静态 Model 实现
│
├── 控制器
├── free_scroll_controller.h            # 自由滚动控制器
├── free_scroll_controller.cpp          # 自由滚动控制器实现
├── zoom_controller.h                   # 缩放控制器
├── zoom_controller.cpp                 # 缩放控制器实现
│
├── 滚动条
├── inner/
│   ├── scroll_bar.h                    # 滚动条基类
│   ├── scroll_bar.cpp                  # 滚动条实现
│   ├── scroll_bar_2d.h                 # 二维滚动条
│   ├── scroll_bar_2d.cpp               # 二维滚动条实现
│   ├── scroll_bar_2d_painter.h         # 二维滚动条绘制器
│   ├── scroll_bar_2d_painter.cpp       # 二维滚动条绘制器实现
│   ├── scroll_bar_overlay_modifier.h   # 滚动条覆盖修饰器
│   └── scroll_bar_overlay_modifier.cpp # 滚动条覆盖修饰器实现
│
├── 边缘效果
├── effect/
│   ├── scroll_fade_effect.h            # 淡入淡出效果
│   ├── scroll_fade_effect.cpp          # 淡入淡出效果实现
│   ├── scroll_fade_controller.h        # 淡入淡出控制器
│   ├── scroll_fade_controller.cpp      # 淡入淡出控制器实现
│   ├── scroll_fade_painter.h           # 淡入淡出绘制器
│   └── scroll_fade_painter.cpp         # 淡入淡出绘制器实现
│
└── 文档
    ├── CLAUDE.md                       # 子目录规则（英文）
    ├── CLAUDE_ZH.md                    # 子目录规则（中文）
    └── claude-ZH.md                    # 临时中文文档

关键文件说明

文件	职责	核心类/方法
scroll_pattern.h/cpp	核心业务逻辑	`ScrollPattern::OnModifyDone()`, `OnScrollCallback()`
scroll_layout_algorithm.h/cpp	布局计算	`ScrollLayoutAlgorithm::Measure()`, `Layout()`
scroll_model_ng.h/cpp	ArkTS API 接口	`ScrollModelNG::Create()`, `SetScrollDirection()`
free_scroll_controller.h/cpp	二维滚动控制	`FreeScrollController::ScrollBy()`
zoom_controller.h/cpp	缩放控制	`ZoomController::HandlePinch()`
scroll_bar.h/cpp	滚动条实现	`ScrollBar::UpdatePosition()`
scroll_fade_effect.h/cpp	淡入淡出效果	`ScrollFadeEffect::PerformScroll()`

核心类继承关系

1. Pattern 层继承关系

Pattern (基类)
    ↓
ScrollablePattern (滚动基类)
    ├─ 手势识别 (PanGestureRecognizer)
    ├─ 滚动控制器 (ScrollPositionController)
    ├─ 边缘效果 (EdgeEffect)
    └─ 滚动事件处理
         ↓
ScrollPattern (Scroll 组件实现)
    ├─ 单轴滚动逻辑
    ├─ 布局算法创建
    ├─ 滚动条管理
    ├─ ScrollSnap（滚动对齐）
    ├─ Paging（分页）
    ├─ FreeScroll（二维滚动）
    └─ Zoom（缩放）

2. 关键类定义

ScrollPattern

文件：scroll_pattern.h:44

class ACE_FORCE_EXPORT ScrollPattern : public ScrollablePattern
{
    DECLARE_ACE_TYPE(ScrollPattern, ScrollablePattern);

public:
    ScrollPattern() : ScrollablePattern(EdgeEffect::NONE, true) {}

    // 核心状态变量
    double currentOffset_ = 0.0;           // 当前滚动偏移量
    double scrollableDistance_ = 0.0;      // 可滚动距离
    float viewPortLength_ = 0.0f;          // 视口长度
    SizeF viewPort_;                        // 视口尺寸
    SizeF viewPortExtent_;                  // 内容总尺寸

    // ScrollSnap
    std::vector<float> snapOffsets_;       // 对齐点列表
    std::vector<Dimension> snapPaginations_; // 分页点列表

    // Paging
    ScrollPagingStatus enablePagingStatus_ = ScrollPagingStatus::NONE;

    // 自由滚动
    RefPtr<FreeScrollController> freeScroll_;

    // 缩放
    RefPtr<ZoomController> zoomCtrl_;
    float maxZoomScale_ = 1.0f;
    float minZoomScale_ = 1.0f;
    std::optional<float> zoomScale_;

    // 缓存
    std::list<ScrollLayoutInfo> scrollLayoutInfos_;
    std::list<ScrollMeasureInfo> scrollMeasureInfos_;
};

ScrollLayoutAlgorithm

文件：scroll_layout_algorithm.h:33

class ACE_EXPORT ScrollLayoutAlgorithm : public LayoutAlgorithm
{
    DECLARE_ACE_TYPE(ScrollLayoutAlgorithm, LayoutAlgorithm);

public:
    explicit ScrollLayoutAlgorithm(double currentOffset, float crossOffset = 0.0f)
        : crossOffset_(crossOffset), currentOffset_(currentOffset) {}

    // 布局方法
    void Measure(LayoutWrapper* layoutWrapper) override;
    void Layout(LayoutWrapper* layoutWrapper) override;

    // 状态获取
    double GetCurrentOffset() const { return currentOffset_; }
    float GetScrollableDistance() const { return scrollableDistance_; }
    const SizeF& GetViewPort() const { return viewPort_; }
    const SizeF& GetViewPortExtent() const { return viewPortExtent_; }

private:
    float crossOffset_;
    double currentOffset_ = 0.0f;
    double scrollableDistance_ = 0.0f;
    float viewPortLength_ = 0.0f;
    SizeF viewPort_;        // 视口尺寸
    SizeF viewPortExtent_;  // 内容尺寸
    SizeF viewSize_;        // Scroll 组件尺寸
};

ScrollModelNG

文件：scroll_model_ng.h

class ScrollModelNG : public ScrollModel
{
public:
    // 创建 Scroll 节点
    static void Create();

    // 设置滚动方向
    void SetScrollDirection(ScrollDirection direction);

    // 设置滚动条
    void SetScrollBar(DisplayMode displayMode, const std::string& id = "");

    // 设置边缘效果
    void SetEdgeEffect(EdgeEffect edgeEffect);

    // 注册滚动事件
    void SetOnScroll(ScrollEventFunc&& onScroll);
    void SetOnReachStart(ReachEventFunc&& onReachStart);
    void SetOnReachEnd(ReachEventFunc&& onReachEnd);

    // 设置滚动对齐
    void SetScrollSnap(ScrollSnapAlign snapAlign, uint32_t snapInterval);
    void SetScrollSnapPagination(const std::vector<Dimension>& snapPaginations);

    // 设置分页
    void SetEnablePaging(bool enablePaging);

    // 设置初始偏移
    void SetInitialOffset(const OffsetT<CalcDimension>& offset);

    // 设置缩放
    void SetMaxZoomScale(float scale);
    void SetMinZoomScale(float scale);
};

Pattern层详解

ScrollPattern 核心职责

ScrollPattern 是 Scroll 组件的核心逻辑层，负责：

滚动位置管理
- 维护 currentOffset_（当前偏移量）
- 计算 scrollableDistance_（可滚动距离）
- 管理边界判断（IsAtTop(), IsAtBottom(), IsOutOfBoundary()）
布局算法协调
- 在 CreateLayoutAlgorithm() 中创建 ScrollLayoutAlgorithm 实例
- 传递 currentOffset_ 给 LayoutAlgorithm
- 在 OnDirtyLayoutWrapperSwap() 中接收布局结果
滚动事件处理
- 处理滚动回调：OnScrollCallback(float offset, int32_t source)
- 触发滚动事件：FireOnDidScroll(float scroll)
- 管理边缘到达事件：FireOnReachStart(), FireOnReachEnd()
特殊功能
- ScrollSnap（滚动对齐）：CaleSnapOffsets(), CalcPredictSnapOffset()
- Paging（分页滚动）：GetPagingOffset(), ScrollPage()
- FreeScroll（二维自由滚动）：FreeScrollBy(), FreeScrollTo()
- Zoom（缩放）：ProcessZoomScale(), UpdatePinchGesture()

关键生命周期方法

1. OnModifyDone()

调用时机：组件属性修改完成时

源码位置：scroll_pattern.cpp

执行流程：

void ScrollPattern::OnModifyDone()
{
    // 1. 处理轴变化
    auto axis = GetAxis();
    if (axis != lastAxis_) {
        // 重置位置
        ResetPosition();
        lastAxis_ = axis;
    }

    // 2. 初始化自由滚动控制器
    if (axis == Axis::FREE && !freeScroll_) {
        freeScroll_ = AceType::MakeRefPtr<FreeScrollController>(GetHost());
    }

    // 3. 设置滚动条
    SetScrollBarDisplay();

    // 4. 设置边缘效果
    HandleScrollEffect();

    // 5. 注册事件
    RegisterScrollBarEventTask();

    // 6. 计算 ScrollSnap 对齐点
    if (scrollSnapUpdate_) {
        CaleSnapOffsets(host);
        scrollSnapUpdate_ = false;
    }

    // 7. 处理缩放手势
    UpdatePinchGesture();
}

注意事项：

⚠️ 不要在 OnModifyDone 中触发布局
⚠️ 此时 geometryNode 可能还没有更新
✅ 可以访问 LayoutProperty 和 EventHub

2. OnDirtyLayoutWrapperSwap()

调用时机：布局结果交换时

源码位置：scroll_pattern.cpp

执行流程：

bool ScrollPattern::OnDirtyLayoutWrapperSwap(
    const RefPtr<LayoutWrapper>& dirty,
    const DirtySwapConfig& config)
{
    // 1. 获取 LayoutAlgorithm
    auto algorithm = DynamicCast<ScrollLayoutAlgorithm>(
        dirty->GetLayoutAlgorithm());
    CHECK_NULL_RETURN(algorithm, false);

    // 2. 同步布局结果
    scrollableDistance_ = algorithm->GetScrollableDistance();
    viewPort_ = algorithm->GetViewPort();
    viewPortExtent_ = algorithm->GetViewPortExtent();
    viewSize_ = algorithm->GetViewSize();

    // 3. 添加布局缓存
    if (dirty->ConstraintChanged() ||
        lastViewSize != viewSize_ ||
        lastViewPortExtent != viewPortExtent_) {
        AddScrollLayoutInfo();
    }

    // 4. 更新滚动条
    UpdateScrollBarOffset();

    // 5. 检查是否到达边界
    CheckScrollToEdge();

    return true;
}

注意事项：

✅ 这是访问布局结果的正确时机
✅ 可以安全地获取 geometryNode 数据
⚠️ 不要在此方法中修改 LayoutProperty

3. OnScrollCallback()

调用时机：滚动发生时（由手势触发）

源码位置：scroll_pattern.cpp

执行流程：

bool ScrollPattern::OnScrollCallback(float offset, int32_t source)
{
    // 1. 计算预测偏移（考虑 ScrollSnap）
    std::optional<float> predictSnapOffset;
    if (IsScrollSnap() && source != SCROLL_FROM_ANIMATION) {
        predictSnapOffset = CalcPredictSnapOffset(offset, 0.0f, 0.0f);
    }

    // 2. 更新当前偏移
    bool result = UpdateCurrentOffset(offset, source);

    // 3. 触发滚动事件
    FireOnDidScroll(offset);

    // 4. 检查边界
    if (IsAtTop()) {
        FireOnReachStart(onReachStart_, onJSFrameNodeReachStart_);
    }
    if (IsAtBottom()) {
        FireOnReachEnd(onReachEnd_, onJSFrameNodeReachEnd_);
    }

    return result;
}

注意事项：

⚠️ 此方法会在滚动过程中频繁调用
⚠️ 避免在回调中执行重计算
✅ 使用 OnScrollEndCallback 处理批量更新

状态变量详解

currentOffset_

含义：当前滚动偏移量

坐标系：

currentOffset_ = 0              → 在顶部
currentOffset_ > 0              → 内容向上偏移
currentOffset_ < 0              → 内容向下偏移
currentOffset_ = -scrollableDistance_ → 在底部

更新时机：

用户滑动手势
调用 ScrollTo() API
调用 ScrollBy() API
ScrollSnap 动画

scrollableDistance_

含义：可滚动距离

计算公式：

scrollableDistance_ = max(0, contentSize - viewportSize)

更新时机：

内容尺寸变化
视口尺寸变化
在 ScrollLayoutAlgorithm::Measure() 中重新计算

viewPortLength_

含义：视口长度（滚动方向上的可见区域大小）

计算：

垂直滚动：viewPortLength_ = viewPort_.Height()
水平滚动：viewPortLength_ = viewPort_.Width()

ScrollPattern 与 LayoutAlgorithm 的数据流

Pattern (scroll_pattern.cpp)
    ↓ 创建时
LayoutAlgorithm (scroll_layout_algorithm.cpp)
    ├─ 构造函数接收 currentOffset_
    ↓ Measure/Layout 计算
    ├─ 计算 scrollableDistance_
    ├─ 计算 viewPort_
    ├─ 计算 viewPortExtent_
    ↓ 返回结果
Pattern (OnDirtyLayoutWrapperSwap)
    ├─ 同步 scrollableDistance_
    ├─ 同步 viewPort_
    └─ 同步 viewPortExtent_

关键约束：

❌ LayoutAlgorithm 不应该直接访问 Pattern
❌ Pattern 不应该在布局过程中修改 LayoutAlgorithm 的状态
✅ 两者通过构造函数和返回值传递数据

Model层详解

ScrollModelNG 核心职责

ScrollModelNG 提供 ArkTS 声明式 API，负责：

创建 Scroll 节点
设置布局属性（通过 ScrollLayoutProperty）
注册事件处理（通过 ScrollEventHub）
管理滚动控制器（ScrollPositionController）