鸿蒙原生 ArkTS 布局之美（一）：ZOrder 图层管理与 zIndex 深度解析

---

一、引言

在移动端应用开发中，UI 布局不仅仅是组件的排列组合，更涉及组件之间的空间层次关系。当多个组件在屏幕上重叠时，谁在前、谁在后、谁遮挡谁——这背后的控制机制，就是我们今天要深入探讨的 ZOrder（图层顺序）管理。

鸿蒙操作系统从诞生之初就将「原生流畅」作为核心设计目标之一，其声明式 UI 框架 ArkTS 提供了完整的图层管理能力。其中，zIndex 属性是最基础、最常用的图层控制手段。本文将以一个完整的示例应用为线索，从原理到实战，全面解析鸿蒙 ArkTS 中的 ZOrder 图层管理机制，并结合 API 24（HarmonyOS NEXT 5.x）的最新特性，帮助开发者真正掌握组件叠放顺序的控制艺术。

---

二、从设计到代码：理解 ZOrder 与 zIndex

2.1 什么是 ZOrder？

在计算机图形学中，屏幕可以理解为一个二维坐标系：X 轴（水平方向）和 Y 轴（垂直方向）。但除此之外，还存在一个隐形的第三维度——Z 轴（垂直于屏幕的方向）。ZOrder 指的就是组件在 Z 轴上的排列顺序，它决定了当多个组件在 X-Y 平面上重叠时，哪一个组件被渲染在最前面（即遮挡其他组件）。

这个概念在几乎所有主流 UI 框架中都有对应实现：

平台 / 框架	对应 API	说明
HarmonyOS ArkTS	.zIndex(value)	值为整数，越大越靠上
CSS（Web）	z-index	值为整数，需配合 position 使用
Android	elevation / translationZ	基于阴影高度，API 21+
iOS UIKit	layer.zPosition	Core Animation 层的 z 位置
Flutter	Stack + index	通过 children 顺序控制

鸿蒙 ArkTS 的 zIndex 在设计理念上更接近 CSS 的 z-index——通过一个显式的数值来声明组件的图层优先级，简洁、直观、且易于动态调节。

2.2 zIndex 的核心规则

在深入研究代码之前，我们先明确 zIndex 的三条核心规则：

1. 数值越大，图层越靠上：zIndex: 10 的组件会覆盖 zIndex: 5 的组件。
2. 默认值为 0：所有未显式设置 zIndex 的组件，其图层层级均为 0。
3. 相同 zIndex 时，后书写的组件在上：如果两个组件 zIndex 相同，则在 build() 方法中书写顺序靠后的组件会被渲染在更上层。

此外，zIndex 支持负值。设置 zIndex: -1 可以将组件置于默认图层之下，这在实现「背景装饰层」或「占位元素」时非常有用。

2.3 与 CSS z-index 的关键区别

不少 Web 开发者初次接触鸿蒙 zIndex 时会觉得似曾相识，但二者有一个重要的区别需要特别注意：

在 CSS 中，z-index 的有效性依赖于元素的 position 属性（必须是 relative、absolute、fixed 或 sticky 之一），否则 z-index 不会生效。而在鸿蒙 ArkTS 中，zIndex 对所有组件均生效，无需额外设置定位上下文。即使一个组件使用默认的布局方式（如 Column 内的子组件），zIndex 依然可以控制其相对于兄弟组件的图层顺序。这一设计降低了开发者的心智负担，使得图层管理更加「声明式」和「可预测」。

---

三、示例应用架构解析

在深入技术细节之前，我们先概览一下示例应用的整体架构。应用包含两个页面：

• 首页（Index.ets）：导航入口，通过卡片形式引导用户进入各个布局示例。
• 演示页（ZOrderDemo.ets）：核心演示页面，包含三个可交互的色块，通过 zIndex 控制叠放顺序。

3.1 首页设计

首页使用简洁的卡片式布局，卡片内包含三个重叠的小方块作为视觉隐喻，暗示该页面与图层管理相关。点击「查看示例」按钮，通过 router.pushUrl() 跳转到演示页。

3.2 演示页核心设计

演示页的核心是一个 Stack 容器，内部放置三个颜色不同的色块（红、绿、蓝），每个色块通过 position() 属性在 Stack 内部进行偏移定位，从而产生部分重叠的效果。每个色块下方有一组控制按钮（+ / -），用于实时调整该色块的 zIndex 值，调整结果通过色块上的文字和遮挡关系的变化直观呈现。

