企业官网建设流程全解析

• 文档
• 知识库
• 教程
• OpenHarmony

本篇技术指南围绕 OpenHarmony 仓颉（Cangjie）ArkUI-CJ 框架中的通用属性overlay（浮层）展开，完整讲解该属性的函数签名、三个命名参数（value、align、offset）的语义与默认值，并深入剖析其背后的Alignment枚举与OverlayOffset类的定义，结合仓库内真实示例演示如何在Text、Image等任意组件上快速添加文字浮层并精确控制其位置。读完本篇，你将掌握组件浮层文本的完整配置方法，能够独立实现"默认居中浮层、角落浮层、偏移浮层"三类典型效果，并理解align与offset同时生效时的叠加定位规则。

一、overlay 属性概述：什么是组件浮层

在 ArkUI-CJ（方舟 UI 框架的仓颉语言 API）中，overlay是挂载在所有组件之上的通用属性之一，其作用是为当前组件增加一段"遮罩文本"作为该组件的浮层（Overlay）。所谓"浮层"，即悬浮绘制在组件内容之上的附加文本层，它不参与组件原有的布局计算，而是直接叠加显示在组件区域中，常用于：

• 为图片组件标注格式或名称（如"png"、"gif"、"Contain"等）；
• 为色块组件添加说明文字；
• 为列表项、卡片等容器追加角标式提示文本。

从属性体系的位置来看，overlay属于 ArkUI-CJ 通用属性列表中"浮层"一项，与尺寸设置、位置设置、背景设置、透明度设置、Z序控制等并列，适用于Text、Image、Column、Row、Stack、List 等全部组件，见 通用属性总览 与 ArkUI-CJ 组件索引。

与bindPopup（Popup 弹窗）这类需要动态控制显隐的浮层不同，overlay是静态的文本遮罩：只要设置了value参数，浮层文本就会随组件一起渲染；它不拦截交互、不需要额外的显隐状态管理，是最轻量的一种组件标注手段。

二、API 签名与返回值

overlay属性的完整声明如下：

public func overlay(value!: ?String, align!: ?Alignment = None, offset!: ?OverlayOffset = None): T

调用前需要导入 ArkUI 模块：

import kit.ArkUI.*

功能：在当前组件上，增加遮罩文本作为该组件的浮层。

系统能力：SystemCapability.ArkUI.ArkUI.Full

起始版本：22

返回值：

从返回值T可以看出，overlay遵循 ArkUI-CJ 通用属性的链式编程范式：.overlay(...)之后仍可继续调用.zIndex(...)、.onClick(...)等属性或事件方法，这与通用属性列表中其他条目（如 背景设置、显隐控制）的用法保持一致。

三、三个命名参数详解

overlay共接收三个命名参数，其中仅value为必填，align与offset均可省略并各自拥有默认值：

3.1 value：遮罩文本内容

value是唯一的必填参数，类型为可空字符串?String。它的取值直接决定浮层上显示的文字内容，例如：

.overlay(value: "Overlay Text") // 浮层显示 Overlay Text .overlay(value: "png") // 浮层显示 png

3.2 align：浮层相对组件的方位

align参数的类型是Alignment枚举，用于指定浮层相对于组件的方位。该枚举定义于 cj-common-types.md，其完整声明为：

public enum Alignment <: Equatable<Alignment> { | TopStart | Top | TopEnd | Start | Center | End | BottomStart | Bottom | BottomEnd | ... }

Alignment共提供 9 个公开的方位取值，语义如下：

此外，Alignment还约束了Equatable<Alignment>父类型并重载了operator func ==(other: Alignment): Bool，用于判断两个对齐方式是否相等（具体实现见 cj-common-types.md）。overlay中align的默认值为None，实际生效的初始对齐方式是Alignment.Center，即不显式指定时浮层文本默认水平、垂直居中显示在组件上。

3.3 offset：基于浮层左上角的偏移

offset参数的类型是OverlayOffset类，用于为浮层指定额外的平移量。其定义同样位于 cj-common-types.md：

public class OverlayOffset { public var x: ?Float64 public var y: ?Float64 public init(x!: ?Float64 = None, y!: ?Float64 = None) }

该类包含两个可读写的属性：

构造方式为命名参数OverlayOffset(x: ..., y: ...)，两者均可省略，默认值均为None。overlay中offset的默认值是OverlayOffset(x: 0.0, y: 0.0)，且需要特别注意：偏移基准是浮层自身的左上角，而不是组件的左上角；文档同时说明"浮层默认处于组件左上角"，因此未设置align、offset时的实际渲染位置为组件左上角。

需要提醒的是，由于OverlayOffset使用Float64描述坐标，偏移量支持小数与负值。负偏移可将浮层拉出组件边缘之外（如示例 1 中OverlayOffset(x: -20.0, y: -20.0)将浮层向左上方向移动）。

四、align 与 offset 的叠加定位规则

overlay参数说明中给出了一条重要规则：

说明：align和offset都设置时，效果重叠，浮层相对于组件方位定位后，再基于当前位置的左上角进行偏移。

这条规则可以拆解为两步定位流程：

1. 第一步（align 生效）：浮层先按照align指定的方位对齐到组件上的对应位置。例如align: Alignment.BottomEnd时，浮层先对齐到组件的右下角区域；
2. 第二步（offset 生效）：在第一步确定的位置基础上，以浮层自身当前的左上角为基准，沿 x 轴（水平）、y 轴（纵向）分别平移offset指定的距离。

因此，当同时指定align: Alignment.BottomEnd与offset: OverlayOffset(x: -20.0, y: -20.0)时，浮层会先贴到组件右下角，再向左上方平移 20 个长度单位，从而形成"内缩于右下角"的角标效果。理解了这一叠加规则，就可以组合出任意位置的浮层。

