HarmonyOS6 overlay 叠加层属性使用指南

是稻香啊2026-03-12 12:28

文章目录

一、属性介绍

overlay 是 ArkUI 提供的通用属性，用于在组件上方叠加一段文字，形成浮层效果。常见于图片说明、角标提示、水印等场景。

接口签名：

typescript 复制代码 
overlay(value: string, options?: OverlayOptions): T
参数 类型 必填 说明
value string 是 叠加在组件上方的文字内容
options OverlayOptions 否 叠加层的对齐与偏移配置

二、OverlayOptions 参数说明

typescript 复制代码 
interface OverlayOptions {
  align?: Alignment   // 叠加层相对于组件的对齐位置，默认 Alignment.Center
  offset?: { x: number; y: number }  // 在 align 基础上的额外偏移，单位 vp，默认 {x:0, y:0}
}
字段 类型 默认值 说明
align Alignment Alignment.Center 叠加层的对齐方向，见下方枚举表
offset { x: number; y: number } { x: 0, y: 0 } x 为水平偏移（正值向右），y 为垂直偏移（正值向下）

三、Alignment 枚举值一览

ArkTS 的 Alignment 枚举共 9 个值，对应九宫格的 9 个位置：

枚举值 位置 枚举值 位置
Alignment.TopStart 左上角 Alignment.Top 顶部居中
Alignment.TopEnd 右上角 Alignment.Start 左侧居中
Alignment.Center 正中央（默认） Alignment.End 右侧居中
Alignment.BottomStart 左下角 Alignment.Bottom 底部居中
Alignment.BottomEnd 右下角 --- ---
复制代码 
┌─────────────────────────────────┐
│ TopStart      Top      TopEnd   │
│                                 │
│ Start        Center       End   │
│                                 │
│ BottomStart  Bottom  BottomEnd  │
└─────────────────────────────────┘

四、示例解析

示例一：基础叠加层（固定底部文字）

typescript 复制代码 
Image($r('app.media.bg'))
  .width(240)
  .height(160)
  .overlay('Winter is a beautiful season, especially when it snows.', {
    align: Alignment.Bottom,
    offset: { x: 0, y: -15 }
  })
  • align: Alignment.Bottom：文字锚定在图片底部居中
  • offset: { x: 0, y: -15 }：向上偏移 15vp，避免文字紧贴底边

效果示意：

复制代码 
┌────────────────────┐
│                    │
│      (图片区域)     │
│                    │
│  Winter is a beau- │  ← overlay 文字，底部上移 15vp
└────────────────────┘

示例二：overlay 显示与隐藏控制

typescript 复制代码 
@State showOverlay: boolean = true

Image($r('app.media.bg'))
  .overlay(
    this.showOverlay ? '叠加层已显示（点击按钮切换）' : '',
    { align: Alignment.Center }
  )

Button(this.showOverlay ? '隐藏 overlay' : '显示 overlay')
  .onClick(() => {
    this.showOverlay = !this.showOverlay
  })

要点：

  • overlay 的 value 传入空字符串 '' 即可隐藏叠加层，无需额外 API
  • 用 @State 驱动三元表达式，实现叠加层的动态显隐
  • 这是 ArkTS 响应式编程的典型用法：状态变更 → UI 自动刷新

示例三：九个 align 方向动态切换

typescript 复制代码 
@State currentAlign: Alignment = Alignment.Bottom

// 用具名 class 声明数组元素类型（ArkTS 规范要求）
class AlignOption {
  label: string = ''
  value: Alignment = Alignment.Center
}

private alignOptions: AlignOption[] = [
  { label: 'TopStart',    value: Alignment.TopStart },
  { label: 'Top',         value: Alignment.Top },
  { label: 'TopEnd',      value: Alignment.TopEnd },
  { label: 'Start',       value: Alignment.Start },
  { label: 'Center',      value: Alignment.Center },
  { label: 'End',         value: Alignment.End },
  { label: 'BottomStart', value: Alignment.BottomStart },
  { label: 'Bottom',      value: Alignment.Bottom },
  { label: 'BottomEnd',   value: Alignment.BottomEnd },
]

Image($r('app.media.bg'))
  .overlay('★ overlay 文字', { align: this.currentAlign, offset: { x: 0, y: 0 } })