---

四、关键技术点详解

4.1 @State 驱动 zIndex 动态变化

在鸿蒙 ArkTS 中，UI 的更新依赖于状态变量。我们使用 @State 装饰器声明三个状态变量，分别对应三个色块的 zIndex 值：

@State block1ZIndex: number = 0;
@State block2ZIndex: number = 1;
@State block3ZIndex: number = 2;

当用户点击 + 或 - 按钮时，状态变量的值发生变化，触发组件重新渲染，新的 zIndex 值被应用到对应的色块上，从而实现图层顺序的动态调整。这一过程完全由框架自动完成，开发者只需关注状态的定义和变更逻辑，无需手动操作 DOM 或视图树。

4.2 Stack + position 实现组件重叠

为了实现「多个组件在同一区域内重叠」的效果，我们选择 Stack 作为容器组件。Stack 的特点是：所有子组件在 Z 轴上从栈底到栈顶依次堆叠，子组件之间可以通过 position() 方法进行绝对定位。

Stack() {
  // 色块1：位置 (20, 20)
  Column() { /* ... */ }
    .position({ x: 20, y: 20 })
    .zIndex(this.block1ZIndex)

  // 色块2：位置 (100, 80)
  Column() { /* ... */ }
    .position({ x: 100, y: 80 })
    .zIndex(this.block2ZIndex)

  // 色块3：位置 (180, 140)
  Column() { /* ... */ }
    .position({ x: 180, y: 140 })
    .zIndex(this.block3ZIndex)
}

三个色块的坐标经过精心设计，确保它们之间产生部分重叠——这样当 zIndex 改变时，遮挡关系的变化才能被清晰观察。

4.3 @Builder 实现代码复用

在控制区域，三个色块的操作行具有完全相同的布局结构（色标圆点 + 名称 + 空白填充 + 减号按钮 + 数值显示 + 加号按钮）。我们使用 @Builder 装饰器将这一重复的 UI 结构抽象为可复用的构建函数：

@Builder
controlRow(label: string, color: string, zIndex: number, onChange: (val: number) => void) {
  Row() {
    Circle().width(14).height(14).fill(color)
    Text(label).margin({ left: 8 })
    Blank()
    Button('-').onClick(() => { if (zIndex > -5) onChange(zIndex - 1) })
    Text(`${zIndex}`)
    Button('+').onClick(() => { if (zIndex < 5) onChange(zIndex + 1) })
  }
}

@Builder 是鸿蒙 ArkTS 声明式 UI 中实现代码复用的核心机制之一。与传统的函数式抽象不同，@Builder 内部可以完整地使用链式 API 和状态绑定，同时保持了 UI 代码的可读性。

4.4 动态阴影增强视觉层次感

为了让图层的前后关系更加明显，我们为每个色块添加了阴影效果：

.shadow({ radius: 6, color: 'rgba(0,0,0,0.25)' })

阴影的视觉暗示与人类的深度感知机制天然契合——位于上层的物体会在位于下层的物体表面投下阴影。在示例中，当色块 A 的 zIndex 大于色块 B 时，色块 A 会在色块 B 上投下淡淡的阴影，增强了图层关系在视觉上的可信度。

---

五、zIndex 的高级用法与最佳实践

5.1 负值 zIndex 的应用场景

将 zIndex 设为负值可以将组件置于默认图层之下。常见的应用场景包括：

• 背景装饰层：实现水印、纹理背景、装饰性图形等不干扰主内容交互的元素。
• 占位占位符：在数据加载完成前显示骨架屏的底层结构。
• 底部导航栏的阴影/背景：将无法交互的装饰元素置于内容层之下。

// 背景装饰层示例
Text('Watermark')
  .zIndex(-1)
  .position({ x: 0, y: 0 })
  .width('100%')
  .height('100%')
  .opacity(0.1)

5.2 zIndex 与动画结合

zIndex 支持与动画系统配合使用，实现平滑的图层过渡效果。例如，在卡片翻转、弹窗展开、拖拽排序等场景中，可以结合 animateTo 或属性动画来实现 zIndex 的渐变过渡：

animateTo({ duration: 300, curve: Curve.EaseInOut }, () => {
  this.block1ZIndex = 5;
});

