ArkUI Badge 组件完整知识库

文档版本：v2.0 深度扩充版 更新时间：2026-02-03 源码版本：OpenHarmony ace_engine (master 分支) 快速参考：请参考 Badge/CLAUDE.md

---

📚 目录

1. 概述
2. 完整调用链
3. 目录结构
4. 核心类继承关系
5. 设计决策分析
6. 实现原理深挖
7. 问题排查手册
8. 跨组件交互
9. 性能分析
10. 附录

---

概述

组件定位

Badge 组件是 OpenHarmony ArkUI 框架中的标记组件，用于在组件上附加圆点、数字或文字标记，常用于显示通知数量、状态标记等场景。

技术栈：

• 前端：ArkTS/JavaScript
• 桥接层：BadgeModelNG + ViewAbstractModel
• 核心层：NG Pattern 架构
• 渲染层：Rosen + Skia

代码规模：

项目	数量
核心文件	约 7 个文件
核心代码	约 1,500 行 C++ 代码
Pattern 文件	badge_pattern.cpp (~550 行)
LayoutAlgorithm 文件	badge_layout_algorithm.cpp (~400 行)

功能特性

功能类别	具体功能
标记类型	数字标记、文字标记、圆点标记
位置选项	右上角、右侧、左侧、自定义 X/Y 坐标
样式定制	颜色、字体大小、边框、外边框、圆角等
计数限制	支持最大计数显示（默认 99+）
老年模式	fontSizeScale >= 1.75 时自动放大
无障碍	完整的 Accessibility 支持
主题适配	支持系统颜色配置更新

设计模式

Badge 组件采用 NG Pattern 架构：

┌─────────────────────────────────────────────────────────┐
│  应用层 (ArkTS)                                           │
│  Badge({ count: 5 }) { Child() }                         │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  桥接层 (Model Layer)                                    │
│  BadgeModelNG::Create() → FrameNode 创建                │
│  源码：badge_model_ng.cpp:24-34                          │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  核心层 (Pattern Layer)                                  │
│  BadgePattern                                            │
│  ├── 内部创建 Text 子节点用于显示内容                     │
│  ├── OnModifyDone 更新显示                                │
│  └── 主题更新处理                                         │
│  源码：badge_pattern.cpp                                  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  布局层 (LayoutAlgorithm Layer)                          │
│  BadgeLayoutAlgorithm                                    │
│  ├── 圆形/长条形尺寸计算                                   │
│  ├── 老年模式适配                                         │
│  └── RTL 布局支持                                         │
│  源码：badge_layout_algorithm.cpp                          │
└─────────────────────────────────────────────────────────┘
                          ↓
                    [Badge 显示在屏幕上]

---

完整调用链

创建流程调用链

