介绍

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

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

尺寸属性

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

属性	类型	描述
`.width(value)`	`Length`	设置组件的宽度。`value` 可以是具体的数值（如 `200`）、带单位的字符串（如 `'200px'`）、百分比（如 `'50%'`）或弹性份数（如 `'1fr'`）。
`.height(value)`	`Length`	设置组件的高度。用法同 `.width()`。
`.size(width, height)`	`(width: Length, height?: Length)`	同时设置组件的宽度和高度。如果只传一个参数，则宽高相等。
`.minWidth(value)`	`Length`	设置组件的最小宽度。当内容或布局约束导致宽度小于该值时，组件不会更窄。
`.maxWidth(value)`	`Length`	设置组件的最大宽度。限制组件不会超过此宽度。
`.minHeight(value)`	`Length`	设置组件的最小高度。
`.maxHeight(value)`	`Length`	设置组件的最大高度。

布局属性

属性	类型	描述
`.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()` 完全相同。

示例：

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 }`	设置组件相对于其原始位置的偏移量。正数向右/下，负数向左/上。

显示与可见性属性

控制组件是否显示。

属性	类型	描述
`.visibility(state)`	`'Visible' \ 'Hidden' \ 'None'`	控制组件的可见性：
		- `'Visible'`: 正常显示。
		- `'Hidden'`: 隐藏，但仍占据布局空间。
		- `'None'`: 隐藏，且不占据布局空间（相当于从布局树中移除）。
`.opacity(value)`	`number`	设置组件的透明度。`value` 范围 `0.0` (完全透明) 到 `1.0` (完全不透明)。

背景与边框属性

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

属性	类型	描述
`.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`	综合设置边框，可以一次性设置宽度、颜色、样式（实线、虚线等）。

示例：

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

交互与手势类属性

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

属性	类型	描述
`.onClick(event)`	`(event: ClickEvent) => void`	点击事件回调。这是最常用的交互属性。
`.enabled(enabled)`	`boolean`	设置组件是否启用。禁用状态通常表现为灰色且无交互响应。
`.focusable(focusable)`	`boolean`	设置组件是否可获得焦点。
`.tabIndex(index)`	`number`	设置组件在 Tab 键导航中的顺序。

其他常用通用属性

属性	类型	描述
`.id(id)`	`string`	为组件设置唯一标识符。虽然在声明式 UI 中不常用于查找，但在某些场景（如动画、特定逻辑）下有用。
`.key(key)`	`string \ number`	在列表 (`List`) 或条件渲染中，帮助框架高效地识别和更新组件。对于动态列表，强烈建议为每个项目设置唯一的 `key`。
`.aspectRatio(ratio)`	`number`	设置组件的宽高比。例如 `.aspectRatio(1)` 创建一个正方形，`.aspectRatio(16 / 9)` 创建一个 16:9 的矩形。组件会根据可用空间按此比例调整尺寸。

总结

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

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

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

原文出处：/show_1GW25cCWurcQ.html