HarmonyOS NEXT鸿蒙开发ArkUI：通用属性（尺寸、布局、外边距、内边距、对齐、定位、显示、可见性、背景、边框）-马育民老师

# 介绍

在 ArkUI 的声明式开发范式中，**通用属性**（Common Attributes）是指那些可以应用于**绝大多数组件**（如 `Text`, `Button`, `Image`, `Column`, `Row` 等）的基础性属性。它们不决定组件的核心功能，而是用于控制组件的外观、布局、交互等通用行为。

掌握这些通用属性是进行 ArkUI 开发的基础，因为它们贯穿于所有 UI 构建过程中。

---

### 尺寸属性

这类属性控制组件自身的尺寸以及在父容器中的布局行为。

### 布局属性

| 属性 | 类型 | 描述 |
| :--- | :--- | :--- |
| **`.layoutWeight(weight)`** | `number` | （主要用于 `Row`/`Column` 的子组件）设置组件在主轴方向上的**弹性伸缩权重**。类似于 CSS Flexbox 的 `flex-grow`。值越大，可伸展的空间越多。 |

---

### 外边距与内边距 (Margin & Padding)

控制组件周围的空白区域。

| 属性 | 类型 | 描述 |
| :--- | :--- | :--- |
| **`.margin(value)`** | `Length \ Margin` | 设置组件的**外边距**（组件边界到其相邻元素的距离）。`value` 可以是： |
| | | - 单个值：四周边距相同。 |
| | | - 数组 `[top, right, bottom, left]` 或 `[vertical, horizontal]`。 |
| | | - 对象 `{ top?: number, right?: number, bottom?: number, left?: number }`。 |
| **`.padding(value)`** | `Length \ Padding` | 设置组件的**内边距**（组件边界到其内容的距离）。用法与 `.margin()` 完全相同。 |

**示例**：

```ts
Text('Hello')
  .margin({ top: 10, bottom: 10 }) // 上下边距10px
  .padding('16px') // 四周内边距16px
```

---

### 对齐与定位属性

控制组件内部或与其他组件的对齐方式。

| 属性 | 类型 | 描述 |
| :--- | :--- | :--- |
| **`.align(alignment)`** | `Alignment` | 设置组件在其父容器分配的空间内的**对齐方式**。常用值有： |
| | | - `Alignment.TopStart`, `Top`, `TopEnd` |
| | | - `Alignment.CenterStart`, `Center`, `CenterEnd` |
| | | - `Alignment.BottomStart`, `Bottom`, `BottomEnd` |
| **`.alignSelf(alignment)`** | `Alignment` | （仅用于 `Flex`/`Grid` 布局的子组件）覆盖父容器的 `alignItems`，设置**自身在交叉轴上的对齐方式**。 |
| **`.position({ x, y })`** | `{ x?: Length, y?: Length }` | 设置组件相对于其**父容器左上角**的绝对位置。常用于 `Stack` 布局中精确定位。 |
| **`.offset({ x, y })`** | `{ x?: Length, y?: Length }` | 设置组件相对于其**原始位置**的偏移量。正数向右/下，负数向左/上。 |

---

### 显示与可见性属性

控制组件是否显示。

---

### 背景与边框属性

为组件添加背景和边框样式。

| 属性 | 类型 | 描述 |
| :--- | :--- | :--- |
| **`.backgroundColor(color)`** | `ResourceColor` | 设置组件的背景颜色。可以是颜色常量（如 `Color.Blue`）、十六进制字符串（如 `'#FF0000'`）或资源引用。 |
| **`.backgroundImage(src)`** | `ResourceStr` | 设置组件的背景图片。`src` 可以是本地路径（如 `'./images/bg.png'`）或网络 URL。 |
| **`.backgroundImageSize(size)`** | `ImageSize` | 设置背景图片的尺寸。常用值：`'cover'`, `'contain'`, `'auto'`, 或具体尺寸如 `{ width: '100%', height: '100%' }`。 |
| **`.backgroundImagePosition(x, y)`** | `(x?: Length, y?: Length)` | 设置背景图片的位置。 |
| **`.borderWidth(width)`** | `Length \| BorderStyle` | 设置边框宽度。也可以直接传对象设置四边不同宽度。 |
| **`.borderColor(color)`** | `ResourceColor \| BorderColor` | 设置边框颜色。 |
| **`.borderRadius(radius)`** | `Length` | 设置边框圆角半径，实现圆角效果。 |
| **`.border(style)`** | `BorderOptions` | **综合设置边框**，可以一次性设置宽度、颜色、样式（实线、虚线等）。 |

**示例**：

```ts
Column()
  .width('80%')
  .height(200)
  .backgroundColor(Color.Gray)
  .borderRadius(12)
  .border({
    width: 2,
    color: Color.Blue,
    style: BorderStyle.Dashed
  })
```

---

### 交互与手势类属性

虽然更复杂的手势通常通过 `Gesture` API 添加，但一些基础交互也作为通用属性提供。

---

### 其他常用通用属性

---

### 总结

ArkUI 的通用属性体系设计得非常清晰和一致：

*   **链式调用**：所有属性都通过点语法 `.` 追加，形成流畅的链式调用。
*   **类型安全**：在 ArkTS (TypeScript) 环境下，属性的参数类型有良好定义，提供代码提示和错误检查。
*   **组合性强**：你可以自由组合这些通用属性来构建出复杂的 UI 效果。
*   **语义化**：属性名称直观，易于理解。

在实际开发中，你几乎每天都会使用这些通用属性。熟练掌握它们，能让你更快速、更高效地构建出符合设计要求的 HarmonyOS 应用界面。

原文出处：http://www.malaoshi.top/show_1GW25cCWurcQ.html