┌─────────────────────────────────────────────────────────┐
│ 前端 ArkTS 调用                                          │
│                                                          │
│ Badge({ count: 5 }) { Text('Message') }                   │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ BadgeModelNG::Create(BadgeParameters&)                    │
│ 源码：frameworks/core/components_ng/pattern/badge/       │
│       badge_model_ng.cpp:24-34                           │
│                                                          │
│ 执行流程：                                                 │
│ 1. ViewStackProcessor::GetInstance() 获取栈              │
│ 2. stack->ClaimNodeId() 申请节点 ID                       │
│ 3. FrameNode::GetOrCreateFrameNode() 创建 FrameNode     │
│    └── 工厂函数: []() { return AceType::MakeRefPtr<      │
│           BadgePattern>(); }                              │
│ 4. stack->Push(frameNode) 推入视图栈                     │
│ 5. CreateByFrameNode() 应用参数                           │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ BadgeModelNG::CreateByFrameNode()                         │
│ 源码：badge_model_ng.cpp:46-94                            │
│                                                          │
│ 执行流程：                                                 │
│ 1. 获取 BadgeTheme 默认值                                │
│ 2. 设置 BadgeValue/BadgeCount                            │
│ 3. 设置 BadgeMaxCount (默认 99)                          │
│ 4. 设置 BadgePosition (默认 RightTop)                    │
│ 5. 调用 UpdateBadgeStyle() 设置样式                       │
│ 6. 处理资源对象（ResourceObject）用于主题更新             │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ BadgePattern::OnModifyDone()                              │
│ 源码：badge_pattern.cpp:24-133                            │
│                                                          │
│ 执行流程：                                                 │
│ 1. 检查是否需要创建 Text 子节点                           │
│    └── 比较 lastFrameNode->GetId() 与 textNodeId_        │
│ 2. 创建 Text 子节点（V2::TEXT_ETS_TAG）                   │
│ 3. 处理 BadgeCount：数字标记模式                          │
│    └── 超过 maxCount 显示 "99+"                           │
│ 4. 处理 BadgeValue：文字标记模式                          │
│ 5. 设置文本样式（颜色、字体、居中等）                     │
│ 6. 设置背景色和圆角                                       │
│ 7. 设置可见性（badgeVisible）                             │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ BadgeLayoutAlgorithm::Measure()                           │
│ 源码：badge_layout_algorithm.cpp:29-154                    │
│                                                          │
│ 执行流程：                                                 │
│ 1. 获取字体缩放系数 fontSizeScale                         │
│ 2. 应用老年模式（fontSizeScale >= 1.75）                  │
│ 3. 计算 Badge 尺寸：                                     │
│    ├── 单字符/小数字：圆形 (宽=高)                        │
│    └── 多字符/大数字：长条形 (宽=文字宽+padding)           │
│ 4. 测量 Text 子节点                                       │
│ 5. 测量子节点（被标记的组件）                             │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ BadgeLayoutAlgorithm::Layout()                            │
│ 源码：badge_layout_algorithm.cpp:234-367                   │
│                                                          │
│ 执行流程：                                                 │
│ 1. 根据 BadgePosition 计算基础位置                       │
│ 2. 应用 RTL 偏移（布局方向为 RTL 时）                     │
│ 3. 应用 badgePositionX/Y 自定义偏移                       │
│ 4. 布局 Text 子节点                                       │
│ 5. 布局子节点（被标记的组件）                             │
└─────────────────────────────────────────────────────────┘
                          ↓
                    [Badge 显示在屏幕上]

关键代码片段

① Model层创建 - badge_model_ng.cpp:24-34

void BadgeModelNG::Create(BadgeParameters& badgeParameters)
{
    auto* stack = ViewStackProcessor::GetInstance();
    int32_t nodeId = (stack == nullptr ? 0 : stack->ClaimNodeId());
    ACE_LAYOUT_SCOPED_TRACE("Create[%s][self:%d]", V2::BADGE_ETS_TAG, nodeId);

    // 创建 Badge FrameNode，使用 lambda 工厂函数创建 BadgePattern
    auto frameNode = FrameNode::GetOrCreateFrameNode(
        V2::BADGE_ETS_TAG, nodeId,
        []() { return AceType::MakeRefPtr<BadgePattern>(); });
    ACE_UINODE_TRACE(frameNode);
    ViewStackProcessor::GetInstance()->Push(frameNode);

    CreateByFrameNode(frameNode, badgeParameters);
}

② 参数设置 - badge_model_ng.cpp:46-94

void BadgeModelNG::CreateByFrameNode(
    const RefPtr<FrameNode>& frameNode,
    BadgeParameters& badgeParameters)
{
    CHECK_NULL_VOID(frameNode);
    auto pipeline = PipelineBase::GetCurrentContext();
    CHECK_NULL_VOID(pipeline);
    auto badgeTheme = pipeline->GetTheme<BadgeTheme>();

    auto layoutProperty = frameNode->GetLayoutProperty<BadgeLayoutProperty>();
    layoutProperty->SetIsDefault(isDefaultFontSize_, isDefaultBadgeSize_);

    // 设置内容属性
    if (badgeParameters.badgeValue.has_value()) {
        layoutProperty->UpdateBadgeValue(badgeParameters.badgeValue.value());
    }
    if (badgeParameters.badgeCount.has_value()) {
        layoutProperty->UpdateBadgeCount(badgeParameters.badgeCount.value());
    }
    if (badgeParameters.badgeMaxCount.has_value()) {
        layoutProperty->UpdateBadgeMaxCount(badgeParameters.badgeMaxCount.value());
    } else {
        layoutProperty->UpdateBadgeMaxCount(badgeTheme->GetMaxCount());  // 默认 99
    }

    // 设置位置属性
    if (badgeParameters.badgePosition.has_value()) {
        auto badgePosition = static_cast<BadgePosition>(badgeParameters.badgePosition.value());
        layoutProperty->UpdateBadgePosition(badgePosition);
    } else {
        layoutProperty->UpdateBadgePosition(badgeTheme->GetBadgePosition());  // 默认 RightTop
    }

    // 设置样式属性
    UpdateBadgeStyle(badgeParameters, frameNode);

    // 处理资源对象（用于主题动态更新）
    if (SystemProperties::ConfigChangePerform()) {
        CreateWithResourceObj(frameNode, badgeParameters);
        CreateWithResourceObjFlag(frameNode, badgeParameters);
    }
}