// 九宫格按钮
Grid() {
  ForEach(this.alignOptions, (item: AlignOption) => {
    GridItem() {
      Button(item.label)
        .backgroundColor(this.currentAlign === item.value ? '#007DFF' : '#E5E5E5')
        .fontColor(this.currentAlign === item.value ? Color.White : Color.Black)
        .onClick(() => { this.currentAlign = item.value })
    }
  })
}
.columnsTemplate('1fr 1fr 1fr')
.width(300)
.height(132)

要点：

  • Grid + columnsTemplate('1fr 1fr 1fr') 实现 3 列九宫格布局
  • ForEach 遍历 AlignOption[] 渲染按钮，item: AlignOption 显式标注类型
  • 当前选中项通过颜色高亮（蓝色背景 + 白色文字）直观反馈
  • this.currentAlign === item.value 比较枚举值来判断是否选中

示例四：offset 偏移量演示

typescript 复制代码 
Image($r('app.media.bg'))
  .overlay('偏移后的 overlay 文字', {
    align: Alignment.BottomStart,
    offset: { x: 30, y: -20 }
  })
  • 先以 Alignment.BottomStart（左下角）为锚点
  • 再向右偏移 30vp、向上偏移 20vp
  • 最终文字落在左下角偏右上的位置

offset 坐标系说明：

x 值 效果 y 值 效果
正值（如 30） 向右偏移 正值（如 20） 向下偏移
负值（如 -30） 向左偏移 负值（如 -20） 向上偏移
0 不偏移 0 不偏移

五、完整源码

typescript 复制代码 
// ArkTS 要求数组字面量元素类型可推断，需提前声明具名类型
class AlignOption {
  label: string = ''
  value: Alignment = Alignment.Center
}

@Entry
@Component
struct OverlayExample {
  @State currentAlign: Alignment = Alignment.Bottom
  @State showOverlay: boolean = true

  // 对齐方式选项
  private alignOptions: AlignOption[] = [
    { label: 'TopStart',    value: Alignment.TopStart },
    { label: 'Top',         value: Alignment.Top },
    { label: 'TopEnd',      value: Alignment.TopEnd },
    { label: 'Start',       value: Alignment.Start },
    { label: 'Center',      value: Alignment.Center },
    { label: 'End',         value: Alignment.End },
    { label: 'BottomStart', value: Alignment.BottomStart },
    { label: 'Bottom',      value: Alignment.Bottom },
    { label: 'BottomEnd',   value: Alignment.BottomEnd },
  ]

