ArkUI Pipeline 模块完整知识库
文档版本：v1.0 更新时间：2026-02-04 源码版本：OpenHarmony ace_engine (master 分支) 作者：基于 CLAUDE.md 规范自动生成
目录
- 概述
- 核心架构
- 目录结构
- 核心类继承关系
- PipelineBase详解
- PipelineContext详解
- Component层详解
- Element层详解
- RenderNode层详解
- 生命周期管理
- 渲染流程
- 事件处理
- WindowManager
- Layer系统
- 执行流程
- 关键实现细节
- 附录
概述
模块定位
Pipeline 模块是 OpenHarmony ArkUI 框架中的核心渲染管道，负责 UI 组件从声明到显示的完整流程管理。它是连接前端（ArkTS/JavaScript）和后端渲染（Rosen/Skia）的桥梁。
技术栈：
- 前端接口：ArkTS/JavaScript
- 桥接层：JSViewAbstract + ViewAbstractModel
- 核心层：Component → Element → RenderNode 三层架构
- 渲染层：Rosen (RSNode) + Skia (Canvas)
代码规模：
- 总文件数：约 50 个文件
- 核心代码：约 30,000+ 行 C++ 代码
- 涉及 3 个架构层次
功能特性
Pipeline 模块支持：
- 三层架构：Component（声明）、Element（逻辑）、RenderNode（渲染）
- 生命周期管理：完整的组件创建、更新、销毁流程
- 渲染管道：布局计算、渲染绘制、显示同步
- 事件处理：触摸、键盘、鼠标、拖拽等输入事件
- 窗口管理：多窗口支持、窗口状态管理
- 动画系统：显式动画、隐式动画、页面转场
- 主题管理：多主题支持、动态切换
- 资源管理：图片缓存、字体管理、资源加载
设计模式
Pipeline 采用 三层架构模式 + 管道模式：
前端 (ArkTS/JS)
↓ (Bridge Layer - JSViewAbstract)
↓
Component Layer (声明层 - 不可变配置)
↓ (Element Layer - 逻辑层)
↓
Element Layer (逻辑层 - 可变状态管理)
↓ (RenderNode Layer - 渲染层)
↓
RenderNode Layer (渲染层 - 绘制单元)
↓
Rosen/Skia Backend
核心架构
三层架构设计
┌─────────────────────────────────────────────────────────┐
│ Component Layer (声明层) │
│ - 只读配置 │
│ - 描述组件的外观和行为 │
│ - 不可变对象 │
│ - 位置: frameworks/core/pipeline/base/component.h │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Element Layer (逻辑层) │
│ - 可变状态管理 │
│ - 生命周期控制 │
│ - 子元素管理 │
│ - 两类: RenderElement + ComposedElement │
│ - 位置: frameworks/core/pipeline/base/element.h │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ RenderNode Layer (渲染层) │
│ - 绘制单元 │
│ - 布局计算 │
│ - 渲染指令 │
│ - 位置: frameworks/core/pipeline/base/render_node.h │
└─────────────────────────────────────────────────────────┘
管道流程
Frontend Code (ArkTS)
↓
[Parse] 解析声明式 UI
↓
[Build] 创建 Component 树
↓
[Mount] 挂载到 Element 树
↓
[Layout] 计算布局
↓
[Render] 绘制渲染
↓
[Present] 显示到屏幕
目录结构
frameworks/core/pipeline/
├── base/ # 核心基础类
│ ├── component.h/cpp # Component 基类
│ ├── element.h/cpp # Element 基类
│ ├── composed_element.h/cpp # ComposedElement 组合元素
│ ├── render_element.h/cpp # RenderElement 渲染元素
│ ├── render_node.h/cpp # RenderNode 渲染节点
│ ├── element_register.h/cpp # Element 注册表
│ ├── render_context.h # 渲染上下文
│ ├── rosen_render_context.cpp # Rosen 渲染上下文
│ ├── flutter_render_context.cpp # Flutter 渲染上下文
│ ├── factories/ # 工厂类
│ │ ├── render_node_factory.h/cpp
│ │ └── render_factory.h
│ ├── multi_child.h # 多子节点混入
│ ├── single_child.h # 单子节点混入
│ └── constants.h/cpp # 常量定义
├── layers/ # 渲染层
│ ├── layer.h/cpp # Layer 基类
│ └── ...
├── pipeline_base.h/cpp # PipelineBase 管道基类
├── pipeline_context.h/cpp # PipelineContext 管道上下文
└── container_window_manager.h # 窗口管理器
核心类继承关系
核心类继承图
AceType (引用计数基类)
├── Component (声明层基类)
│ ├── RenderComponent
│ ├── ComposedComponent
│ └── [具体组件...]
│
├── Element (逻辑层基类)
│ ├── RenderElement (渲染元素)
│ │ └── [具体RenderElement...]
│ └── ComposedElement (组合元素)
│ └── [具体ComposedElement...]
│
├── RenderNode (渲染层基类)
│ ├── RenderBox
│ ├── RenderStack
│ └── [具体RenderNode...]
│
├── PipelineBase (管道基类)
│ └── PipelineContext
│
└── Layer (渲染层)
└── [具体Layer...]
三层映射关系
Component Element RenderNode
───────── ───────── ──────────
TextComponent → TextElement → RenderText
ButtonComponent → ButtonElement → RenderButton
ColumnComponent → ColumnElement → RenderColumn
...
PipelineBase详解
类定义
class ACE_FORCE_EXPORT PipelineBase : public virtual AceType {
DECLARE_ACE_TYPE(PipelineBase, AceType);
public:
// 静态方法
static RefPtr<PipelineBase> GetCurrentContext();
static RefPtr<PipelineBase> GetMainPipelineContext();
// 生命周期
virtual void SetupRootElement() = 0;
virtual void Destroy();
// Vsync 处理
virtual void OnVsyncEvent(uint64_t nanoTimestamp, uint64_t frameCount);
// 事件处理
virtual void OnTouchEvent(const TouchEvent& point, bool isSubPipe = false) = 0;
virtual bool OnNonPointerEvent(const NonPointerEvent& event) = 0;
virtual void OnMouseEvent(const MouseEvent& event) = 0;
virtual void OnAxisEvent(const AxisEvent& event) = 0;
// 表面变化
virtual void OnSurfaceChanged(int32_t width, int32_t height,
WindowSizeChangeReason type = WindowSizeChangeReason::UNDEFINED,
const std::shared_ptr<Rosen::RSTransaction>& rsTransaction = nullptr) = 0;
// 动画
bool Animate(const AnimationOption& option, const RefPtr<Curve>& curve,
const std::function<void()>& propertyCallback,
const std::function<void()>& finishCallBack = nullptr);
// 资源管理
RefPtr<AssetManager> GetAssetManager() const;
RefPtr<ThemeManager> GetThemeManager() const;
RefPtr<ImageCache> GetImageCache() const;
// 尺寸转换
double NormalizeToPx(const Dimension& dimension) const;
double ConvertPxToVp(const Dimension& dimension) const;
protected:
std::shared_ptr<Window> window_;
RefPtr<TaskExecutor> taskExecutor_;
RefPtr<AssetManager> assetManager_;
WeakPtr<Frontend> weakFrontend_;
RefPtr<ThemeManager> themeManager_;
RefPtr<ImageCache> imageCache_;
double density_ = 1.0;
double dipScale_ = 1.0;
float fontScale_ = 1.0f;
double rootWidth_ = 0.0;
double rootHeight_ = 0.0;
};
核心职责
-
窗口管理
- 窗口尺寸跟踪
- 密度（DPI）管理
- 系统栏高度管理
-
资源管理
- AssetManager：资源加载
- ThemeManager：主题管理
- ImageCache：图片缓存
- FontManager：字体管理
-
任务调度
- TaskExecutor：任务执行器
- Vsync同步
- 动画调度
-
事件分发
- 触摸事件
- 键盘事件
- 鼠标事件
- 滚轴事件
-
尺寸转换
- Px ↔ Vp 转换
- NormalizeToPx：维度转换
- 密度感知
PipelineContext详解
类定义
class ACE_FORCE_EXPORT PipelineContext : public PipelineBase {
DECLARE_ACE_TYPE(PipelineContext, PipelineBase);
public:
// 页面管理
void PushPage(const RefPtr<PageComponent>& pageComponent);
void PopPage();
void PopToPage(int32_t pageId);
void ReplacePage(const RefPtr<PageComponent>& pageComponent);
bool CanPopPage();
// 元素管理
void AddComposedElement(const ComposeId& id, const RefPtr<ComposedElement>& element);
void RemoveComposedElement(const ComposeId& id, const RefPtr<ComposedElement>& element);
void AddDirtyElement(const RefPtr<Element>& dirtyElement);
// 渲染管理
void AddDirtyRenderNode(const RefPtr<RenderNode>& renderNode, bool overlay = false);
void AddDirtyLayoutNode(const RefPtr<RenderNode>& renderNode);
void FlushPipelineImmediately();
// 焦点管理
bool RequestFocus(const std::string& targetNodeId, bool isSyncRequest = false);
void AddDirtyFocus(const RefPtr<FocusNode>& node);
// 对话框管理
RefPtr<DialogComponent> ShowDialog(const DialogProperties& dialogProperties,
bool isRightToLeft, const std::string& inspectorTag = "");
// Vsync 处理
void OnVsyncEvent(uint64_t nanoTimestamp, uint64_t frameCount) override;
// 表面变化
void OnSurfaceChanged(int32_t width, int32_t height, WindowSizeChangeReason type,
const std::shared_ptr<Rosen::RSTransaction>& rsTransaction,
const std::map<NG::SafeAreaAvoidType, NG::SafeAreaInsets>& safeAvoidArea) override;
private:
// 核心组件
RefPtr<RootElement> rootElement_;
RefPtr<RenderFactory> renderFactory_;
RefPtr<MultiModalManager> multiModalManager_;
RefPtr<SharedTransitionController> sharedTransitionController_;
RefPtr<CardTransitionController> cardTransitionController_;
// 脏节点管理
std::set<WeakPtr<Element>, NodeCompareWeak<WeakPtr<Element>>> dirtyElements_;
std::set<RefPtr<RenderNode>, NodeCompare<RefPtr<RenderNode>>> dirtyRenderNodes_;
std::set<RefPtr<RenderNode>, NodeCompare<RefPtr<RenderNode>>> dirtyLayoutNodes_;
// 页面栈管理
std::queue<std::function<void()>> pageUpdateTasks_;
std::map<int32_t, RefPtr<Element>> deactivateElements_;
};
核心职责
-
页面栈管理
- PushPage：入栈
- PopPage：出栈
- ReplacePage：替换
- 页面转场动画
-
元素树管理
- 根元素管理
- 组合元素映射（composedElementMap_）
- 脏元素跟踪
-
渲染管道
- FlushLayout：布局刷新
- FlushRender：渲染刷新
- FlushAnimation：动画刷新
- FlushVsync：垂直同步
-
焦点管理
- 焦点请求
- 焦点树构建
- 焦点动画
-
对话框/Overlay
- Dialog显示/关闭
- Overlay管理
- 上下文菜单
Component层详解
Component基类
核心特性：
- 不可变性：Component 是只读配置对象
- 声明式：描述组件的属性和行为
- 轻量级：易于创建和销毁
class ACE_FORCE_EXPORT Component : public virtual AceType {
public:
// 创建对应的 Element
virtual RefPtr<Element> CreateElement() = 0;
// 属性访问
TextDirection GetTextDirection() const;
bool IsDisabledStatus() const;
bool IsTouchable() const;
// 事件标记
void SetOnAppearEventId(const EventMarker& appearEventId);
void SetOnDisappearEventId(const EventMarker& disappearEventId);
// 元素 ID（用于增量更新）
void AssignUniqueElementId(ElementIdType elmtId);
ElementIdType GetElementId() const;
protected:
WeakPtr<Component> parent_;
bool disabledStatus_ = false;
bool touchable_ = true;
int32_t retakeId_ = 0;
EventMarker appearEventId_;
EventMarker disappearEventId_;
ElementIdType elmtId_ = ElementRegister::UndefinedElementId;
};
Component分类
Component
├── RenderComponent (有RenderNode的组件)
│ ├── SingleChild
│ ├── MultiChild
│ └── [具体组件...]
│
└── ComposedComponent (组合组件)
├── SoleChildComponent
└── MultiComposedComponent
关键属性
| 属性 | 类型 | 说明 |
|---|---|---|
retakeId_ |
int32_t | 用于Component-Element对应关系 |
elmtId_ |
ElementIdType | 全局唯一ID，用于增量更新 |
disabledStatus_ |
bool | 禁用状态 |
touchable_ |
bool | 可触摸状态 |
appearEventId_ |
EventMarker | 出现事件 |
disappearEventId_ |
EventMarker | 消失事件 |
Element层详解
Element基类
位置：element.h:40
核心特性：
- 可变性：Element 管理可变状态
- 生命周期：Mount → Activate → Deactivate → Detach
- 子元素管理：维护子元素列表
class ACE_FORCE_EXPORT Element : public virtual AceType {
public:
// 生命周期
virtual void OnMount() {}
virtual void Activate() {}
virtual void Deactivate() {}
virtual void Detached() {}
// 子元素管理
void AddChild(const RefPtr<Element>& child, int32_t slot = DEFAULT_ELEMENT_SLOT);
void RemoveChild(const RefPtr<Element>& child);
RefPtr<Element> UpdateChild(const RefPtr<Element>& child,
const RefPtr<Component>& newComponent) = 0;
// 构建
void Rebuild();
virtual void PerformBuild() {}
// 渲染节点
virtual RefPtr<RenderNode> GetRenderNode() const;
// 焦点
void AddToFocus();
RefPtr<FocusGroup> GetFocusScope();
// 增量更新
virtual void LocalizedUpdate();
virtual void UnregisterForPartialUpdates();
// Element ID
void SetElementId(int32_t elmtId);
int32_t GetElementId() const;
protected:
std::list<RefPtr<Element>> children_;
RefPtr<Component> component_;
WeakPtr<PipelineContext> context_;
WeakPtr<Element> parent_;
int32_t depth_ = 0;
int32_t slot_ = DEFAULT_ELEMENT_SLOT;
int32_t retakeId_ = 0;
int32_t elmtId_ = ElementRegister::UndefinedElementId;
bool active_ = false;
bool needRebuild_ = false;
};
Element类型
Element
├── RenderElement (有RenderNode的Element)
│ └── 直接对应 RenderNode
│
└── ComposedElement (组合Element)
└── 管理子Element树
RenderElement详解
class ACE_FORCE_EXPORT RenderElement : public Element {
public:
RefPtr<RenderNode> GetRenderNode() const override { return renderNode_; }
void SetRenderNode(RefPtr<RenderNode> renderNode);
protected:
virtual RefPtr<RenderNode> CreateRenderNode();
virtual RefPtr<RenderNode> GetCachedRenderNode();
RefPtr<RenderNode> renderNode_;
};
ComposedElement详解
class ACE_FORCE_EXPORT ComposedElement : public Element {
public:
// 渲染函数
using RenderFunction = std::function<RefPtr<Component>(const RefPtr<Component>&)>;
RefPtr<Component> CallRenderFunction(const RefPtr<Component>& component);
void SetRenderFunction(RenderFunction&& func);
bool HasRenderFunction();
// 移除函数
void CallRemoveFunction();
void SetRemoveFunction(RemoveFunction&& func);
// 页面转场
RefPtr<Component> CallPageTransitionFunction();
void SetPageTransitionFunction(PageTransitionFunction&& func);
const ComposeId& GetId() const { return id_; }
protected:
virtual RefPtr<Component> BuildChild();
ComposeId id_;
std::string name_;
RenderFunction renderFunction_;
RemoveFunction removeFunction_;
PageTransitionFunction pageTransitionFunction_;
};
RenderNode层详解
RenderNode基类
核心特性：
- 渲染单元：实际参与绘制的节点
- 布局计算：测量和布局
- 渲染绘制：Paint 方法
- RSNode同步：与Rosen后端同步
class ACE_EXPORT RenderNode : public PropertyAnimatable,
public AnimatableProperties,
public virtual AceType {
public:
// 子节点管理
void AddChild(const RefPtr<RenderNode>& child, int32_t slot);
void RemoveChild(const RefPtr<RenderNode>& child);
void ClearChildren();
// 更新
void UpdateAll(const RefPtr<Component>& component);
virtual void Update(const RefPtr<Component>& component) = 0;
// 布局
void Layout(const LayoutParam& layoutParam);
virtual void PerformLayout() = 0;
void MarkNeedLayout(bool selfOnly = false, bool forceParent = false);
// 渲染
virtual void Paint(RenderContext& context, const Offset& offset);
void MarkNeedRender(bool overlay = false);
// 触摸测试
virtual bool TouchTest(const Point& globalPoint, const Point& parentLocalPoint,
const TouchRestrict& touchRestrict, TouchTestResult& result);
// 鼠标测试
virtual void MouseTest(const Point& globalPoint, const Point& parentLocalPoint,
MouseRawResult& result);
// 尺寸和位置
Size GetLayoutSize() const;
Offset GetPosition() const;
void SetPosition(const Offset& offset);
void SetLayoutSize(const Size& size);
// 可见性
virtual void SetVisible(bool visible, bool inRecursion = false);
virtual bool GetVisible() const { return visible_; }
// 不透明度
uint8_t GetOpacity() const;
virtual void UpdateOpacity(uint8_t opacity);
// RSNode（Rosen后端）
const std::shared_ptr<RSNode>& GetRSNode() const { return rsNode_; }
virtual void SyncGeometryProperties();
bool IsHeadRenderNode() const;
bool IsTailRenderNode() const;
// 可访问性
void SetAccessibilityNode(const WeakPtr<AccessibilityNode>& node);
const WeakPtr<AccessibilityNode>& GetAccessibilityNode() const;
// 恢复信息
virtual std::string ProvideRestoreInfo() { return ""; }
void SetRestoreInfo(const std::string& restoreInfo);
protected:
std::list<RefPtr<RenderNode>> children_;
WeakPtr<RenderNode> parent_;
WeakPtr<PipelineContext> context_;
LayoutParam layoutParam_;
Rect paintRect_;
uint8_t opacity_ = 255;
bool visible_ = true;
bool needLayout_ = false;
bool needRender_ = false;
int32_t depth_ = 0;
std::shared_ptr<RSNode> rsNode_ = nullptr;
bool isHeadRenderNode_ = false;
bool isTailRenderNode_ = false;
};
布局流程
// 1. 设置布局参数
void Layout(const LayoutParam& layoutParam) {
layoutParam_ = layoutParam;
layoutParamChanged_ = true;
SetNeedLayout(true);
OnLayout(); // 触发布局
}
// 2. 执行布局
virtual void PerformLayout() = 0; // 子类实现
// 3. 标记需要布局
void MarkNeedLayout(bool selfOnly, bool forceParent) {
needLayout_ = true;
if (!selfOnly) {
auto parent = parent_.Upgrade();
if (parent) {
parent->MarkNeedLayout();
}
}
}
渲染流程
// 1. 标记需要渲染
void MarkNeedRender(bool overlay) {
needRender_ = true;
auto context = context_.Upgrade();
if (context) {
context->AddDirtyRenderNode(AceType::Claim(this), overlay);
}
}
// 2. 渲染
virtual void Paint(RenderContext& context, const Offset& offset) {
// 1. 绘制自己
// 2. 绘制子节点
for (const auto& child : children_) {
PaintChild(child, context, offset + paintRect_.GetOffset());
}
}
RSNode同步（Rosen后端）
// 同步几何属性到RSNode
virtual void SyncGeometryProperties() {
if (!rsNode_) return;
auto offset = GetGlobalOffset();
auto size = GetLayoutSize();
rsNode_->SetBounds(offset.GetX(), offset.GetY(),
size.Width(), size.Height());
if (HasEffectiveTransform()) {
rsNode_->SetTransform(GetTransformByGlobalOffset());
}
}
// 是否是RSNode边界
bool IsHeadRenderNode() const {
return isHeadRenderNode_;
}
生命周期管理
Element生命周期
Mount（挂载）
↓
Prepare（准备）
↓
Activate（激活）
↓
[Active状态 - 接收更新和事件]
↓
Deactivate（停用）
↓
Detach（分离）
生命周期方法
| 方法 | 阶段 | 说明 |
|---|---|---|
Prepare() |
挂载前 | 准备阶段，设置父元素 |
OnMount() |
挂载时 | 刚挂载到元素树 |
Activate() |
激活时 | 激活，开始接收更新 |
PerformBuild() |
构建时 | 执行构建逻辑 |
Update() |
更新时 | 接收新Component并更新 |
Deactivate() |
停用时 | 停用，不再接收更新 |
Detached() |
分离时 | 从元素树分离 |
UmountRender() |
卸载渲染 | 卸载渲染节点 |
RenderNode生命周期
Create（创建）
↓
Attach（附加到PipelineContext）
↓
OnAttachContext（上下文附加）
↓
[Ready状态 - 接收布局和渲染]
↓
Unmount（从渲染树卸载）
渲染流程
完整渲染管道
Vsync信号到达
↓
FlushVsync()
↓
ProcessPreFlush() → PreFlushListeners
↓
FlushAnimation() → 动画更新
↓
FlushLayout() → 布局计算
↓
FlushRender() → 渲染绘制
↓
FlushRenderFinish() → 渲染完成回调
↓
ProcessPostFlush() → PostFlushListeners
布局刷新（FlushLayout）
void PipelineContext::FlushLayout() {
// 1. 获取所有需要布局的节点
auto nodes = std::move(dirtyLayoutNodes_);
// 2. 按深度排序
nodes.sort(NodeCompare<RefPtr<RenderNode>>());
// 3. 依次执行布局
for (const auto& node : nodes) {
if (node->NeedLayout()) {
node->OnLayout(); // 触发PerformLayout
}
}
}
渲染刷新（FlushRender）
void PipelineContext::FlushRender() {
// 1. 获取所有需要渲染的节点
auto nodes = std::move(dirtyRenderNodes_);
// 2. 按深度排序
nodes.sort(NodeCompare<RefPtr<RenderNode>>());
// 3. 依次执行渲染
for (const auto& node : nodes) {
if (node->NeedRender()) {
node->Paint(*renderContext_, node->GetGlobalOffset());
}
}
// 4. 通知Rosen后端
if (rsUIDirector_) {
rsUIDirector_->SendMessages();
}
}
动画刷新（FlushAnimation）
void PipelineContext::FlushAnimation(uint64_t nanoTimestamp) {
// 1. 更新所有动画
for (auto& animator : animators_) {
animator->Animate(nanoTimestamp);
}
// 2. 触发属性动画
PropertyAnimatable::Animate(nanoTimestamp);
}
事件处理
事件类型
| 事件 | 触发方式 | 处理方法 |
|---|---|---|
| 触摸事件 | 手指触摸 | OnTouchEvent() |
| 键盘事件 | 键盘输入 | OnNonPointerEvent() |
| 鼠标事件 | 鼠标移动/点击 | OnMouseEvent() |
| 滚轴事件 | 鼠标滚轮 | OnAxisEvent() |
| 旋转事件 | 屏幕旋转 | OnRotationEvent() |
触摸事件流程
系统触摸事件
↓
PipelineContext::OnTouchEvent()
↓
RenderNode::TouchTest()
↓
递归查找命中节点
↓
GestureRecognizer识别手势
↓
触发回调
触摸测试
virtual bool TouchTest(const Point& globalPoint, const Point& parentLocalPoint,
const TouchRestrict& touchRestrict, TouchTestResult& result) {
// 1. 检查可见性
if (!visible_ || hidden_) {
return false;
}
// 2. 检查触摸区域
if (!InTouchRectList(parentLocalPoint, GetTouchRectList())) {
return false;
}
// 3. 递归测试子节点
Point localPoint = parentLocalPoint - paintRect_.GetOffset();
for (auto iter = children_.rbegin(); iter != children_.rend(); ++iter) {
const auto& child = *iter;
if (child->TouchTest(globalPoint, localPoint, touchRestrict, result)) {
break; // 找到最顶层命中节点
}
}
// 4. 添加自己的手势识别器
OnTouchTestHit(localPoint - paintRect_.GetOffset(), touchRestrict, result);
return true;
}
WindowManager
WindowManager类
位置：container_window_manager.h:70
核心职责：
- 窗口状态管理（最小化、最大化、关闭）
- 系统栏样式管理
- 窗口模式管理
- 页面视口配置
class WindowManager : public virtual AceType {
public:
// 窗口操作
void WindowMinimize() const;
void WindowMaximize(bool supportFloatingMaximize = false);
void WindowRecover();
void WindowClose() const;
void WindowStartMove() const;
// 窗口状态
WindowMode GetWindowMode() const;
WindowType GetWindowType() const;
MaximizeMode GetWindowMaximizeMode() const;
// 系统栏样式
RefPtr<SystemBarStyle> GetSystemBarStyle();
void SetSystemBarStyle(const RefPtr<SystemBarStyle>& style);
bool SetWindowSystemBarEnabled(SystemBarType type,
std::optional<bool> enabled, std::optional<bool> needAnimation);
// 页面视口配置
bool GetPageViewportConfig(
const PageViewportConfigParams& currentParams,
RefPtr<PageViewportConfig>& currentConfig,
const PageViewportConfigParams& targetParams,
RefPtr<PageViewportConfig>& targetConfig);
// 屏幕方向
bool IsSetOrientationNeeded(std::optional<Orientation> orientation);
void SetRequestedOrientation(std::optional<Orientation> orientation,
bool needAnimation = true);
Orientation GetRequestedOrientation() const;
private:
WindowCallback windowMinimizeCallback_;
WindowCallback windowMaximizeCallback_;
WindowCallback windowRecoverCallback_;
WindowCallback windowCloseCallback_;
WindowModeCallback windowGetModeCallback_;
GetSystemBarStyleCallback getSystemBarStyleCallback_;
SetSystemBarStyleCallback setSystemBarStyleCallback_;
// ... 更多回调
};
窗口模式
enum class WindowMode {
WINDOW_MODE_UNDEFINED,
WINDOW_MODE_FULLSCREEN,
WINDOW_MODE_PRIMARY,
WINDOW_MODE_SECONDARY,
WINDOW_MODE_FLOATING,
};
Layer系统
Layer基类
位置：layer.h:27
核心特性：
- 渲染层的抽象表示
- 支持层级结构
- 用于Flutter渲染后端
namespace OHOS::Ace::Flutter {
class Layer : public AceType {
public:
// 父子关系
WeakPtr<Layer> GetParent() { return parentLayer_; }
void SetParent(const RefPtr<Layer>& layer);
// 添加到场景
virtual void AddToScene(SceneBuilder& builder, double x, double y) = 0;
// 子节点管理
void AddChildren(const RefPtr<Layer>& layer);
void RemoveChildren();
const std::list<RefPtr<Layer>>& GetChildren() const { return children_; }
// 调试
virtual void DumpTree(int32_t depth);
virtual void Dump() = 0;
protected:
WeakPtr<Layer> parentLayer_;
std::list<RefPtr<Layer>> children_;
};
} // namespace OHOS::Ace::Flutter
Layer类型
Layer
├── PictureLayer (图片层)
├── TextureLayer (纹理层)
├── ContainerLayer (容器层)
│ ├── TransformLayer (变换层)
│ ├── ClipPathLayer (裁剪层)
│ ├── ClipRectLayer (矩形裁剪层)
│ ├── ClipRRectLayer (圆角裁剪层)
│ ├── OpacityLayer (透明度层)
│ └── OffsetLayer (偏移层)
└── PerformanceOverlayLayer (性能覆盖层)
执行流程
应用启动流程
main()
↓
Ace::RunPage()
↓
PipelineContext::SetupRootElement()
↓
创建 RootElement
↓
Frontend::BuildPage()
↓
创建 Component 树
↓
Component::CreateElement()
↓
生成 Element 树
↓
RenderElement::CreateRenderNode()
↓
生成 RenderNode 树
↓
PipelineContext::FlushPipeline()
↓
首次布局和渲染
页面跳转流程
router.push()
↓
Frontend::Push()
↓
PipelineContext::PushPage()
↓
创建新 PageComponent
↓
创建新 Element 和 RenderNode
↓
页面转场动画
↓
更新页面栈
组件更新流程
状态改变
↓
Frontend::UpdatePage()
↓
创建新 Component
↓
Element::UpdateChild()
↓
RenderNode::Update()
↓
标记 Dirty
↓
PipelineContext::FlushPipeline()
↓
布局和渲染
关键实现细节
Element-Component对应关系
RetakeId机制：
// Component设置retakeId
void Component::SetRetakeId(int32_t retakeId) {
retakeId_ = retakeId;
}
// Element获取retakeId
void Element::SetNewComponent(const RefPtr<Component>& newComponent) {
component_ = newComponent;
if (newComponent) {
retakeId_ = newComponent->GetRetakeId(); // 同步retakeId
MarkNeedRebuild();
}
}
用途：
- 用于Component和Element的对应关系
- 支持组件的增量更新
- 识别相同类型的Component
增量更新机制
ElementId机制：
// Component分配ElementId
void Component::AssignUniqueElementId(ElementIdType elmtId) {
elmtId_ = elmtId;
}
// Element设置ElementId
void Element::SetElementId(int32_t elmtId) {
elmtId_ = elmtId;
}
// 增量更新
void Element::LocalizedUpdateWithComponent(
const RefPtr<Component>& newComponent,
const RefPtr<Component>& outmostWrappingComponent) {
// 局部更新，不需要重建整个子树
LocalizedUpdate();
}
脏节点管理
节点比较器：
template<typename T>
struct NodeCompare {
bool operator()(const T& nodeLeft, const T& nodeRight) const {
if (nodeLeft->GetDepth() < nodeRight->GetDepth()) {
return true; // 深度小的在前
}
if (nodeLeft->GetDepth() == nodeRight->GetDepth()) {
return nodeLeft < nodeRight; // 深度相同，按指针排序
}
return false;
}
};
排序目的：
- 确保父节点先于子节点处理
- 保证布局和渲染的正确顺序
RSNode边界管理
Head/Tail机制：
// JSView边界内的所有节点共享同一个RSNode
bool IsHeadRenderNode() const { return isHeadRenderNode_; }
bool IsTailRenderNode() const { return isTailRenderNode_; }
// 同步边界
void SyncRSNodeBoundary(bool isHead, bool isTail,
const RefPtr<Component>& component = nullptr);
用途：
- 减少RSNode数量
- 提高渲染性能
- 支持外部RSNode
焦点管理
焦点树构建：
void Element::RebuildFocusTree() {
// 1. 清空现有焦点树
// 2. 重新构建
auto children = RebuildFocusChild();
// 3. 注册到FocusScope
}
std::list<RefPtr<FocusNode>> Element::RebuildFocusChild() {
std::list<RefPtr<FocusNode>> focusNodes;
for (const auto& child : children_) {
if (child->IsActive()) {
auto childFocusNodes = child->RebuildFocusChild();
focusNodes.splice(focusNodes.end(), childFocusNodes);
}
}
return focusNodes;
}
附录
关键文件索引
| 文件 | 行数 | 说明 |
|---|---|---|
| pipeline_base.h | 1912 | PipelineBase基类 |
| pipeline_context.h | 1050 | PipelineContext实现 |
| component.h | 339 | Component基类 |
| element.h | 337 | Element基类 |
| render_node.h | 1361 | RenderNode基类 |
| composed_element.h | 153 | ComposedElement |
| render_element.h | 88 | RenderElement |
| container_window_manager.h | 511 | WindowManager |
| layer.h | 72 | Layer基类 |
相关文档
参考资源
- OpenHarmony文档: https://docs.openharmony.cn/
- ArkUI文档: https://developer.huawei.com/consumer/cn/doc/
- 源码仓库: https://gitee.com/openharmony/ace_ace_engine
文档维护：
- 请根据代码变更及时更新本文档
- 新增功能请补充相关章节
- 发现错误请及时修正
最后更新: 2026-02-04 文档状态: ✅ 完成