③ Pattern层OnModifyDone - badge_pattern.cpp:24-133

void BadgePattern::OnModifyDone()
{
    Pattern::OnModifyDone();
    auto frameNode = GetHost();
    CHECK_NULL_VOID(frameNode);

    // 1. 创建或获取 Text 子节点
    auto needCreateText = false;
    auto lastFrameNode = AceType::DynamicCast<FrameNode>(frameNode->GetChildren().back());
    if (lastFrameNode) {
        needCreateText = lastFrameNode->GetId() != textNodeId_;
    }
    if (needCreateText) {
        textNodeId_ = ElementRegister::GetInstance()->MakeUniqueId();
        lastFrameNode = FrameNode::GetOrCreateFrameNode(
            V2::TEXT_ETS_TAG, textNodeId_,
            []() { return AceType::MakeRefPtr<TextPattern>(); });
        lastFrameNode->MountToParent(frameNode);
    }

    auto textLayoutProperty = lastFrameNode->GetLayoutProperty<TextLayoutProperty>();
    auto layoutProperty = frameNode->GetLayoutProperty<BadgeLayoutProperty>();

    // 2. 处理数字标记模式
    auto badgeCount = layoutProperty->GetBadgeCount();
    bool badgeVisible = false;
    if (badgeCount.has_value() && badgeCount.value() > 0) {
        auto badgeMaxCount = layoutProperty->GetBadgeMaxCount().value_or(99);
        auto content = std::to_string(badgeCount.value());
        if (badgeCount.value() > badgeMaxCount) {
            content = std::to_string(badgeMaxCount) + "+";  // 显示 "99+"
        }
        textLayoutProperty->UpdateContent(content);
        badgeVisible = true;
    }

    // 3. 处理文字标记模式
    auto badgeValue = layoutProperty->GetBadgeValue();
    if (badgeValue.has_value()) {
        textLayoutProperty->UpdateContent(badgeValue.value());
        badgeVisible = true;
    }

    // 4. 设置文本样式
    auto badgeTheme = pipeline->GetTheme<BadgeTheme>();
    auto badgeTextColor = layoutProperty->GetBadgeTextColor();
    textLayoutProperty->UpdateTextColor(badgeTextColor.value_or(badgeTheme->GetBadgeTextColor()));

    auto badgeFontSize = layoutProperty->GetBadgeFontSize();
    if (badgeFontSize.has_value()) {
        textLayoutProperty->UpdateFontSize(badgeFontSize.value());
    }

    textLayoutProperty->UpdateMaxLines(1);
    textLayoutProperty->UpdateTextAlign(TextAlign::CENTER);

    // 5. 设置背景色和圆角
    auto badgeColor = layoutProperty->GetBadgeColorValue(badgeTheme->GetBadgeColor());
    auto textRenderContext = lastFrameNode->GetRenderContext();
    textRenderContext->SetVisible(badgeVisible);
    textRenderContext->UpdateBackgroundColor(badgeColor);

    BorderRadiusProperty radius;
    radius.SetRadius(Dimension(badgeCircleRadius + borderWidth.ConvertToPx()));
    textRenderContext->UpdateBorderRadius(radius);
}

④ LayoutAlgorithm层测量 - badge_layout_algorithm.cpp:29-100