  build() {
    Column({ space: 16 }) {

      // ── 示例一：基础用法（固定底部文字叠加层）─────────────────────────
      Text('示例一：基础 overlay 叠加层')
        .fontSize(15)
        .fontWeight(FontWeight.Bold)
        .alignSelf(ItemAlign.Start)
        .margin({ left: 16 })

      Column() {
        // $r('app.media.bg') 需要替换为开发者所需的图像资源文件
        Image($r('app.media.bg'))
          .width(240)
          .height(160)
          .borderRadius(8)
          .overlay('Winter is a beautiful season, especially when it snows.', {
            align: Alignment.Bottom,
            offset: { x: 0, y: -15 }
          })
      }
      .border({ color: Color.Gray, width: 1 })
      .borderRadius(8)

      // ── 示例二：overlay 显示 / 隐藏控制 ────────────────────────────────
      Text('示例二：overlay 显示与隐藏')
        .fontSize(15)
        .fontWeight(FontWeight.Bold)
        .alignSelf(ItemAlign.Start)
        .margin({ left: 16 })

      Column() {
        Image($r('app.media.bg'))
          .width(240)
          .height(160)
          .borderRadius(8)
          .overlay(
            this.showOverlay ? '叠加层已显示（点击按钮切换）' : '',
            { align: Alignment.Center }
          )
      }
      .border({ color: Color.Gray, width: 1 })
      .borderRadius(8)

      Button(this.showOverlay ? '隐藏 overlay' : '显示 overlay')
        .onClick(() => {
          this.showOverlay = !this.showOverlay
        })
        .width(160)

      // ── 示例三：九个对齐方向动态切换 ────────────────────────────────────
      Text('示例三：align 枚举值动态切换')
        .fontSize(15)
        .fontWeight(FontWeight.Bold)
        .alignSelf(ItemAlign.Start)
        .margin({ left: 16 })

      Column() {
        Image($r('app.media.bg'))
          .width(240)
          .height(160)
          .borderRadius(8)
          .overlay('★ overlay 文字', { align: this.currentAlign, offset: { x: 0, y: 0 } })
      }
      .border({ color: Color.Gray, width: 1 })
      .borderRadius(8)

      // 九宫格按钮选择对齐方式
      Grid() {
        ForEach(this.alignOptions, (item: AlignOption) => {
          GridItem() {
            Button(item.label)
              .fontSize(11)
              .width('100%')
              .height(36)
              .backgroundColor(this.currentAlign === item.value ? '#007DFF' : '#E5E5E5')
              .fontColor(this.currentAlign === item.value ? Color.White : Color.Black)
              .onClick(() => {
                this.currentAlign = item.value
              })
          }
        })
      }
      .columnsTemplate('1fr 1fr 1fr')
      .rowsGap(6)
      .columnsGap(6)
      .width(300)
      .height(132)

      // ── 示例四：offset 偏移量演示 ────────────────────────────────────────
      Text('示例四：offset 偏移量（x:30, y:-20）')
        .fontSize(15)
        .fontWeight(FontWeight.Bold)
        .alignSelf(ItemAlign.Start)
        .margin({ left: 16 })

      Column() {
        Image($r('app.media.bg'))
          .width(240)
          .height(160)
          .borderRadius(8)
          .overlay('偏移后的 overlay 文字', {
            align: Alignment.BottomStart,
            offset: { x: 30, y: -20 }
          })
      }
      .border({ color: Color.Gray, width: 1 })
      .borderRadius(8)

    }
    .width('100%')
    .height('100%')
    .padding(16)
    .backgroundColor('#F5F5F5')
  }
}

运行效果如图：

总结

需求 写法
底部文字说明 .overlay('文字', { align: Alignment.Bottom })
动态显隐 value 传 '' 隐藏，传非空字符串显示
向上微调位置 offset: { x: 0, y: -15 }
向右偏移 offset: { x: 30, y: 0 }
左下角文字 align: Alignment.BottomStart
正中央文字 align: Alignment.Center（默认值）

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！

相关推荐
全栈若城3 天前
HarmonyOS6 半年磨一剑 - RcInput 组件清空、密码切换与图标交互机制
架构·交互·harmonyos6·三方库开发实战·rchoui·三方库开发
全栈若城8 天前
HarmonyOS 6 实战：Component3D 与 SURFACE 渲染模式深度解析
3d·架构·harmonyos6
全栈若城8 天前
HarmonyOS 6 实战：使用 ArkGraphics3D 加载 GLB 模型与 Scene 初始化全流程
3d·华为·架构·harmonyos·harmonyos6
是稻香啊16 天前
HarmonyOS6 ArkTS Popup 气泡组件指南
harmonyos6
是稻香啊16 天前
HarmonyOS6 触摸目标 touch-target 属性使用指南
harmonyos6
是稻香啊17 天前
HarmonyOS6 foregroundBlurStyle 通用属性使用指南
harmonyos6
是稻香啊17 天前
HarmonyOS6 clickEffect 通用属性使用指南
harmonyos6
是稻香啊17 天前
HarmonyOS6 filter 通用属性使用指南
harmonyos6
是稻香啊23 天前
HarmonyOS6 ArkUI 无障碍悬停事件（onAccessibilityHover）全面解析与实战演示
华为·harmonyos·harmonyos6
是稻香啊24 天前
HarmonyOS6 背景设置：background 基础属性全解析
harmonyos6
热门推荐
01GitHub 镜像站点02Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）032026年3月AI领域大事件：DeepSeek引领开源风暴04VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）05【技术干货】Gemma 4 上手深度指南：本地多模态大模型的新基线06AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南07Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services08OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程09Mac 本地部署 OMLX + 通义千问 Qwen3.5-27B 保姆级教程10纯 HTML/CSS/JS 实现的高颜值登录页，还会眨眼睛！少女心爆棚！