ArkUI(鸿蒙)中组件的通用属性

最新推荐文章于 2025-12-15 14:43:46 发布

原创最新推荐文章于 2025-12-15 14:43:46 发布 · 1.3k 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #华为 #鸿蒙

鸿蒙专栏收录该内容

383 篇文章

订阅专栏

本文同步发表于我的微信公众号，微信搜索程语新视界即可关注，每个工作日都有文章更新

一、尺寸与布局属性

1. 尺寸设置（单位：vp）

属性	类型	默认值	说明	示例
width	Length	-	组件宽度	`.width(100).width('50%')`
height	Length	-	组件高度	`.height('100%')`
size	{ width: Length, height: Length }	-	同时设置宽高	`.size({ width: 100, height: 100 })`
minWidth	Length	0	最小宽度	`.minWidth(80)`
maxHeight	Length	Infinity	最大高度	`.maxHeight(200)`

2. 边距与间距（单位：vp）

属性	类型	说明	示例
margin	Margin \| Length	外边距	`.margin(10).margin({ top: 5, bottom: 5 })`
padding	Padding \| Length	内边距	`.padding(15)`
space	Length	子组件间距	`.space(8)`

二、样式属性

1. 背景与边框

属性	类型	说明	示例
backgroundColor	ResourceColor	背景颜色	`.backgroundColor('#FF0000').backgroundColor($r('app.color.red'))`
backgroundImage	string \| PixelMap \| Resource	背景图片	`.backgroundImage('common/bg.png')`
border	{ width?: Length, color?: ResourceColor, radius?: Length }	边框样式	`.border({ width: 2, color: '#000' })`
borderRadius	Length \| { topLeft?: Length, topRight?: Length, bottomLeft?: Length, bottomRight?: Length}	圆角半径	`.borderRadius(10).borderRadius({ topLeft: 8 })`

2. 透明度与可见性

属性	类型	说明	示例
opacity	number	透明度(0-1)	`.opacity(0.5)`
visibility	Visibility	可见性	`.visibility(Visibility.None)`

三、文本样式属性

1. 字体相关

属性	类型	说明	示例
fontColor	ResourceColor	文字颜色	`.fontColor('#333')`
fontSize	Length	字体大小	`.fontSize(16)`
fontStyle	FontStyle	字体样式	`.fontStyle(FontStyle.Italic)`
fontWeight	number \| FontWeight	字体粗细	`.fontWeight(FontWeight.Bold)`
fontFamily	string	字体家族	`.fontFamily('HarmonyOS Sans')`

2. 文本布局

属性	类型	说明	示例
textAlign	TextAlign	文本对齐	`.textAlign(TextAlign.Center)`
lineHeight	Length	行高	`.lineHeight(24)`
textOverflow	{ overflow: TextOverflow }	文本溢出	`.textOverflow({ overflow: TextOverflow.Ellipsis })`
maxLines	number	最大行数	`.maxLines(2)`

四、布局控制属性

1. Flex布局

属性	类型	说明	示例
flexGrow	number	扩展比例	`.flexGrow(1)`
flexShrink	number	收缩比例	`.flexShrink(0)`
flexBasis	Length	基准尺寸	`.flexBasis('40%')`
alignSelf	ItemAlign	自身对齐	`.alignSelf(ItemAlign.Center)`

2. 定位属性

属性	类型	说明	示例
position	Position	定位类型	`.position(Position.Absolute)`
markAnchor	{ x: Length, y: Length }	锚点	`.markAnchor({ x: 0.5, y: 0.5 })`
offset	{ x: Length, y: Length }	偏移量	`.offset({ x: 10, y: -5 })`

五、交互属性

1. 事件响应

属性	类型	说明	示例
onClick	(event: ClickEvent) => void	点击事件	`.onClick(() => {})`
onTouch	(event: TouchEvent) => void	触摸事件	`.onTouch((e) => {})`
onKeyEvent	(event: KeyEvent) => void	按键事件	`.onKeyEvent((e) => {})`

2. 状态效果

属性	类型	说明	示例
stateEffect	boolean \| StateEffect	状态效果	`.stateEffect(true)`
hoverEffect	HoverEffect	悬停效果	`.hoverEffect(HoverEffect.Scale)`
pressedEffect	PressedEffect	按压效果	`.pressedEffect(PressedEffect.Scale)`

六、变换属性

属性	类型	说明	示例
scale	{ x: number, y: number, z?: number }	缩放	`.scale({ x: 1.2, y: 1.2 })`
rotate	{ x?: number, y?: number, z?: number, angle: Angle }	旋转	`.rotate({ z: 1, angle: 30 })`
translate	{ x?: Length, y?: Length, z?: Length }	平移	`.translate({ x: 10 })`
transform	Matrix4Transit	变换矩阵	`.transform({ matrix: [1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1] })`

七、阴影与滤镜

属性	类型	说明	示例
shadow	{ radius: Length, color?: ResourceColor, offsetX?: Length, offsetY?: Length}	阴影效果	`.shadow({ radius: 8, color: '#888' })`
backdropBlur	number	背景模糊	`.backdropBlur(5)`
blur	number	模糊效果	`.blur(3)`

八、栅格与约束

属性	类型	说明	示例
gridSpan	number	栅格跨度	`.gridSpan(2)`
gridOffset	number	栅格偏移	`.gridOffset(1)`
constraintSize	{ minWidth?: Length, maxWidth?: Length, minHeight?: Length, maxHeight?: Length}	约束尺寸	`.constraintSize({ minWidth: 100 })`

九、使用示例

@Entry
@Component
struct UniversalPropertiesExample {
  @State isActive: boolean = false;

  build() {
    Column() {
      Text('通用属性演示')
        .width('80%')
        .height(60)
        .margin(10)
        .padding(15)
        .backgroundColor('#F5F5F5')
        .borderRadius(8)
        .fontSize(20)
        .fontColor('#333')
        .onClick(() => {
          this.isActive = !this.isActive;
        })
        .stateEffect(this.isActive)//启用状态动画
        .scale(this.isActive ? { x: 1.05, y: 1.05 } : { x: 1, y: 1 })
        .animation({ duration: 300, curve: Curve.EaseOut })

      if (this.isActive) {
        Text('扩展内容')
          .width('70%')
          .height(100)
          .margin({ top: 20 })
          .transition({ type: TransitionType.Insert, opacity: 0 })
      }
    }
    .width('100%')
    .height('100%')
  }
}