void BadgeLayoutAlgorithm::Measure(LayoutWrapper* layoutWrapper)
{
    auto host = layoutWrapper->GetHostNode();
    auto layoutProperty = AceType::DynamicCast<BadgeLayoutProperty>(layoutWrapper->GetLayoutProperty());
    auto badgeTheme = pipeline->GetTheme<BadgeTheme>();

    // 应用字体缩放（老年模式）
    double fontSizeScale = pipeline->GetFontScale();
    const double AGE_FONT_SIZE_SCALE = 1.75;

    if (fontSizeScale >= AGE_FONT_SIZE_SCALE) {
        if (isDefaultFontSize) {
            fontSizeInit = badgeTheme->GetBadgeAgeFontSize().ConvertToVp();
        }
        if (isDefaultBadgeSize) {
            badgeSizeInit = badgeTheme->GetBadgeAgeCircleSize().ConvertToVp();
        }
    }

    // 计算 Badge 尺寸
    auto textData = textLayoutProperty->GetContent();
    if ((textData.size() <= 1) || (messageCount < 10 && messageCount <= countLimit)) {
        // 单字符或小数字：使用圆形尺寸
        badgeCircleDiameter = std::max(textSize.Height(), badgeCircleDiameter);
        badgeWidth = badgeCircleDiameter;
    } else if (textData.size() > 1 || messageCount > countLimit) {
        // 多字符或大数字：宽度 = 文字宽度 + padding
        badgeWidth = textSize.Width() + badgeTheme->GetNumericalBadgePadding() * 2;
        badgeWidth = std::max(badgeCircleDiameter, badgeWidth);
    }
}

---

目录结构

components_ng/pattern/badge/
├── badge_pattern.h/cpp                    # Pattern 层：业务逻辑 (~550 行)
├── badge_layout_property.h/cpp            # 布局属性 (~200 行)
├── badge_layout_algorithm.h/cpp           # 布局算法 (~400 行)
├── badge_model.h                          # Model 接口定义
├── badge_model_ng.h/cpp                   # NG Model 实现 (~200 行)
├── badge_accessibility_property.h/cpp     # 无障碍属性
└── badge_data.h                           # 数据结构定义 (~80 行)

相关路径：

• Pattern 层：frameworks/core/components_ng/pattern/badge/
• 兼容层：frameworks/compatible/components/badge/
• 主题定义：frameworks/core/components/badge/badge_theme.h

---

核心类继承关系

                        Pattern
                           ↑
                    BadgePattern
             (badge_pattern.h:42)
                           |
        +--------------+--------------+
        |              |              |
  LayoutProperty  LayoutAlgorithm  AccessibilityProperty
        ↑              ↑                    ↑
BadgeLayoutProperty  BadgeLayoutAlgorithm  BadgeAccessibilityProperty

BadgePattern 定义：

// 源码位置：badge_pattern.h:42
class BadgePattern : public Pattern
{
    DECLARE_ACE_TYPE(BadgePattern, Pattern);

public:
    BadgePattern();
    ~BadgePattern() override;

    // 核心方法
    void OnModifyDone() override;
    void OnColorConfigurationUpdate() override;
    void OnDetachFromFrameNode(FrameNode* frameNode) override;

    // 成员变量
    int32_t textNodeId_;  // Text 子节点 ID

private:
    // 更新方法
    void UpdateBadgeValue();
    void UpdateColor();
    void UpdateBadgeColor();
};

---

设计决策分析

1. 为什么 Badge 使用 Text 子节点而不是直接绘制？

设计决策：Badge 内部创建一个 Text 节点作为子节点来显示内容

源码位置：badge_pattern.cpp:30-49

// 创建 Text 子节点
lastFrameNode = FrameNode::GetOrCreateFrameNode(
    V2::TEXT_ETS_TAG, textNodeId_,
    []() { return AceType::MakeRefPtr<TextPattern>(); });
lastFrameNode->MountToParent(frameNode);

设计理由：

优点	说明
复用 Text 能力	自动获得文字测量、渲染、样式支持
主题适配	继承 Text 的主题系统（字体颜色、大小等）
无障碍支持	复用 Text 的 Accessibility 实现
维护成本低	Text 组件的优化自动惠及 Badge

替代方案考虑：