需要注意的是，zIndex 本身不支持插值动画（从 0 到 5 的中间值没有实际意义），但在 animateTo 的回调中设置 zIndex 可以实现「在动画过程中切换图层」的效果——适合在动画关键帧处改变图层归属。

5.3 zIndex 与交互事件穿透

当多个组件重叠时，一个常见的需求是：上层组件虽然视觉上遮挡了下层组件，但希望点击事件能够「穿透」上层组件，由下层组件响应。此时可以结合 .hitTestBehavior() 来控制事件命中测试的行为：

Column()
  .zIndex(2)
  .hitTestBehavior(HitTestMode.None)  // 自身不响应事件，也不拦截事件传递

结合 zIndex 与 hitTestBehavior，可以实现更加精细的交互控制——例如弹窗遮罩层（上）+ 底层内容（下）的场景中，遮罩层视觉上覆盖内容层，但遮罩层自身的空白区域允许点击事件穿透到底层。

5.4 图层爆炸：避免 zIndex 值滥用

在实际项目中，随着页面复杂度的提升，zIndex 值可能会变得难以管理。一个常见的反模式是随意使用大数值（如 zIndex: 9999）来「确保」组件在最上层。这种做法会导致：

1. 数值膨胀：新来的开发者为了覆盖已有的组件，不得不使用更大的值。
2. 可维护性下降：无法从 zIndex 的值推断出组件的层级关系。
3. 调试困难：当图层出现异常时，难以定位原因。

推荐做法：定义图层层级常量，统一管理所有 zIndex 值。

// layer-levels.ets
export const LayerLevels = {
  BACKGROUND: -10,
  DEFAULT: 0,
  CONTENT: 10,
  STICKY_HEADER: 100,
  MODAL_BACKDROP: 500,
  MODAL_CONTENT: 501,
  TOAST: 1000,
  POPOVER: 2000,
} as const;

使用时直接引用常量，既清晰又可控：

Column()
  .zIndex(LayerLevels.MODAL_CONTENT)

5.5 Stack 的嵌套与 zIndex 作用域

需要注意的是，zIndex 的作用域是相对于同一个父容器内的兄弟组件。如果两个组件位于不同的 Stack 中，那么它们的 zIndex 不会直接相互影响。每个 Stack 构成了一个独立的图层上下文。

这个问题在 CSS 中被称为「层叠上下文（stacking context）」——当一个元素的 zIndex 被设置后，它只在其所在的层叠上下文中有效，而无法跨越上下文与其他元素比较 z 轴位置。鸿蒙 ArkTS 的 Stack 容器也遵循类似的规则：

// 错误的理解：认为红色块一定在绿色块之上
Stack() {
  Text('红色块').zIndex(10)
}
Stack() {
  Text('绿色块').zIndex(1)  // 在两个不同的 Stack 中，zIndex 不直接比较
}

在这个例子中，红色块和绿色块位于不同的 Stack 容器中，它们各自的 zIndex 只在各自的 Stack 内生效。最终的渲染顺序取决于两个 Stack 在整个布局树中的位置关系（后渲染的 Stack 整体在前）。因此，跨容器的图层管理需要从更上层的布局结构入手，而不是单纯依赖 zIndex。

---

六、从示例到实战：典型应用场景

6.1 悬浮按钮（FAB）

悬浮操作按钮（Floating Action Button）是移动应用中常见的 UI 模式。它需要始终悬浮在内容之上，不随页面滚动而移动：

Stack() {
  // 主内容区域
  Scroll() { /* 长内容列表 */ }

  // 悬浮按钮
  Button()
    .position({ bottom: 24, right: 24 })
    .zIndex(100)
    .onClick(() => { /* 操作 */ })
}

6.2 拖拽排序

在拖拽排序场景中，被拖拽的卡片需要临时提升其图层层级，以在移动过程中始终悬浮在其他卡片之上：

@State dragIndex: number = -1;

Column() {
  ForEach(this.items, (item, index) => {
    CardComponent({ item })
      .zIndex(this.dragIndex === index ? 100 : 0)
      .onDragStart(() => { this.dragIndex = index; })
      .onDragEnd(() => { this.dragIndex = -1; })
  })
}

6.3 遮罩弹窗

弹窗通常由遮罩层和内容层组成，二者具有明确的层级关系：