五、完整示例：三种浮层效果

关联文档给出了一段可运行的完整示例，演示了浮层的三种典型配置：默认居中、左上角对齐、右下角对齐并偏移。以下代码完整保留并标注了关键点：

package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* @Entry @Component class EntryView { func build() { Column() { // 场景一：只传 value，align、offset 使用默认值 // 默认对齐方式为 Alignment.Center，浮层文本水平垂直居中 Text("默认居中浮层") .width(200) .height(100) .backgroundColor(0xf48899) .align(Alignment.Top) .overlay(value: "Overlay Text") // 场景二：指定 align 为 Alignment.TopStart // 浮层对齐到组件左上角，无额外偏移 Text("左上角浮层") .width(200) .height(100) .backgroundColor(0xf7b0bb) .overlay(value: "Top Left", align: Alignment.TopStart) // 场景三：同时设置 align 与 offset // 先对齐到右下角（BottomEnd），再以浮层左上角为基准向左上偏移 20 Text("带偏移的浮层") .width(200) .height(100) .backgroundColor(0xfbd7dd) .overlay( value: "Offset Text", align: Alignment.BottomEnd, offset: OverlayOffset(x: -20.0, y: -20.0) ) } .width(100.percent) .height(100.percent) .justifyContent(FlexAlign.Center) .alignItems(HorizontalAlign.Center) } }

运行该示例后的预期效果为：

• 场景一（默认居中浮层）：粉红色矩形（0xf48899）中央显示 "Overlay Text"，由于未传align与offset，文本水平垂直居中；
• 场景二（左上角浮层）：浅粉色矩形（0xf7b0bb）左上角显示 "Top Left"，对应Alignment.TopStart；
• 场景三（带偏移的浮层）：更浅的粉色矩形（0xfbd7dd）中，文本先对齐到右下角，再向左上方偏移 20，形成距右下角 20 单位的 "Offset Text" 角标。

三个浮层分别演示了value单独使用、value + align、value + align + offset三种参数组合，覆盖了最常见的浮层配置形态。

六、仓库中的更多实战用法

除了 API 文档中的演示示例，overlay在仓库其他模块中也有大量真实使用，可作为扩展参考：

6.1 为图片组件标注格式

在 图片组件 Image 文档 中，开发者通过overlay为不同格式的图片标注类型名，例如：

Image(@r(app.media.startIcon)) .width(110) .height(110) .margin(15) .overlay(value: "png", align: Alignment.Bottom, offset: OverlayOffset(x: 0.0, y: 20.0))

这段代码为 png 图片在底部居中位置添加 "png" 标签，并向下偏移 20 个单位（OverlayOffset(x: 0.0, y: 20.0)），使其略微探出图片底边，视觉效果类似图片下方的图注。同一示例中 gif、svg、jpg 等格式均采用相同的align: Alignment.Bottom+ 下偏移 20 的写法，可用于对齐多张图片的标注文字。

6.2 为图像渲染效果添加说明

在 图形绘制与图像显示文档 中，overlay被大量用于标注不同的渲染模式，例如：

.overlay(value: 'Contain', align: Alignment.Bottom, offset: OverlayOffset(x: 0.0, y: 20.0)) .overlay(value: 'Cover', align: Alignment.Bottom, offset: OverlayOffset(x: 0.0, y: 20.0)) .overlay(value: 'ImageRepeat.XY', align: Alignment.Bottom, offset: OverlayOffset(x: 0.0, y: 20.0))

这印证了一个结论：overlay是通用属性，凡是组件均可调用——上述用法正是把"标注文本"作为调试与演示手段，将渲染模式名称直接浮在预览效果图上的常见做法，也可以沿用到你自己的开发调试中。

七、注意事项与边界

使用overlay时需要留意以下几点（均有仓库文档依据）：

1. 内容类型限制：overlay的value参数类型为?String，即只能承载文本内容，无法直接放入自定义组件或复杂布局。若需要将任意内容作为浮层展示，应改用 全屏模态转场 bindContentCover（可绑定CustomBuilder自定义内容）或 Popup 控制 bindPopup（可配置弹窗内容与交互逻辑）。
2. 与其他通用属性共用：overlay属于通用属性，可与尺寸、背景、透明度、Z序等属性自由链式组合；其返回值是组件实例本身，不会破坏调用链。
3. 可能与边缘渐隐相互覆盖：仓库中 滚动组件通用能力文档 明确指出，滚动组件的fadingEdge（边缘渐隐）选项生效时会覆盖原组件的.overlay()属性。因此在使用 Scroll、List 等可滚动容器时，若同时开启fadingEdge与overlay，浮层可能不显示，需要结合具体场景取舍。
4. 版本与系统能力：overlay的起始版本为 22，系统能力要求为SystemCapability.ArkUI.ArkUI.Full，即仅在全量 ArkUI 能力环境下可用，开发时需确保目标设备的系统版本与能力满足要求。

八、小结

overlay是 ArkUI-CJ 中实现"组件文字浮层"最直接、最轻量的通用属性：仅需一个必填的value参数即可为任意组件叠加遮罩文本；通过align可在 9 个方位间选择浮层对齐位置；通过offset可基于浮层自身左上角做二次平移；当align与offset同时设置时，先定位后偏移的叠加规则让浮层位置可以精确落到组件的任意区域。结合仓库中 Image 标注、渲染模式标注等真实案例，overlay既可服务于正式 UI 的角标与图注，也可用于开发调试阶段的视觉效果标注，是仓颉应用开发中值得熟练掌握的通用属性之一。

• 文档
• 知识库
• 教程
• OpenHarmony