方案	优点	缺点	未选择原因
直接绘制（Rosen Canvas）	性能略好	需自己实现文字测量、渲染、无障碍	维护成本高
使用 Image 节点	灵活	不支持动态内容，需预渲染	不适合动态标记
使用 StaticText 节点	简单	已废弃，API 不稳定	技术债

权衡结论：选择 Text 子节点方案，虽然轻微性能损耗，但大幅降低复杂度和维护成本

---

2. 为什么 Badge 有 BadgePosition 枚举又有 badgePositionX/Y？

设计矛盾：

• BadgePosition 枚举：预设位置（右上角、右侧、左侧）
• badgePositionX/Y：精确坐标偏移

设计理由：

┌─────────────────────────────────────────┐
│  预设位置（快速）    +    精确调整（灵活） │
│                                             │
│  BadgePosition.RightTop  →  基础定位      │
│  badgePositionX: 5vp      →  微调偏移     │
└─────────────────────────────────────────┘

使用场景：

场景	推荐方式	原因
标准通知标记	BadgePosition.RightTop	符合用户习惯
图标上标记	badgePositionX/Y 微调	图标形状不规则
动画效果	badgePositionX/Y 动态修改	需要平滑过渡

源码实现：badge_layout_algorithm.cpp:234-367

// 先应用预设位置
OffsetF baseOffset = CalculateBasePosition(badgePosition);

// 再叠加自定义偏移
if (badgePositionX.has_value()) {
    textOffset.SetX(textOffset.GetX() + badgePositionX->ConvertToPx());
}
if (badgePositionY.has_value()) {
    textOffset.SetY(textOffset.GetY() + badgePositionY->ConvertToPx());
}

---

3. 老年模式阈值为 1.75 的设计考量

源码：badge_layout_algorithm.cpp:88

const double AGE_FONT_SIZE_SCALE = 1.75;

为什么是 1.75？

字体缩放	视觉效果	用户群体
1.0x	正常	普通用户
1.5x	较大	轻度视觉障碍
1.75x	明显较大	老年用户阈值
2.0x+	很大	重度视觉障碍

设计依据：

• 参考 WCAG 2.1 无障碍标准，建议文字最小放大 200%
• OpenHarmony 系统级字体缩放档位：1.0, 1.25, 1.5, 1.75, 2.0
• 1.75x 是"老年模式"的典型入口点

Badge 特殊处理：

if (fontSizeScale >= 1.75) {
    // 使用更大的默认尺寸
    fontSizeInit = badgeTheme->GetBadgeAgeFontSize();    // 16vp (vs 10vp)
    badgeSizeInit = badgeTheme->GetBadgeAgeCircleSize(); // 24vp (vs 16vp)
}

---

4. maxCount 默认值为 99 的原因

源码：badge_theme.h

constexpr int32_t DEFAULT_MAX_COUNT = 99;

设计考量：

因素	分析	结论
显示空间	3位数字（"99+"）在圆形Badge中可读	99 是两位数上限
心理学	"99+" 比 "100+" 更简洁	用户认知负担低
行业惯例	iOS/Android 均使用 99	保持一致性

扩展性设计：

// 应用可自定义
Badge({ count: 150, maxCount: 999 })  // 显示 "999+"

---

实现原理深挖

1. Badge 尺寸计算算法

源码位置：badge_layout_algorithm.cpp:29-154

核心逻辑：

输入：textData（显示文本）、badgeCircleSize（圆形直径）
输出：badgeWidth、badgeHeight

算法流程：
┌─────────────────────────────────────┐
│ 1. 测量文本实际尺寸                  │
│    textSize = Paragraph::Measure()  │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 2. 判断使用圆形还是长条形            │
│                                     │
│    if (textData.size() <= 1) OR    │
│       (count < 10 AND count < max) │
│        → 圆形：宽 = 高 = circleSize │
│    else                             │
│        → 长条：宽 = textWidth + padding │
│           高 = circleSize          │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 3. 应用老年模式缩放                  │
│    if (fontSizeScale >= 1.75)      │
│        → 使用 ageFontSize/CircleSize│
└─────────────────────────────────────┘

关键代码片段：

