HarmonyOS应用开发实战：猫猫大作战-`Button` 组件从默认胶囊到圆角矩形、从平面到浮起的完整套路

HarmonyOS应用开发实战：猫猫大作战-`Button` 组件从默认胶囊到圆角矩形、从平面到浮起的完整套路

发布时间：2026/9/4 23:07:07
HarmonyOS应用开发实战：猫猫大作战-`Button` 组件从默认胶囊到圆角矩形、从平面到浮起的完整套路 前言主菜单的视觉焦点除了标题就是那个醒目的「开始游戏」按钮。在 HarmonyOS 里Button看似简单——一行代码就能跑起来——但要做出「圆润饱满 微微浮起 点击有反馈」的精致体验背后涉及ButtonType枚举、borderRadius像素值、shadow阴影结构、stateEffect状态效果四个知识点。本篇以「猫猫大作战」主菜单的开始按钮为锚点把Button组件从默认胶囊到圆角矩形、从平面到浮起的完整套路讲透。读完本篇你将能独立写出主操作按钮、次要操作按钮、危险操作按钮三种视觉语义的 Button。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1、2 篇。一、场景拆解开始按钮的视觉规格打开entry/src/main/ets/pages/Index.ets的MainMenuView找到开始按钮// 来源entry/src/main/ets/pages/Index.ets MainMenuView() Button(开始游戏) .width(70%) .height(56) .fontSize(20) .fontWeight(FontWeight.Bold) .fontColor(#FFFFFF) .backgroundColor(#2ECC71) .borderRadius(28) .shadow({ radius: 8, color: rgba(46, 204, 113, 0.4), offsetY: 4 }) .onClick(() { this.startGame(); })这个按钮的视觉规格拆解维度取值作用宽度70%占父容器 7 成居中显眼但不顶满高度56vp比默认 40 高主操作按钮要够大字号20比正文大比标题小字重Bold加粗强调字色#FFFFFF白配深绿底对比强底色#2ECC71绿「开始」用绿色通行语义圆角28高度 56 的一半 → 完美胶囊阴影radius:8, offsetY:4向下浮起 4vp阴影色rgba(46,204,113,0.4)与底色同色相不脏关键经验圆角取高度的一半即得胶囊形阴影色与底色同色相 透明度 0.3–0.5浮起感干净不脏。二、Button 创建的两种方式参考 按钮 (Button) 官方指南Button有两种调用形式2.1 字符串 label纯文本按钮Button(label?: ResourceStr, options?: { type?: ButtonType, stateEffect?: boolean })Button(开始游戏, { type: ButtonType.Normal, stateEffect: true }) .borderRadius(28) .backgroundColor(#2ECC71) .width(70%) .height(56)本项目用的就是这种最简洁。2.2 子组件形式图文混排按钮Button(options?: { type?: ButtonType, stateEffect?: boolean }) { // 只支持一个子组件 }Button({ type: ButtonType.Normal, stateEffect: true }) { Row() { Image($r(app.media.play_icon)).width(20).height(20).margin({ left: 12 }) Text(开始游戏).fontSize(20).fontColor(Color.White).margin({ left: 5, right: 12 }) }.alignItems(VerticalAlign.Center) } .backgroundColor(#2ECC71) .borderRadius(28) .width(70%) .height(56)提示子组件形式只支持包含一个子组件。要在按钮里放图 文必须用一个Row或Column把它们包起来再塞进去不能直接ImageText平铺。三、ButtonType 四种类型枚举类型圆角默认是否支持borderRadius改圆角适用场景Capsule胶囊默认高度的一半不支持圆角主按钮Circle圆形完全圆不支持图标按钮、FABNormal普通0支持方角按钮Rounded_Rectangle圆角矩形0支持自定义圆角矩形3.1 胶囊按钮默认Button(Disable, { type: ButtonType.Capsule, stateEffect: false }) .backgroundColor(#317AFF) .width(90) .height(40)圆角自动设为高度的一半40/220改borderRadius无效。适合「登录」「提交」这类主操作。3.2 圆形按钮Button(Circle, { type: ButtonType.Circle, stateEffect: false }) .backgroundColor(#317AFF) .width(90) .height(90)宽高必须相等才是正圆。适合 FAB悬浮动作按钮、图标按钮。3.3 普通按钮方角Button(Ok, { type: ButtonType.Normal, stateEffect: true }) .borderRadius(8) .backgroundColor(#317AFF) .width(90) .height(40)默认圆角 0必须显式设borderRadius才有圆角。本项目开始按钮走的就是这种 borderRadius(28)比Capsule更灵活——能在高度变化时保持圆角值不变。3.4 圆角矩形按钮Button(Rounded, { type: ButtonType.ROUNDED_RECTANGLE, stateEffect: true }) .borderRadius(8) .backgroundColor(#317AFF) .width(90) .height(40)与Normal类似但圆角渲染机制更优API 12 推荐用ROUNDED_RECTANGLE替代Normal。提示本项目用NormalborderRadius(28)是兼容老写法。新项目直接用ROUNDED_RECTANGLE视觉更干净。四、borderRadius 圆角实战borderRadius接受 number 或 string单位 vp。关键经验值高度圆角推荐效果4020胶囊5628胶囊本项目开始按钮4422胶囊本项目暂停按钮4824胶囊本项目弹窗按钮408小圆角矩形400方角圆角 高度 / 2是胶囊形的铁律。如果你想小圆角矩形取高度的 10–30%Button(小圆角, { type: ButtonType.Normal }) .height(40) .borderRadius(8) // 高度的 20%五、shadow 阴影结构与浮起感shadow接受一个对象核心字段字段类型作用本项目取值radiusnumber阴影模糊半径越大越散8colorstring | Color阴影颜色rgba(46,204,113,0.4)offsetXnumber水平偏移0默认offsetYnumber垂直偏移正值向下45.1 浮起按钮的阴影套路.shadow({ radius: 8, color: rgba(46, 204, 113, 0.4), offsetY: 4 })三个要点offsetY: 4向下偏移模拟光从上方打下来的投影。radius: 8模糊半径让阴影不硬边更真实。color与底色同色相底色#2ECC71绿阴影也用绿 0.4 透明度视觉干净。5.2 错误示范黑色阴影配绿底// ❌ 脏 .shadow({ radius: 8, color: rgba(0, 0, 0, 0.3), offsetY: 4 })黑色阴影配亮色底会有「脏灰」感不如同色相透明度阴影来得清爽。六、stateEffect 点击反馈stateEffect是 Button 独有的属性默认true点击时按钮会有一层半透明遮罩反馈。Button(开始游戏, { stateEffect: true }) // 默认值可省略 Button(已禁用, { stateEffect: false }) // 禁用反馈禁用按钮的正确写法是stateEffect: false 灰底Button(已禁用, { stateEffect: false }) .backgroundColor(#BDC3C7) .fontColor(#FFFFFF) .width(70%) .height(56)提示不要用enabled: false替代stateEffect: false——前者会彻底禁用点击事件后者只是视觉反馈。如果你要的是「视觉上像禁用但还能点」比如弹提示「请先登录」用stateEffect: false。七、三种视觉语义的 Button 完整代码7.1 主操作按钮绿色开始/提交Button(开始游戏) .width(70%) .height(56) .fontSize(20) .fontWeight(FontWeight.Bold) .fontColor(#FFFFFF) .backgroundColor(#2ECC71) .borderRadius(28) .shadow({ radius: 8, color: rgba(46, 204, 113, 0.4), offsetY: 4 }) .onClick(() { this.startGame(); })7.2 次要操作按钮灰色暂停/取消Button(暂停) .width(100) .height(44) .fontSize(15) .fontColor(#FFFFFF) .backgroundColor(#95A5A6) .borderRadius(22) .onClick(() { this.pauseGame(); })次要按钮省略fontWeight和shadow字号 15 比主按钮 20 小不浮起。7.3 危险操作按钮红色删除/重新开始Button(重新开始) .width(100) .height(44) .fontSize(15) .fontColor(#FFFFFF) .backgroundColor(#E74C3C) .borderRadius(22) .onClick(() { this.clearTimers(); this.startGame(); })危险按钮用红底#E74C3C圆角高度一半22不加阴影保持低视觉权重——危险操作不该诱导用户点。八、onClick 点击事件绑定Button(开始游戏) .onClick(() { this.startGame(); })关键点必须用箭头函数() { ... }否则this不指向组件。本系列第 38 篇会专讲箭头函数this绑定。onClick返回void不能async异步操作在内部async () { await ... }。事件穿透Button默认不穿透点击事件叠在上面的透明层不会响应。九、调试技巧按钮怎么量尺寸临时加 border.border({ width: 1, color: Color.Red })看清按钮占框。width用百分比响应式但父容器宽度要先确定。本项目主菜单Column是 100% 屏宽按钮 70% 即 7 成屏宽。height固定 vp按钮高度别用百分比弹层和键盘弹起会让百分比高度乱跳。预览器看圆角DevEco 预览器圆角渲染接近真机可放心调。十、性能与最佳实践backgroundColor用资源$r(app.color.primary)比硬编码#2ECC71更易维护暗色模式切换也靠它。本系列第 28 篇专讲。避免width: 100%的主按钮顶满宽度没有「按钮」的视觉边界留点空隙更易点。shadow.radius别太大超过 16 会让阴影糊成一团8–12 是甜区。stateEffect: false替代enabled: false前者保留点击事件适合「禁用但弹提示」场景。总结本篇我们从开始按钮切入掌握Button的ButtonType四枚举、borderRadius圆角铁律、shadow阴影结构、stateEffect点击反馈四大要点并给出了主操作、次要、危险三种视觉语义的完整代码。核心要点圆角取高度一半得胶囊阴影同色相 offsetY 浮起绿/灰/红三色对应主/次/危。下一篇我们将继续主菜单拆解游戏规则面板的Column卡片容器把padding、backgroundColor、borderRadius、alignItems四个容器属性讲透。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源「猫猫大作战」项目源码本仓库entry/src/main/ets/pages/Index.ets按钮 (Button) 官方指南Button API 参考ButtonOptions 对象说明开源鸿蒙跨平台社区HarmonyOS 开发者官方文档首页ArkUI 组件参考系列索引本仓库articles/INDEX.md