Stack() {
  // 底层内容
  MainContent()

  // 遮罩层
  Column()
    .width('100%').height('100%')
    .backgroundColor('rgba(0,0,0,0.5)')
    .zIndex(500)
    .onClick(() => { this.showModal = false; })

  // 弹窗内容
  Column() { /* 弹窗 UI */ }
    .zIndex(501)
    .borderRadius(16)
    .backgroundColor(Color.White)
}

遮罩层的 zIndex 为 500，弹窗内容层的 zIndex 为 501，确保弹窗内容在遮罩层之上。这样的数值设计（而不是使用 0 和 1）为将来在弹窗之上再叠加其他元素（如 Toast 提示）预留了空间。

6.4 页面转场动画

在页面转场过程中，新页面从右侧滑入时可能需要位于旧内容之上，但转场完成后又需要恢复正常层级。通过动态调整 zIndex 可以实现这一效果：

// 入场动画
animateTo({ duration: 300 }, () => {
  this.newPageOffset = 0;     // 位置归零
  this.newPageZIndex = 10;    // 临时提升层级
});

// 出场动画
animateTo({ duration: 300 }, () => {
  this.newPageOffset = '100%';
  this.newPageZIndex = 0;     // 恢复层级
});

---

七、性能考量与注意事项

7.1 图层合成与性能

在鸿蒙的渲染管线中，每个 zIndex 值不同的组件可能会被分配到不同的渲染图层中。过多的独立图层会增加渲染合成的开销。因此，在保证功能正确的前提下，应尽量控制图层数量，避免为大量组件分别设置不同的 zIndex。

7.2 避免频繁变更

频繁修改 zIndex 会触发组件的重新布局和重新渲染。在动画循环或高频交互（如拖拽）中，应合理控制 zIndex 的更新频率，避免不必要的性能损耗。

7.3 与 elevation 的区别

在 API 24 中，除了 zIndex，还可以使用 elevation 属性来实现阴影效果和图层提升。二者的区别在于：

• zIndex：仅控制图层顺序，不产生视觉阴影效果。
• elevation：同时控制图层顺序和阴影大小，值越大阴影越明显。

如果只需要调整图层顺序而不需要阴影，应优先使用 zIndex；如果需要视觉上的「高度感」，可以结合使用二者。

---

八、总结与展望

本文围绕鸿蒙 ArkTS 中的 zIndex 属性，从基本原理到实战技巧，从一个完整的示例应用出发，深入剖析了 ZOrder 图层管理的方方面面。我们看到了 zIndex 如何与 @State 状态管理、@Builder 代码复用、Stack 容器等机制协同工作，也探讨了图层层级管理的设计原则和最佳实践。

在鸿蒙 NEXT（API 24）的时代，ArkTS 的声明式 UI 框架正在日益成熟。zIndex 作为图层管理的基石，虽然 API 本身简单直观，但其背后涉及的渲染原理、交互策略、性能考量却值得每一位开发者深思。掌握好图层的管理能力，不仅是写出正确 UI 的基础，更是构建流畅、优雅、高体验度应用的关键一步。

在后续的「鸿蒙原生 ArkTS 布局之美」系列文章中，我们将继续探讨更多布局话题，包括 Flex 弹性布局、Grid 网格布局、RelativeContainer 相对布局、以及自定义组件的布局测量等。敬请期待。

---

附录：完整示例代码

ZOrderDemo.ets（完整版）

import { router } from '@kit.ArkUI';

@Entry
@Component
struct ZOrderDemo {
  @State block1ZIndex: number = 0;
  @State block2ZIndex: number = 1;
  @State block3ZIndex: number = 2;