// 圆形 Badge 尺寸计算
if ((textData.size() <= 1) ||
    (messageCount < 10 && messageCount <= countLimit)) {
    badgeCircleDiameter = std::max(textSize.Height(), badgeCircleDiameter);
    badgeWidth = badgeCircleDiameter;  // 正圆
}
// 长条形 Badge 尺寸计算
else if (textData.size() > 1 || messageCount > countLimit) {
    float padding = badgeTheme->GetNumericalBadgePadding();  // 左右内边距
    badgeWidth = textSize.Width() + padding * 2;
    badgeWidth = std::max(badgeCircleDiameter, badgeWidth);  // 最小宽度为圆形直径
}

边界情况处理：

输入	输出	原因
空字符串	不显示（visible=false）	无内容
"1"	圆形，直径=b badgeCircleSize	单字符
"99+"	长条形，宽度=textWidth+padding	多字符
超长文字（"HOTSALE"）	长条形，宽度=textWidth+padding	动态宽度

---

2. Badge 位置计算与 RTL 支持

源码位置：badge_layout_algorithm.cpp:166-191

坐标系：

LTR（从左到右）          RTL（从右到左）
┌─────────────┐         ┌─────────────┐
│ Parent      │         │      Parent │
│          [B]│         │[B]          │
└─────────────┘         └─────────────┘

Badge 在右上角            Badge 在左上角

计算逻辑：

OffsetF GetTextDataOffset(..., BadgePosition badgePosition, TextDirection layoutDirection) {
    OffsetF textOffset;

    if (badgePosition == BadgePosition::RIGHT_TOP) {
        if (layoutDirection == TextDirection::RTL) {
            // RTL: 右上角变成左上角
            textOffset = OffsetF(offset.GetX(), offset.GetY());
        } else {
            // LTR: 正常右上角
            textOffset = OffsetF(
                offset.GetX() + width - badgeCircleDiameter,
                offset.GetY()
            );
        }
    }
    // ... 其他位置类似处理

    return textOffset;
}

自定义偏移叠加：

// 在预设位置基础上叠加用户偏移
if (badgePositionX.has_value()) {
    textOffset.SetX(textOffset.GetX() + badgePositionX->ConvertToPx());
}
if (badgePositionY.has_value()) {
    textOffset.SetY(textOffset.GetY() + badgePositionY->ConvertToPx());
}

---

3. 主题更新机制

源码位置：badge_pattern.cpp:494-538

问题：系统主题切换时，如何区分用户自定义样式和默认样式？

解决方案：用户设置标志（*Byuser）

// 属性定义中包含标志
class BadgeLayoutProperty : public LayoutProperty {
    ACE_DISALLOW_COPY_AND_MOVE(BadgeLayoutProperty);

    // 属性 + 用户设置标志
    ACE_DEFINE_PROPERTY_Flags(BadgeColor, Color, PROPERTY_UPDATE_MEASURE);
    ACE_DEFINE_PROPERTY_FLAG_ITEM(BadgeColorByuser, bool, PROPERTY_UPDATE_MEASURE);
    // ...
};

更新流程：

系统主题切换
    ↓
OnColorConfigurationUpdate()
    ↓
遍历所有 Badge 属性
    ↓
for each property:
    if (property->Get*Byuser() == false):
        update with theme value  // 仅更新未由用户设置的属性
    else:
        keep user value         // 保留用户自定义值

关键代码：

void BadgePattern::OnColorConfigurationUpdate()
{
    auto badgeTheme = pipeline->GetTheme<BadgeTheme>();

    // 检查用户是否设置了颜色
    if (!layoutProperty->GetBadgeColorByuser().value_or(false)) {
        // 未设置，使用主题值
        UpdateBadgeColor(badgeTheme->GetBadgeColor());
    }
    // 否则，保留用户设置

    if (!layoutProperty->GetBadgeTextColorByuser().value_or(false)) {
        UpdateBadgeTextColor(badgeTheme->GetBadgeTextColor());
    }
    // ...
}

Model 层设置标志：badge_model_ng.cpp

void BadgeModelNG::UpdateBadgeStyle(...) {
    // 用户显式设置颜色时，标记为"由用户设置"
    if (badgeParameters.badgeColor.has_value()) {
        layoutProperty->UpdateBadgeColor(badgeParameters.badgeColor.value());
        layoutProperty->UpdateBadgeColorByuser(true);  // 设置标志
    }
}

