Badge（徽章）

Badge（徽章）

【免费下载链接】HandyControl Contains some simple and commonly used WPF controls 项目地址: https://gitcode.com/gh_mirrors/ha/HandyControl

控件概述

Badge控件用于在UI元素上显示通知标记，支持数字、文本和小红点三种显示模式，常见于消息通知、未读提示等场景。

基本用法

<!-- 数字徽章 -->
<hc:Badge Content="5" 
          BadgePlacement="TopRight">
    <Button Content="通知" Width="80"/>
</hc:Badge>

<!-- 文本徽章 -->
<hc:Badge Content="NEW" 
          Background="#2196F3">
    <hc:Avatar Icon="User" />
</hc:Badge>

<!-- 小红点模式 -->
<hc:Badge IsDot="True">
    <hc:Icon Width="24" Height="24" Kind="Bell"/>
</hc:Badge>

高级特性

动态更新

// ViewModel属性
public int UnreadCount { get; set; } = 3;

// 后台代码更新
UnreadCount = 5;
OnPropertyChanged(nameof(UnreadCount));

<!-- 数据绑定 -->
<hc:Badge Content="{Binding UnreadCount}">
    <Button Content="动态更新" />
</hc:Badge>

注意事项

• 当Content值大于99时，自动显示为"99+"
• BadgePlacement属性支持TopLeft/TopRight/BottomLeft/BottomRight四种位置
• 嵌套元素建议使用尺寸小于48x48的控件，避免布局错乱

相关控件

• Tag：用于标签展示，不支持计数和自动截断
• Notification：用于系统级通知提示，支持交互操作

## 文档质量检查清单

提交PR前请确保完成以下检查：

### 内容完整性
- [ ] 所有代码示例可直接复制运行（无外部依赖）
- [ ] 包含控件所有公共属性的说明（使用表格形式）
- [ ] 提供至少2种实际应用场景示例

### 格式规范性
- [ ] 使用统一的Markdown样式（参照`doc/source/handycontrol/extend_controls/badge.md`）
- [ ] 代码块使用```xml ```而非```html ```标记
- [ ] 关键术语首现标注中英文对照（如`Data Binding（数据绑定）`）

### 技术准确性
- [ ] API版本标注正确（如`Available in v3.5.0+`）
- [ ] 已验证代码示例在最新`dev`分支可正常运行
- [ ] 性能注意事项包含具体测试数据（如`在包含1000+项时启用虚拟化`）

## 特殊控件文档处理

### 复合控件
对于`ChatBubble`、`ComboBox`等包含子元素的复合控件，需额外提供：
- 子元素类型限制说明
- 父子控件交互逻辑
- 完整的视觉层次结构示意图（使用mermaid）

![mermaid](https://web-api.gitcode.com/mermaid/svg/eNqNTzEOwjAM3HmF1RHUgZWx7dIBVUJ8wEmtNtAkKHbEgPg7aZdEiAEPln2-89l6QebO4BTQ7iCFXgFoZ5QmKrUQvDZ4jUPrg6NwwdHERCmaTBmCIScoxjso6kxoQuQZGtT3Kfjoxjzx6kZa0l4nSbbh758n9UK2PKtDoauxBGtiQfvIM-X9Aj0PT3cmZpzoD7_i-epYQV1Dta--_U-bEI3jD4j4X7U)

### 行为型控件
对于`Watermark`、`TransitioningContentControl`等行为型控件，需重点说明：
- 附加属性的使用方式
- 与其他控件的组合效果
- 动画参数调整方法

## 贡献者激励计划

为鼓励高质量文档贡献，项目实施以下激励措施：

1. **文档贡献墙**：每月评选3篇"优质文档"，贡献者头像将展示在README顶部
2. **优先review权**：文档贡献者提交的代码PR将获得24小时内优先审查
3. **项目权限升级**：累计贡献10篇文档可申请成为Collaborator，获得直接合并权限

## 常见问题解答

### Q: 如何处理控件API变更？
A: 当控件API发生破坏性变更时，需：
1. 在对应控件文档顶部添加**警告框**说明变更内容
2. 在`doc/source/handycontrol/breaking_changes/index.md`中记录详细变更日志
3. 提供旧版API迁移至新版的代码示例对比

### Q: 本地预览出现样式错乱怎么办？
A: 执行以下命令强制同步文档主题：
```bash
cd doc
npm run clean
npm run dev

【免费下载链接】HandyControl Contains some simple and commonly used WPF controls 项目地址: https://gitcode.com/gh_mirrors/ha/HandyControl