鸿蒙PC UI控件库 - IconButton 图标按钮详解-平芜编程栈

视频演示地址：

https://www.bilibili.com/video/BV1jomdBBE4H/

📋 目录

概述
特性
快速开始
API 参考
使用示例
主题配置
最佳实践
常见问题
总结

概述

IconButton是控件库中的图标按钮组件，仅显示图标，无文字，适用于工具栏、操作按钮等场景。与文字按钮的主要区别在于：

PrimaryButton/SecondaryButton/TextButton：显示文字（可带图标）
IconButton：仅显示图标，无文字

设计理念

图标按钮采用极简设计，具有以下特点：

纯图标设计：仅显示图标，节省空间
形状灵活：支持圆形和方形两种形状
尺寸多样：支持 small、medium、large 三种尺寸（large 尺寸为 80vp × 80vp，图标 40vp）
品牌标识：左下角自动包含品牌标识（圆圈红字"PC"）
主题统一：所有样式配置都在代码中，方便定制
通用字符：使用 ASCII 字符作为图标，确保在所有系统上都能正确显示

图标字符映射

为了确保图标在所有系统上都能正确显示，推荐使用以下 ASCII 字符：

字符	含义	用途
`S`	Settings（设置）	设置、配置相关操作
`U`	User（用户）	用户、账户相关操作
`R`	Refresh（刷新）	刷新、重新加载
`D`	Delete（删除）	删除操作
`E`	Edit（编辑）	编辑、修改操作
`+`	Add（添加）	添加、新建操作
`√`	Check（确认）	确认、成功操作
`×`	Close（关闭）	关闭、取消操作
`...`	More（更多）	更多选项
`B`	Bold（粗体）	文本格式化
`I`	Italic（斜体）	文本格式化
`<=>`	对齐	左对齐、居中、右对齐

特性

✨ 核心特性

✅纯图标设计：仅显示图标，无文字
✅多种形状：支持圆形（circle）和方形（square）
✅多种尺寸：支持 small、medium、large 三种尺寸（large 尺寸为 80vp × 80vp，图标 40vp）
✅加载状态：内置加载动画
✅禁用状态：支持禁用状态，自动调整样式
✅自定义颜色：支持自定义图标颜色和背景颜色
✅品牌标识：自动包含左下角品牌标识
✅主题配置：所有样式都可通过代码配置

🎨 视觉特点

圆形按钮：完全圆形，适合工具栏和操作按钮
方形按钮：圆角方形，适合列表操作和卡片操作
正常状态：图标颜色为主题主色，背景透明
悬停状态：背景色变化（通过系统自动处理）
禁用状态：图标变灰 + 50% 透明度

快速开始

基础用法