---

问题排查手册

问题1：Badge 不显示

症状：设置 Badge 后页面上看不到标记

诊断流程：

开始
  ↓
Badge 是否显示？
  ├─ 否 → 检查 badgeCount
  │        ├─ count <= 0? → 设置 count > 0
  │        └─ count 未设置? → 检查 badgeValue
  │             ├─ value 为空? → 设置非空 value
  │             └─ value 未设置? → 至少设置 count 或 value
  │
  ├─ 显示但位置错误 → 检查 badgePosition/badgePositionX/Y
  │
  └─ 显示但颜色与背景相同 → 检查 badgeColor/badgeTextColor

源码保护：badge_pattern.cpp:57-86

bool badgeVisible = false;

// 只有 count > 0 或 value 非空时才显示
if (badgeCount.has_value() && badgeCount.value() > 0) {
    badgeVisible = true;
} else if (badgeValue.has_value() && !badgeValue.value().empty()) {
    badgeVisible = true;
}

// 设置可见性
textRenderContext->SetVisible(badgeVisible);

调试代码：

@Entry
@Component
struct DebugBadge {
  @State count: number = 0

  build() {
    Column({ space: 10 }) {
      // 调试信息
      Text(`Count: ${this.count}`)
      Text(`Badge Visible: ${this.count > 0}`)

      // Badge
      Badge({ count: this.count }) {
        Text('Message')
      }

      // 控制按钮
      Button('Increase')
        .onClick(() => {
          this.count++
          console.log(`[Badge Debug] count=${this.count}`)
        })
    }
  }
}

---

问题2：Badge 位置不符合预期

常见原因：

原因	现象	解决方案
RTL 布局影响	RIGHT_TOP 显示在左侧	检查 layoutDirection，调整 position 或使用 X/Y 偏移
badgePositionX/Y 冲突	位置偏移异常	清除自定义偏移或重新计算
父容器尺寸不足	Badge 被裁剪	增加父容器尺寸或调整 position

调试代码：

@Entry
@Component
struct BadgePositionDebug {
  build() {
    Column({ space: 20 }) {
      // 测试不同位置
      Badge({ count: 5, position: BadgePosition.RightTop }) {
        Text('右上角')
          .width(100)
          .height(40)
          .backgroundColor('#F0F0F0')
      }

      Badge({ count: 5, position: BadgePosition.Right }) {
        Text('右侧')
          .width(100)
          .height(40)
          .backgroundColor('#F0F0F0')
      }

      Badge({ count: 5, position: BadgePosition.Left }) {
        Text('左侧')
          .width(100)
          .height(40)
          .backgroundColor('#F0F0F0')
      }

      // 自定义位置
      Badge({ count: 5 })
        .badgePositionX(30)
        .badgePositionY(-10) {
        Text('自定义')
          .width(100)
          .height(40)
          .backgroundColor('#F0F0F0')
      }
    }
  }
}

---

问题3：主题更新后 Badge 样式未变化

原因：用户设置了 *Byuser 标志

检查方法：

// C++ 层检查
auto layoutProperty = frameNode->GetLayoutProperty<BadgeLayoutProperty>();
bool isUserColor = layoutProperty->GetBadgeColorByuser().value_or(false);
TAG_LOGD(ACE_BADGE, "BadgeColorByuser: %d", isUserColor);

解决方案：

// 方案1：移除显式颜色设置，使用主题
Badge({ count: 5 }) {
  Text('Message')
}
// 不调用 .badgeColor()

// 方案2：响应主题变化
@State badgeColor: ResourceColor = $r('app.color.badge_color')

Badge({ count: 5 })
  .badgeColor(this.badgeColor) {
  Text('Message')
}

---

问题4：性能问题 - 大量 Badge 导致卡顿

场景：列表中有 100+ 个 Badge

优化策略：

1. 条件渲染：

// 仅在必要时显示 Badge
if (this.messageCount > 0) {
  Badge({ count: this.messageCount }) {
    Text('Message')
  }
} else {
  Text('Message')  // 无 Badge 时直接显示文本
}

2. 使用 LazyForEach：

