HarmonyOS 「事件 + 属性」

DevEco Studio「事件 + 属性」16 词全解

3 分钟看懂 OnClick、OnScroll、Size、Background… 到底干什么、怎么用、代码长什么样。

---

一、Events（事件）——让组件“活”起来

事件名	触发时机	典型用法	一行代码示例
OnClick	手指/鼠标单击抬起	按钮、列表项点击	.onClick(() => router.pushUrl('pages/Detail'))
OnTouch	按下 → 移动 → 抬起全过程	自定义手势、画布绘图	.onTouch((e: TouchEvent) => console.log(e.type))
OnAppear	组件首次进入屏幕	埋点曝光、动画入场	.onAppear(() => report('show'))
OnDisappear	组件完全离开屏幕	埋点消失、资源回收	.onDisappear(() => this.clear())
OnKeyEvent	物理/软键盘按键	TV/车机方向键、回车	.onKeyEvent((e) => if(e.key === KeyCode.ENTER) login())
OnAreaChange	尺寸或位置变化	动态调整弹窗位置	.onAreaChange((old, new) => this.adjust(new))
OnScroll	滚动过程中持续回调	实时吸顶、懒加载	.onScroll((x, y) => this.offsetY = y)
OnScrollEdge	滚动到边缘	上拉/下拉刷新提示	.onScrollEdge((edge) => if(edge === Edge.Top) refresh())
OnScrollEnd	滚动完全停止	停止惯性后埋点	.onScrollEnd(() => savePosition())
OnScrollBegin	滚动即将开始	拦截滚动、嵌套冲突	.onScrollBegin(() => this.allow ? ScrollDirection.Vertical : ScrollDirection.None)

小抄：在 可视化面板 点事件右侧闪电图标 → 自动生成函数骨架，零手写。

---

二、Properties（属性）——让组件“长”什么样

分组	作用	高频字段	一行代码示例
scroll	滚动容器专属	scrollBar、scrollDirection	.scrollBar(BarState.Auto).scrollDirection(Axis.Vertical)
Size	宽高 & 极限值	width、height、minWidth、maxHeight	.width('100%').height(200)
Spacing	外边距 & 内边距	margin、padding	.margin({ top: 8, left: 16 })
Background	背景色 / 图 / 渐变	backgroundColor、backgroundImage	.backgroundColor('#fff').backgroundImage($r('app.media.bg'))
Border	描边 & 圆角	borderWidth、borderColor、borderRadius	.border({ width: 1, color: '#e5e5e5' }).borderRadius(8)
Layout	容器布局规则	justifyContent、alignItems、columns、zIndex	.justifyContent(FlexAlign.Center).columns(2)
Effect	动效 & 滤镜	opacity、shadow、clip	.opacity(0.5).shadow({ radius: 6, color: '#33000000' })
Render	可见性与层级	visibility、zIndex	.visibility(Visibility.Hidden).zIndex(10)

---

事件 = 交互时机，属性 = 视觉样式。
把这 16 个关键词背下来，90% 的 UI 需求都能在可视化面板里点出来，剩下的 10% 再补手写代码即可。

觉得有用，点赞 + 收藏；评论区分享你的隐藏技巧！