  build() {
    Column() {
      Text('ZOrder 图层管理 — zIndex 控制叠放顺序')
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .fontColor('#FF333333')
        .margin({ top: 16, bottom: 8 })

      Stack() {
        // 色块1：红色（默认 zIndex = 0）
        Column() {
          Text('色块 A').fontSize(16).fontColor(Color.White).fontWeight(FontWeight.Bold)
          Text(`zIndex: ${this.block1ZIndex}`).fontSize(14).fontColor(Color.White).margin({ top: 4 })
        }
        .width(200).height(140)
        .backgroundColor('#FFE53B3B')
        .borderRadius(12)
        .justifyContent(FlexAlign.Center)
        .alignItems(HorizontalAlign.Center)
        .position({ x: 20, y: 20 })
        .zIndex(this.block1ZIndex)
        .shadow({ radius: 6, color: 'rgba(0,0,0,0.25)' })

        // 色块2：绿色（默认 zIndex = 1）
        Column() {
          Text('色块 B').fontSize(16).fontColor(Color.White).fontWeight(FontWeight.Bold)
          Text(`zIndex: ${this.block2ZIndex}`).fontSize(14).fontColor(Color.White).margin({ top: 4 })
        }
        .width(200).height(140)
        .backgroundColor('#FF3BA55D')
        .borderRadius(12)
        .justifyContent(FlexAlign.Center)
        .alignItems(HorizontalAlign.Center)
        .position({ x: 100, y: 80 })
        .zIndex(this.block2ZIndex)
        .shadow({ radius: 6, color: 'rgba(0,0,0,0.25)' })

        // 色块3：蓝色（默认 zIndex = 2）
        Column() {
          Text('色块 C').fontSize(16).fontColor(Color.White).fontWeight(FontWeight.Bold)
          Text(`zIndex: ${this.block3ZIndex}`).fontSize(14).fontColor(Color.White).margin({ top: 4 })
        }
        .width(200).height(140)
        .backgroundColor('#FF3B7AE5')
        .borderRadius(12)
        .justifyContent(FlexAlign.Center)
        .alignItems(HorizontalAlign.Center)
        .position({ x: 180, y: 140 })
        .zIndex(this.block3ZIndex)
        .shadow({ radius: 6, color: 'rgba(0,0,0,0.25)' })
      }
      .width(400).height(320)
      .backgroundColor('#FFF5F5F5')
      .borderRadius(16)
      .border({ width: 1, color: '#FFE0E0E0' })
      .margin({ top: 12, bottom: 20 })

      Text('说明：三个色块在 Stack 内通过 position 重叠放置，').fontSize(13).fontColor('#FF666666')
      Text('每个色块独立设置 zIndex，值越大越靠上。').fontSize(13).fontColor('#FF666666').margin({ bottom: 16 })

      // 控制行
      this.controlRow('色块 A（红）', '#FFE53B3B', this.block1ZIndex, (v) => { this.block1ZIndex = v; })
      this.controlRow('色块 B（绿）', '#FF3BA55D', this.block2ZIndex, (v) => { this.block2ZIndex = v; })
      this.controlRow('色块 C（蓝）', '#FF3B7AE5', this.block3ZIndex, (v) => { this.block3ZIndex = v; })

      Button('重置所有 zIndex（0 / 1 / 2）')
        .fontSize(14).fontColor(Color.White)
        .backgroundColor('#FF333333')
        .borderRadius(20).height(40).width(240)
        .margin({ top: 16 })
        .onClick(() => {
          this.block1ZIndex = 0;
          this.block2ZIndex = 1;
          this.block3ZIndex = 2;
        })
    }
    .width('100%').height('100%')
    .padding({ left: 12, right: 12 })
    .alignItems(HorizontalAlign.Center)
    .backgroundColor('#FFFFFFFF')
  }

  @Builder
  controlRow(label: string, color: string, zIndex: number, onChange: (val: number) => void) {
    Row() {
      Circle().width(14).height(14).fill(color)
      Text(label).fontSize(14).fontWeight(FontWeight.Medium).fontColor('#FF333333').margin({ left: 8 })
      Blank()
      Button('-')
        .fontSize(16).fontWeight(FontWeight.Bold).fontColor('#FF333333')
        .backgroundColor('#FFE8E8E8').borderRadius(8).width(36).height(36)
        .onClick(() => { if (zIndex > -5) onChange(zIndex - 1) })
      Text(`${zIndex}`)
        .fontSize(18).fontWeight(FontWeight.Bold).fontColor('#FF007AFF')
        .width(40).textAlign(TextAlign.Center)
      Button('+')
        .fontSize(16).fontWeight(FontWeight.Bold).fontColor('#FF333333')
        .backgroundColor('#FFE8E8E8').borderRadius(8).width(36).height(36)
        .onClick(() => { if (zIndex < 5) onChange(zIndex + 1) })
    }
    .width('100%').height(44)
    .padding({ left: 12, right: 12 })
    .backgroundColor('#FFF8F8F8').borderRadius(8).margin({ top: 6 })
  }
}

项目配置文件

entry/src/main/resources/base/profile/main_pages.json：

{
  "src": [
    "pages/Index",
    "pages/ZOrderDemo"
  ]
}