List() {
  LazyForEach(this.dataSource, (item: Message) => {
    ListItem() {
      Badge({ count: item.count }) {
        Text(item.title)
      }
    }
  })
}

3. 避免频繁更新：

// 使用防抖
debounceUpdate(newCount: number) {
  if (this.updateTimer) {
    clearTimeout(this.updateTimer)
  }
  this.updateTimer = setTimeout(() => {
    this.messageCount = newCount
  }, 100)  // 100ms 内多次更新只触发一次
}

---

跨组件交互

1. Badge 与 Text 的关系

依赖：Badge 包含 Text 节点

Badge FrameNode
├── Text FrameNode (内部创建，用于显示内容)
└── Child FrameNode (用户传入的被标记组件)

数据流向：

ArkTS: Badge({ count: 5 }) { Text("Message") }
           ↓
BadgeModelNG::Create()
           ↓
BadgePattern::OnModifyDone()
           ↓
创建内部 Text 节点
    └── UpdateContent("5")
    └── UpdateTextColor(white)
    └── UpdateFontSize(10vp)

注意事项：

• Badge 内部的 Text 节点 ID 存储在 BadgePattern::textNodeId_
• 更新 Badge 时实际是更新内部 Text 的属性
• 不要直接访问 Badge 内部的 Text 节点（实现细节可能变化）

---

2. Badge 与 List 的组合

最佳实践：

List() {
  ForEach(this.messages, (msg: Message) => {
    ListItem() {
      Row() {
        Text(msg.title)
          .layoutWeight(1)

        // Badge 放在 Row 末尾
        Badge({ count: msg.unreadCount }) {
          Text('')  // 空内容作为占位
            .width(1)
            .height(1)
        }
      }
      .width('100%')
    }
  })
}

性能考虑：

• 使用 LazyForEach 而非 ForEach 处理大量数据
• Badge 的创建开销较小，但频繁更新仍需注意

---

3. Badge 与 Grid 的组合

布局技巧：

Grid() {
  ForEach(this.products, (product: Product) => {
    GridItem() {
      Column() {
        // 商品图片
        Image(product.image)
          .width('100%')
          .aspectRatio(1)

        // Badge 绝对定位在右上角
        Badge({ value: product.tag })
          .position({ x: 0, y: 0 }) {
          Text('')
        }

        // 商品名称
        Text(product.name)
      }
    }
  })
}
.columnsTemplate('1fr 1fr')

---

性能分析

渲染性能

Badge 渲染路径：

Badge FrameNode
    ↓
Text 子节点（内容）
    ↓
RenderContext 绘制
    ↓
Rosen/Skia 渲染

性能数据：

操作	性能影响	优化建议
创建 Badge	低（~1ms）	正常使用
更新 count	低（~0.5ms）	避免高频更新
测量布局	中（~2ms）	使用固定 badgeCircleSize
绘制渲染	低（~1ms）	使用纯色避免渐变

---

内存占用

单个 Badge 内存：

组件	内存占用
Badge FrameNode	~1 KB
内部 Text FrameNode	~0.5 KB
LayoutProperty	~0.2 KB
总计	~1.7 KB

100 个 Badge：~170 KB

优化建议：

• 不需要时条件渲染（if (count > 0)）
• 使用对象池（适用于频繁创建销毁场景）

---

附录

相关文件清单

文件	行数	主要功能
badge_pattern.cpp	~550	Pattern 核心逻辑
badge_layout_algorithm.cpp	~400	布局算法
badge_model_ng.cpp	~200	Model 层
badge_layout_property.h	~200	属性定义
badge_data.h	~80	数据结构

调试命令

# 查看 Badge 组件信息
hidumper -s WindowManagerService -a '-a Badge'

# 查看组件树
hidumper -s WindowManagerService -a '-a ComponentTree'

# 查看 Badge 日志
hilog -T ACE_BADGE

参考文档

• Badge/CLAUDE.md - 快速参考
• Text_Knowledge_Base_CN.md - Text 组件深入（Badge 内部使用 Text）
• badge_theme.h - 主题定义

版本历史

版本	日期	更新内容
v1.0	2026-02-02	初始版本，基于 ace_engine master 分支
v2.0	2026-02-03	深度扩充版，添加设计决策分析、实现原理深挖、问题排查手册