import{IconButton}from'../components/base'@Entry @Component struct MyPage{build(){Column({space:20}){// 基础圆形图标按钮（使用文字图标）IconButton({textIcon:'S'// S = Settings（设置）})// 方形图标按钮IconButton({textIcon:'...',// ... = More（更多）shape:'square'})// 不同尺寸Row({space:12}){IconButton({textIcon:'+',buttonSize:'small'})IconButton({textIcon:'+',buttonSize:'medium'})IconButton({textIcon:'+',buttonSize:'large'})}}.width('100%').height('100%').padding(20).justifyContent(FlexAlign.Center)}}

关于点击事件处理

IconButton的onClickBuilder属性是@BuilderParam类型，需要使用@Builder或@LocalBuilder方法初始化。在实际项目中，推荐使用以下方式处理点击事件：

状态管理方式：通过@State变量和普通Button的onClick来处理
自定义事件系统：创建自定义事件处理机制
@Builder 方法：如果需要使用onClickBuilder，需要定义@Builder方法

本文档中的示例主要展示按钮的视觉效果和样式配置，点击事件处理可以通过上述方式实现。

API 参考

Props

属性名	类型	默认值	说明
`icon`	`ResourceStr?`	`undefined`	按钮图标（可选，图片资源）
`textIcon`	`string?`	`undefined`	文字图标（可选，ASCII字符或Unicode字符，优先级高于 icon。推荐使用：S=设置, U=用户, R=刷新, D=删除, E=编辑, +=添加, √=确认, ×=关闭）
`shape`	`'circle' \| 'square'`	`'circle'`	按钮形状
`buttonSize`	`'small' \| 'medium' \| 'large'`	`'medium'`	按钮尺寸
`loading`	`boolean`	`false`	是否加载中
`disabled`	`boolean`	`false`	是否禁用
`showBrand`	`boolean`	`true`	是否显示品牌标识
`iconColor`	`string?`	`undefined`	图标颜色（可选，默认使用主题色）
`buttonBackgroundColor`	`string?`	`undefined`	背景颜色（可选，默认透明）
`onClickBuilder`	`@BuilderParam () => void?`	`undefined`	点击事件回调（需要使用 @Builder 或 @LocalBuilder 方法）

尺寸规格

尺寸	按钮大小	图标大小	圆角（圆形）	圆角（方形）
`small`	32vp × 32vp	16vp	16vp	4vp
`medium`	40vp × 40vp	20vp	20vp	8vp
`large`	80vp × 80vp	40vp	40vp	12vp

使用示例

1. 基础按钮

@Entry @Component struct ButtonExample1{build(){Column({space:15}){// 圆形图标按钮（使用文字图标）IconButton({textIcon:'S'// S = Settings（设置）})// 方形图标按钮IconButton({textIcon:'...',// ... = More（更多）shape:'square'})// 带背景的图标按钮IconButton({textIcon:'+',// + = Add（添加）buttonBackgroundColor:'#F0F7FF'})}.width('100%').height('100%').padding(20).justifyContent(FlexAlign.Center)}}

2. 不同尺寸

@Entry @Component struct ButtonExample2{build(){Column({space:15}){Row({space:12}){IconButton({textIcon:'S',// S = Settings（设置）buttonSize:'small'})IconButton({textIcon:'S',buttonSize:'medium'})IconButton({textIcon:'S',buttonSize:'large'})}.width('100%').justifyContent(FlexAlign.Center)}.width('100%').height('100%').padding(20).justifyContent(FlexAlign.Center)}}

3. 不同形状

@Entry @Component struct ButtonExample3{build(){Column({space:15}){Row({space:12}){// 圆形按钮IconButton({textIcon:'U',// U = User（用户）shape:'circle'})// 方形按钮IconButton({textIcon:'U',shape:'square'})}.width('100%').justifyContent(FlexAlign.Center)}.width('100%').height('100%').padding(20).justifyContent(FlexAlign.Center)}}

4. 自定义颜色

@Entry @Component struct ButtonExample4{build(){Column({space:15}){Row({space:12}){// 默认颜色IconButton({textIcon:'S'// S = Settings（设置）})// 自定义图标颜色IconButton({textIcon:'√',// √ = Check（确认/成功）iconColor:'#34C759'})// 自定义背景颜色IconButton({textIcon:'S',buttonBackgroundColor:'#F0F7FF'})// 自定义图标和背景颜色IconButton({textIcon:'×',// × = Close（关闭/删除）iconColor:'#FF3B30',buttonBackgroundColor:'#FFEBEE'})}.width('100%').justifyContent(FlexAlign.SpaceAround)}.width('100%').height('100%').padding(20).justifyContent(FlexAlign.Center)}}

5. 加载状态

@Entry @Component struct ButtonExample5{@State loading:boolean=false// 处理加载操作handleLoad(){this.loading=true// 模拟异步操作setTimeout(()=>{this.loading=falseconsole.info('加载完成')},2000)}build(){Column({space:20}){IconButton({textIcon:'R',// R = Refresh（刷新）loading:this.loading})// 使用普通按钮触发加载状态Button(){Text(this.loading?'加载中...':'点击刷新')}.onClick(()=>{this.handleLoad()}).enabled(!this.loading)Text('点击按钮查看加载状态').fontSize(12).fontColor('#999999')}.width('100%').height('100%').padding(20).justifyContent(FlexAlign.Center)}}

6. 禁用状态

@Entry @Component struct ButtonExample6{@State canDelete:boolean=falsebuild(){Column({space:20}){IconButton({textIcon:'D',// D = Delete（删除）disabled:!this.canDelete})Row({space:10}){Text('删除权限：').fontSize(14)Toggle({type:ToggleType.Switch,isOn:this.canDelete}).onChange((isOn:boolean)=>{this.canDelete=isOn})Text(this.canDelete?'已开启':'已关闭').fontSize(14).fontColor(this.canDelete?'#10B981':'#EF4444')}}.width('100%').height('100%').padding(20).justifyContent(FlexAlign.Center)}}

7. 工具栏场景

@Entry @Component struct ToolbarExample{build(){Column({space:20}){// 工具栏Row({space:8}){IconButton({textIcon:'B',buttonSize:'small',shape:'square'})IconButton({textIcon:'I',buttonSize:'small',shape:'square'})IconButton({textIcon:'U',buttonSize:'small',shape:'square'})Divider().vertical(true).height(24).margin({left:8,right:8})IconButton({textIcon:'<',// < = 左对齐buttonSize:'small',shape:'square'})IconButton({textIcon:'=',// = = 居中对齐buttonSize:'small',shape:'square'})IconButton({textIcon:'>',// > = 右对齐buttonSize:'small',shape:'square'})}.width('100%').padding(12).backgroundColor('#F9FAFB').borderRadius(8)}.width('100%').height('100%').padding(20)}}

8. 列表操作场景

@Entry @Component struct ListActionExample{build(){Column({space:20}){// 列表项操作Row({space:12}){Text('文件名称.txt').fontSize(14).layoutWeight(1)IconButton({textIcon:'E',// E = Edit（编辑）buttonSize:'small',shape:'square'})IconButton({textIcon:'D',// D = Delete（删除）buttonSize:'small',shape:'square',iconColor:'#FF3B30'})}.width('100%').padding(12).backgroundColor('#FFFFFF').borderRadius(8).shadow({radius:4,color:'#00000010',offsetX:0,offsetY:2})}.width('100%').height('100%').padding(20)}}

9. 卡片操作场景

@Entry @Component struct CardActionExample{build(){Column({space:20}){// 卡片右上角操作Stack(){Column({space:8}){Text('卡片标题').fontSize(16).fontWeight(FontWeight.Bold)Text('卡片内容描述').fontSize(14).fontColor('#666666')}.width('100%').alignItems(HorizontalAlign.Start)IconButton({textIcon:'...',// ... = More（更多）buttonSize:'small',shape:'circle'}).align(Alignment.TopEnd)}.width('100%').padding(16).backgroundColor('#FFFFFF').borderRadius(12).shadow({radius:4,color:'#00000010',offsetX:0,offsetY:2})}.width('100%').height('100%').padding(20)}}

10. 按钮组合

@Entry @Component struct ButtonGroupExample{build(){Column({space:20}){// 操作按钮组Row({space:12}){IconButton({textIcon:'+',buttonSize:'medium',shape:'circle',buttonBackgroundColor:'#F0F7FF'})IconButton({textIcon:'E',// E = Edit（编辑）buttonSize:'medium',shape:'circle'})IconButton({textIcon:'D',// D = Delete（删除）buttonSize:'medium',shape:'circle',iconColor:'#FF3B30'})}.width('100%').justifyContent(FlexAlign.Center)}.width('100%').height('100%').padding(20).justifyContent(FlexAlign.Center)}}

主题配置

IconButton 的所有样式都通过ComponentTheme配置，所有配置都在代码中，不依赖JSON文件。

修改默认颜色

import{ComponentTheme}from'../theme/ComponentTheme'// 修改主题主色（影响 IconButton 的默认图标颜色）ComponentTheme.PRIMARY_COLOR='#007AFF'// 修改文字主色（影响 IconButton 的默认图标颜色）ComponentTheme.TEXT_PRIMARY='#000000'// 修改禁用文字颜色ComponentTheme.TEXT_DISABLED='#CCCCCC'// 修改背景次要色（影响禁用状态的背景）ComponentTheme.BACKGROUND_SECONDARY='#F5F5F5'

批量配置

import{ComponentTheme}from'../theme/ComponentTheme'// 使用 setTheme 方法批量配置ComponentTheme.setTheme({primaryColor:'#007AFF',borderRadius:8,spacing:16})

自定义主题

// 在应用启动时配置import{ComponentTheme}from'./theme/ComponentTheme'// 设置自定义主色ComponentTheme.TEXT_PRIMARY='#34C759'// 绿色

最佳实践

1. 形状选择

2. 尺寸选择

small：用于工具栏、列表操作、表格操作
medium：默认尺寸，适用于大多数场景
large：用于重要操作或大屏幕显示

3. 颜色使用

默认使用主题主色，保持视觉统一
危险操作使用红色（如删除按钮）
特殊操作可使用自定义颜色
避免在同一页面使用过多不同颜色

4. 图标选择

推荐使用 ASCII 字符：确保在所有系统上都能正确显示
字符映射：使用标准字符映射（S=设置, U=用户, R=刷新, D=删除, E=编辑, +=添加, √=确认, ×=关闭）
清晰易识别：选择清晰、易识别的字符
尺寸适配：确保图标在不同尺寸下都清晰可见（large 尺寸图标为 40vp）

5. 工具栏使用

将相关操作分组
使用分隔线区分不同功能组
保持一致的尺寸和形状

6. 响应式设计

在小屏幕上考虑使用 smaller 尺寸
保持按钮之间的合理间距
确保触摸目标足够大（至少 32vp）

常见问题

Q1: IconButton 和其他按钮有什么区别？

A: 主要区别在于显示内容：

PrimaryButton/SecondaryButton/TextButton：显示文字（可带图标）
IconButton：仅显示图标，无文字

IconButton 更适合工具栏、操作按钮等需要节省空间的场景。

Q2: 什么时候使用圆形，什么时候使用方形？

A: 根据使用场景选择：

圆形（circle）：工具栏、浮动操作按钮、卡片操作、需要突出显示的操作
方形（square）：列表操作、表格操作、紧凑空间、需要对齐的场景

Q3: 如何自定义按钮颜色？

A: 有两种方式：

通过 iconColor 和 buttonBackgroundColor 属性（单个按钮）：

IconButton({textIcon:'S',// S = Settings（设置）iconColor:'#34C759',buttonBackgroundColor:'#F0F9F4'})

通过 ComponentTheme（全局配置）：

ComponentTheme.TEXT_PRIMARY='#34C759'ComponentTheme.BACKGROUND_SECONDARY='#F0F9F4'

Q4: 如何处理按钮点击事件？

A:onClickBuilder是@BuilderParam类型，需要使用@Builder或@LocalBuilder方法。推荐使用状态管理或自定义事件系统：

@Entry @Component struct MyPage{@State count:number=0handleClick(){this.count++console.info('按钮被点击')}build(){Column({space:20}){// 使用普通按钮处理点击Button(){Image($r('app.media.icon_settings')).width(20).height(20)}.onClick(()=>{this.handleClick()})// 使用 IconButton 展示样式IconButton({textIcon:'S'// S = Settings（设置）})Text(`点击次数：${this.count}`)}.width('100%').height('100%').padding(20)}}

Q5: IconButton 可以用于工具栏吗？

A: 可以。IconButton 非常适合用于工具栏场景：

Row({space:8}){IconButton({textIcon:'B',// B = Bold（粗体）buttonSize:'small',shape:'square'})IconButton({textIcon:'I',// I = Italic（斜体）buttonSize:'small',shape:'square'})}

Q6: 按钮大小可以自定义吗？

A: 目前支持三种预设尺寸（small、medium、large）。如果需要自定义大小，可以通过修改ComponentTheme中的相关配置，或者使用其他按钮组件（如 TextButton）配合图标实现。

总结

IconButton 是控件库中的图标按钮组件，具有以下核心特性：

纯图标设计：仅显示图标，节省空间
形状灵活：支持圆形和方形两种形状
尺寸多样：三种尺寸满足不同场景需求
功能完整：支持加载、禁用等多种状态
易于使用：简单的 API，开箱即用
主题配置：所有样式都可通过代码配置
品牌标识：自动包含品牌标识，保持视觉统一

关键要点

✅ 使用shape属性选择合适形状
✅ 使用buttonSize属性选择合适尺寸
✅ 使用iconColor和buttonBackgroundColor自定义颜色
✅ 使用loading属性处理异步操作
✅ 使用disabled属性控制按钮状态
✅ 通过ComponentTheme自定义全局样式

适用场景

工具栏操作按钮
列表项操作按钮
卡片操作按钮
表格操作按钮
浮动操作按钮
需要节省空间的按钮场景

下一篇预告：ButtonGroup（按钮组）详解

本文档属于《鸿蒙PC UI控件库开发系列文章》第5篇