HarmonyOS 6 Badge 组件自定义外描边和文本延伸方向使用示例文档
文章目录
- 组件功能概述
- 核心 API 与参数
- 1. Badge 组件扩展配置（外描边 + 文本避让）
- 2. 关键工具类/枚举
- 代码分段解析
- 1. 状态变量定义
- 2. Badge 核心配置（外描边 + 文本避让）
- 3. 交互按钮（切换文本避让状态）
- 4. 整体布局
- 效果展示
- 总结
组件功能概述
本示例基于 HarmonyOS ArkTS 实现了 Badge 标记组件的两大核心自定义能力：
- 为 Badge 标记添加自定义样式的外描边（边框颜色、宽度）；
- 控制 Badge 文本超出标记尺寸时的自动避让（延伸）行为。
通过交互按钮可切换文本避让开关状态，直观展示不同配置下的视觉效果，适用于需要个性化标记样式、适配长文本展示的场景（如多位数数字标记、自定义风格角标等）。
核心 API 与参数
1. Badge 组件扩展配置（外描边 + 文本避让）
| 参数/样式属性 | 类型 | 说明 |
|---|---|---|
outerBorderColor | Color | 外描边颜色，示例中设置为粉色（Color.Pink） |
outerBorderWidth | Length | 外描边宽度，示例中通过LengthMetrics.vp(5)设为 5vp |
enableAutoAvoidance | boolean | 是否开启文本自动避让： - false：文本超出 Badge 尺寸时被截断/挤压；- true：文本超出时自动向外侧延伸展示 |
badgeSize | number | Badge 标记基础尺寸（宽高），示例中设为 30vp |
fontSize | number | Badge 内部文本字号，示例中设为 20vp |
position | BadgePosition | Badge 相对于子组件的位置，示例中为RightTop（右上） |
direction | Direction | 文本延伸方向，示例中为Ltr（从左到右） |
2. 关键工具类/枚举
LengthMetrics.vp()：将数值转换为 vp 单位（鸿蒙自适应尺寸单位），保证多设备适配；BadgePosition.RightTop：Badge 显示在子组件的右上角；Direction.Ltr：文本延伸方向为从左到右（默认）；Color.Pink：鸿蒙内置颜色常量，也可自定义十六进制颜色（如#FFC0CB）。
代码分段解析
1. 状态变量定义
@State badgeValue: string = '1234'; // Badge 显示的文本内容（长文本用于测试延伸效果） @State textAvoid:boolean[] = [false, true]; // 文本避让开关状态列表 @State textAvoidIndex: number = 0; // 切换状态的索引 @State textAvoidString: string [] = ["false", "true"]; // 状态对应的文本展示值说明：
badgeValue: '1234'选择4位数字，超出 Badge 基础尺寸（30vp），可直观体现文本避让效果；textAvoid数组存储两种开关状态，通过textAvoidIndex切换，实现交互演示。
2. Badge 核心配置（外描边 + 文本避让）
Badge({ value: this.badgeValue, style: { badgeSize : 30, // 标记基础尺寸30vp fontSize:20, // 文本字号20vp（接近标记尺寸，易触发超出场景） outerBorderColor : Color.Pink, // 外描边颜色：粉色 outerBorderWidth : LengthMetrics.vp(5), // 外描边宽度：5vp enableAutoAvoidance : this.textAvoid[this.textAvoidIndex] // 文本避让开关（动态切换） }, position:BadgePosition.RightTop // 标记显示在子组件右上角 }) { // 子组件：示例图片（需替换为开发者自有资源） Image($r("app.media.startIcon")) .width(80) .height(80) } .direction(Direction.Ltr) // 文本延伸方向：从左到右 .margin({ top: 20, bottom: 20 })核心配置说明：
- 外描边样式：
outerBorderColor + outerBorderWidth组合实现粉色粗描边，让 Badge 标记更醒目，适配个性化UI设计； - 文本避让：
enableAutoAvoidance绑定动态状态，false时“1234”文本会因超出 30vp 标记尺寸被挤压/截断，true时文本自动向右延伸展示完整内容； - 位置与方向：
RightTop保证标记在图片右上角，Direction.Ltr定义文本延伸方向为从左到右。
3. 交互按钮（切换文本避让状态）
Button("enableAutoAvoidance ： " + this.textAvoidString[this.textAvoidIndex]) .onClick(() => { // 点击切换索引，循环切换 false/true 状态 this.textAvoidIndex = (this.textAvoidIndex + 1) % this.textAvoidString.length; })说明：
- 按钮文本实时显示当前
enableAutoAvoidance状态； - 点击事件通过取模运算实现
textAvoidIndex在 0/1 之间循环，从而切换文本避让开关。
4. 整体布局
build() { Column() { // Badge 组件区域 ... // 交互按钮区域 ... } .width('100%') .height('80%') .alignItems(HorizontalAlign.Center) // 水平居中 .justifyContent(FlexAlign.Center) // 垂直居中 }说明：整体采用 Column 纵向布局，将 Badge 和按钮居中展示，保证视觉聚焦，便于查看状态切换效果。
效果展示
enableAutoAvoidance状态 | 效果描述 |
|---|---|
false（默认） | Badge 标记为 30vp 粉色描边（5vp）方块，“1234”文本因字号 20vp 超出尺寸，被挤压在标记内（部分字符可能截断）； |
true | Badge 标记基础尺寸不变，“1234”文本自动向右延伸，完整展示所有字符，描边跟随文本延伸区域适配； |
效果运行如图：
点击按钮变为true：
总结
- 资源替换：示例中
$r("app.media.startIcon")需替换为开发者项目内的图片资源（如本地 svg/png 格式），否则会导致图片加载失败； - 尺寸适配：
badgeSize和fontSize需合理搭配，建议文本字号不超过标记尺寸的 70%，避免未开启避让时文本过度挤压； - 描边宽度：
outerBorderWidth不宜设置过大（如超过 10vp），否则会覆盖 Badge 内部文本，影响可读性； - 延伸方向：
direction(Direction.Ltr)仅控制文本延伸方向，需结合position（如 RightTop/RightBottom）选择，避免延伸方向与父组件重叠； - 状态切换：
textAvoidIndex取模运算（% this.textAvoidString.length）保证索引不越界，是循环切换状态的通用写法。
如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力