鸿蒙PC UI控件库 - ButtonGroup 按钮组详解

最新推荐文章于 2025-12-22 21:11:19 发布
原创 最新推荐文章于 2025-12-22 21:11:19 发布 · 764 阅读 · 15 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#harmonyos #ui #android

视频演示地址：

https://www.bilibili.com/video/BV1jomdBBE4H/
在这里插入图片描述

📋 目录

概述

ButtonGroup 是控件库中的按钮组组件，将多个按钮组合在一起，支持单选和多选两种模式，适用于选项选择、筛选、状态切换等场景。

设计理念

按钮组采用统一视觉设计，具有以下特点：

  1. 组合设计：多个按钮无缝连接，形成统一的视觉整体
  2. 模式灵活：支持单选（single）和多选（multiple）两种模式
  3. 尺寸多样：支持 small、medium、large 三种尺寸
  4. 状态清晰：选中状态使用主色背景，未选中状态使用次要背景
  5. 品牌标识：左下角自动包含品牌标识（圆圈红字"PC"）
  6. 主题统一：所有样式配置都在代码中，方便定制

适用场景

  • 筛选条件：时间筛选、状态筛选、类型筛选
  • 选项选择：单选选项、多选选项
  • 状态切换：启用/禁用、显示/隐藏
  • 标签选择：分类标签、属性标签

特性

✨ 核心特性

  • ✅ 单选模式：支持单选模式，只能选择一个选项
  • ✅ 多选模式：支持多选模式，可以选择多个选项
  • ✅ 图标支持：支持文字图标（textIcon）和图片图标（icon）
  • ✅ 多种尺寸：支持 small、medium、large 三种尺寸
  • ✅ 禁用状态：支持整体禁用和单项禁用
  • ✅ 品牌标识：自动包含左下角品牌标识
  • ✅ 主题配置：所有样式都可通过代码配置

🎨 视觉特点

  • 选中状态：主色背景 + 白色文字
  • 未选中状态：次要背景 + 主色文字
  • 禁用状态：灰色背景 + 灰色文字 + 50% 透明度
  • 无缝连接：按钮之间无缝连接，形成统一整体
  • 圆角设计：整体使用圆角，内部按钮无圆角

快速开始

基础用法

import { ButtonGroup, ButtonGroupItem } from '../components/base'

@Entry
@Component
struct MyPage {
  @State selectedValue: string | number = 'option1'

  private items: ButtonGroupItem[] = [
    { label: '选项1', value: 'option1' },
    { label: '选项2', value: 'option2' },
    { label: '选项3', value: 'option3' }
  ]

  build() {
    Column({ space: 20 }) {
      // 单选模式
      ButtonGroup({
        items: this.items,
        mode: 'single'
      })
      
      // 多选模式
      ButtonGroup({
        items: this.items,
        mode: 'multiple'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

关于状态管理

ButtonGroup 使用内部状态管理选中值。如果需要外部控制选中值，可以通过监听点击事件或使用状态管理来实现。

API 参考

Props

属性名类型默认值说明
itemsButtonGroupItem[][]按钮项列表（必需）
mode'single' | 'multiple''single'选择模式：单选或多选
buttonSize'small' | 'medium' | 'large''medium'按钮尺寸
showBrandbooleantrue是否显示品牌标识
disabledbooleanfalse是否禁用整个按钮组

ButtonGroupItem 接口

属性名类型默认值说明
labelstring-按钮文字（必需）
valuestring | number-按钮值（必需）
disabledboolean?undefined是否禁用该项
iconResourceStr?undefined图片图标（可选）
textIconstring?undefined文字图标（可选，优先级高于 icon）

尺寸规格

尺寸按钮高度字体大小图标大小内边距
small28vp12vp14vp12vp（左右）
medium36vp14vp16vp16vp（左右）
large44vp16vp20vp20vp（左右）

使用示例

1. 基础单选按钮组

@Entry
@Component
struct ButtonGroupExample1 {
  private items: ButtonGroupItem[] = [
    { label: '选项1', value: 'option1' },
    { label: '选项2', value: 'option2' },
    { label: '选项3', value: 'option3' }
  ]

  build() {
    Column({ space: 15 }) {
      ButtonGroup({
        items: this.items,
        mode: 'single'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

2. 多选按钮组

@Entry
@Component
struct ButtonGroupExample2 {
  private items: ButtonGroupItem[] = [
    { label: '选项1', value: 'option1' },
    { label: '选项2', value: 'option2' },
    { label: '选项3', value: 'option3' }
  ]

  build() {
    Column({ space: 15 }) {
      ButtonGroup({
        items: this.items,
        mode: 'multiple'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

3. 带图标的按钮组

@Entry
@Component
struct ButtonGroupExample3 {
  private items: ButtonGroupItem[] = [
    { label: '全部', value: 'all', textIcon: 'A' },
    { label: '待处理', value: 'pending', textIcon: 'P' },
    { label: '已完成', value: 'completed', textIcon: '√' }
  ]

  build() {
    Column({ space: 15 }) {
      ButtonGroup({
        items: this.items,
        mode: 'single'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

4. 不同尺寸

@Entry
@Component
struct ButtonGroupExample4 {
  private items: ButtonGroupItem[] = [
    { label: '小', value: 'small' },
    { label: '中', value: 'medium' },
    { label: '大', value: 'large' }
  ]

  build() {
    Column({ space: 20 }) {
      ButtonGroup({
        items: this.items,
        mode: 'single',
        buttonSize: 'small'
      })
      
      ButtonGroup({
        items: this.items,
        mode: 'single',
        buttonSize: 'medium'
      })
      
      ButtonGroup({
        items: this.items,
        mode: 'single',
        buttonSize: 'large'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

5. 禁用状态

@Entry
@Component
struct ButtonGroupExample5 {
  private items: ButtonGroupItem[] = [
    { label: '可用', value: 'available' },
    { label: '不可用', value: 'unavailable', disabled: true },
    { label: '维护中', value: 'maintenance' }
  ]

  build() {
    Column({ space: 20 }) {
      // 整个按钮组禁用
      ButtonGroup({
        items: this.items,
        mode: 'single',
        disabled: true
      })
      
      Divider()
        .margin({ top: 20, bottom: 20 })
      
      // 部分按钮禁用
      ButtonGroup({
        items: this.items,
        mode: 'single'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

6. 筛选场景

@Entry
@Component
struct FilterExample {
  build() {
    Column({ space: 20 }) {
      // 时间筛选
      Column({ space: 10 }) {
        Text('时间筛选：')
          .fontSize(16)
          .fontColor('#111827')
          .width('100%')
        
        ButtonGroup({
          items: [
            { label: '全部', value: 'all' },
            { label: '今天', value: 'today' },
            { label: '本周', value: 'week' },
            { label: '本月', value: 'month' }
          ],
          mode: 'single',
          buttonSize: 'medium'
        })
      }
      .width('100%')
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

7. 状态选择场景

@Entry
@Component
struct StatusExample {
  build() {
    Column({ space: 20 }) {
      // 订单状态（多选）
      Column({ space: 10 }) {
        Text('订单状态（多选）：')
          .fontSize(16)
          .fontColor('#111827')
          .width('100%')
        
        ButtonGroup({
          items: [
            { label: '待付款', value: 'unpaid', textIcon: 'P' },
            { label: '待发货', value: 'unshipped', textIcon: 'S' },
            { label: '已发货', value: 'shipped', textIcon: '√' },
            { label: '已完成', value: 'completed', textIcon: 'C' }
          ],
          mode: 'multiple',
          buttonSize: 'medium'
        })
      }
      .width('100%')
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

主题配置

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

修改默认颜色

import { ComponentTheme } from '../theme/ComponentTheme'

// 修改主色（影响选中状态的背景色）
ComponentTheme.PRIMARY_COLOR = '#007AFF'

// 修改次要背景色（影响未选中状态的背景色）
ComponentTheme.BACKGROUND_SECONDARY = '#F5F5F5'

// 修改边框颜色
ComponentTheme.BORDER_COLOR = '#E5E5E5'

// 修改圆角
ComponentTheme.BORDER_RADIUS = 8

批量配置

import { ComponentTheme } from '../theme/ComponentTheme'

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

最佳实践

1. 模式选择

推荐：根据使用场景选择模式

  • 单选模式（single）：用于互斥选项，如时间筛选、状态切换
  • 多选模式（multiple）：用于可多选的选项，如标签选择、属性筛选

2. 尺寸选择

  • small：用于紧凑空间、工具栏
  • medium：默认尺寸，适用于大多数场景
  • large：用于重要操作或大屏幕显示

3. 选项数量

  • 建议选项数量在 2-5 个之间
  • 选项过多时考虑使用下拉菜单或其他组件
  • 选项文字保持简洁，避免过长

4. 图标使用

  • 使用文字图标（textIcon）确保兼容性
  • 图标应与文字含义相关
  • 保持图标风格统一

5. 禁用状态

  • 使用整体禁用（disabled）控制整个按钮组
  • 使用单项禁用（item.disabled）控制单个选项
  • 禁用状态应清晰可见

6. 响应式设计

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

常见问题

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

A: 主要区别在于使用场景：

  • PrimaryButton/SecondaryButton/TextButton/IconButton：单个按钮，用于操作
  • ButtonGroup：多个按钮组合，用于选项选择、筛选

ButtonGroup 更适合需要从多个选项中选择的场景。

Q2: 什么时候使用单选，什么时候使用多选？

A: 根据业务需求选择：

  • 单选模式（single）：选项互斥，只能选择一个，如时间筛选、状态切换
  • 多选模式（multiple）：选项不互斥，可以选择多个，如标签选择、属性筛选

Q3: 如何获取选中的值？

A: ButtonGroup 使用内部状态管理。如果需要外部获取选中值，可以通过以下方式：

  1. 监听点击事件：在按钮点击时获取值
  2. 状态管理：使用全局状态管理（如 Redux、MobX）
  3. 自定义事件：创建自定义事件系统

Q4: 可以动态更新选项吗？

A: 可以。通过更新 items 数组来动态更新选项：

@State items: ButtonGroupItem[] = [
  { label: '选项1', value: 'option1' }
]

// 动态添加选项
this.items.push({ label: '选项2', value: 'option2' })
this.items = [...this.items]  // 触发更新

Q5: 如何自定义按钮样式？

A: 可以通过 ComponentTheme 自定义全局样式：

ComponentTheme.PRIMARY_COLOR = '#34C759'  // 选中状态背景色
ComponentTheme.BACKGROUND_SECONDARY = '#F0F0F0'  // 未选中状态背景色
ComponentTheme.BORDER_RADIUS = 12  // 圆角大小

Q6: 按钮组可以垂直排列吗？

A: 当前版本支持水平排列。如果需要垂直排列，可以：

  1. 使用多个 ButtonGroup 垂直排列
  2. 自定义实现垂直布局的按钮组

总结

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

  1. 组合设计：多个按钮无缝连接，形成统一整体
  2. 模式灵活：支持单选和多选两种模式
  3. 尺寸多样：三种尺寸满足不同场景需求
  4. 功能完整：支持图标、禁用等多种功能
  5. 易于使用：简单的 API，开箱即用
  6. 主题配置：所有样式都可通过代码配置
  7. 品牌标识：自动包含品牌标识，保持视觉统一

关键要点

  • ✅ 使用 mode 属性选择单选或多选模式
  • ✅ 使用 buttonSize 属性选择合适尺寸
  • ✅ 使用 items 属性配置按钮项
  • ✅ 使用 disabled 属性控制按钮组状态
  • ✅ 使用 textIcon 或 icon 添加图标
  • ✅ 通过 ComponentTheme 自定义全局样式

适用场景

  • 筛选条件选择
  • 选项选择
  • 状态切换
  • 标签选择
  • 属性筛选

下一篇预告：TextInput（文本输入框）详解

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

C#WPF控件Button详解
qq_30725967的博客
03-29 521
C#WPF按钮控件Button详解
鸿蒙PC UI控件库 - IconButton 图标按钮详解
红目香薰
12-13 713
IconButton是一个纯图标按钮组件，适用于工具栏等场景。核心特性包括：仅显示图标无文字、支持圆形/方形两种形状、small/medium/large三种尺寸（large为80×80vp）、自动包含品牌标识。提供加载状态、禁用状态和自定义颜色功能，所有样式均可代码配置。推荐使用ASCII字符作为图标以确保兼容性，如S(设置)、U(用户)、+(添加)等。组件API支持图标资源或文字图标，并可通过@Builder处理点击事件。
【Material-UI】按钮组：Split Button 详解
lph159的博客
08-07 1478
Split Button 是一种组合按钮，它由一个主按钮和一个下拉菜单按钮组成。主按钮用于执行默认操作，而下拉菜单按钮用于选择其他操作。这样，用户可以快速执行常用操作，同时也可以轻松访问其他选项。Material-UI 的组件通过支持 Split Button，为开发者提供了更灵活的操作选项。Split Button 在提交操作、导出操作和文件操作等场景中具有广泛的应用。通过合理设置按钮组的变体和颜色，可以提升界面的视觉一致性和用户体验。
android 圆形单选框,Android UI控件详解-RadioGroup和RadioButton(单选框)
weixin_32940141的博客
05-29 1326
package com.bdqn.radiobutton;import android.os.Bundle;import android.app.Activity;import android.widget.RadioGroup;import android.widget.RadioGroup.OnCheckedChangeListener;import android.widget.Toast;...
HandyControl按钮控件详解：SplitButton、ProgressButton等8种高级按钮
gitblog_00710的博客
11-23 355
HandyControl是一个功能强大的WPF UI控件库，提供了丰富多样的按钮控件来满足现代应用程序的交互需求。作为WPF开发者的终极工具箱，它让创建专业级界面变得简单快捷。本文将详细介绍HandyControl中最实用的8种高级按钮控件，帮助你快速掌握这些强大的UI组件。 ## 🎯 HandyControl按钮控件概览 HandyControl的按钮控件库设计精美、功能完善，能够显著提升
打造WPF照片编辑器：HandyControl控件组合案例
gitblog_00935的博客
09-10 356
你是否还在为WPF项目中图片编辑功能的复杂实现而烦恼？是否希望找到一套高效、美观且易于集成的控件解决方案？本文将带你使用HandyControl控件库，从零开始构建一个功能完备的WPF照片编辑器，通过实际案例展示如何巧妙组合各种控件，轻松实现专业级图片处理功能。读完本文，你将掌握HandyControl核心控件的协同使用方法，学会构建响应式图片编辑界面，并能够将这些技巧应用到自己的WPF项目中。 ...
Matlab GUI组件详解
优快云_l_i_u的博客
05-16 5957
matlab gui
细品RibbonX(31)：buttonGroup元素详解
狂奔之林的博客
03-02 1990
细品RibbonX(31)：buttonGroup元素详解资料整理来自于论坛完整版下载地址：http://download.youkuaiyun.com/download/nodeman/10264659  Loading ... buttonGroup元素与box元素相似，但它也有一些独特的特征。buttonGroup控件和box控件之间在外观上最大的不同是box控件不会在组周围放置可视的边框，而butto...
细品RibbonX(27)：menu控件详解
狂奔之林的博客
03-02 2569
细品RibbonX(27)：menu控件详解资料整理来自于论坛完整版下载地址：http://download.youkuaiyun.com/download/nodeman/10264659 Loading ... 菜单提供给用户可供从中选取的预定义选项列表，与dropDown控件一样，能够组合图像和文本。表面上，菜单的用途与下拉控件的用途非常相似。然而，下拉控件的一个主要局限是仅能包含“项目”，而菜单控件可...
Ember UI组件库：打造高效Ember应用界面
- 按钮组：将多个按钮组织在一起，以提供一组相关的操作选项。 - 复选框：允许用户在一个选项集中选择多个项。 - 上下文菜单：一种弹出菜单，提供与当前情境相关的选项。 - 落下：与下拉菜单相似，用于显示额外的...
Jquery LigerUI 中文 API
12-25
**jQuery LigerUI 中文 API 知识点详解** jQuery LigerUI 是一款基于 jQuery 的前端组件库，它提供了一套完整的用户界面解决方案，适用于快速构建功能丰富的 Web 应用程序。LigerUI 包含了大量的组件，如表格、表单...
jiaahui-ui: 面向Web开发者的Vue.js 2.X UI组件库
### 知识点详解 #### 1. Vue.js框架介绍 Vue.js是一个流行的前端JavaScript框架，用于构建用户界面和单页应用程序（SPA）。其核心库只关注视图层，易于上手，并且可以轻松地与现有的项目集成。Vue采用数据驱动和...
ExtJS控件详解：基础组件与高级功能
4. Ext.ButtonGroup（Since 3.0）：用于创建一组互斥的按钮，用户只能选择其中一个。 5. Ext.Slider：滑动条组件，用于调整数值或设置范围。 6. Ext.ProgressBar：进度条，用于表示任务的完成度。 7. Ext.StatusBar...
HarmonyOS 5 高效使用命令：HDC 使用指南
最新发布
weixin_48952056的博客
12-22 866
本文介绍了鸿蒙开发中HDC命令行工具的环境配置与设备连接方法。主要内容包括：HDC工具获取路径（通过SDK或命令行工具）、Windows/MacOS/Linux系统的环境变量配置步骤、USB调试连接方法及常见问题排查、无线WiFi调试的详细操作流程（包括端口设置、IP查询和连接命令）、多设备管理时的目标指定方法，并提供了一个Windows一键无线连接脚本示例。通过掌握这些基础连接技能，开发者可以更高效地解决鸿蒙开发中的设备连接问题。
HarmonyOS应用开发－组件状态
liuyang1981228的博客
12-19 540
组件状态
鸿蒙应用的测试和调试完全指南：从单元测试到性能分析
源滚滚编程
12-22 313
测试和调试是构建高质量应用的关键。编写单元测试验证单个函数的功能编写集成测试验证组件之间的交互进行性能测试确保应用性能使用调试工具诊断问题编写可测试的代码使用测试覆盖率工具建立持续集成流程现在就在你的项目中应用这些最佳实践吧。如果你有任何问题或想法，欢迎在评论区分享。
HarmonyOS应用开发－初探HarmonyOS应用
liuyang1981228的博客
12-17 982
/ 响应式数据 -> 视图层build里面 this.响应式名 this.响应式名 = 数据。<input typet="text" placeholder="请输入内容" value="默认数据" />Image(图片本地地址) $r('app.media.xxxxxx')Button('各种按钮').type(ButtonType.Normal)// - .alignItems() 交叉轴方向。// - .justifyContent() 主轴方向。
HarmonyOS NEXT之深入解析Grid网格布局列表的交互与状态管理
╰つ栺尖篴夢ゞ
12-19 1065
Grid 组件是 ArkUI 框架中强大的网格布局容器，与 GridItem 子组件配合使用可创建灵活的网格布局。该组件支持自定义行列数、尺寸占比控制、子组件跨行列、间距设置和滚动能力等特性。通过 rowsTemplate 和 columnsTemplate 属性可设置网格布局的行列数量与占比，未设置时可通过 layoutDirection 决定排列方式。Grid 还支持绑定 Scroller 对象实现滚动控制，适用于日历翻页等场景。实战中可用于构建商品展示等网格布局，通过设置两列模板和行列间距实现整齐排列
鸿蒙2025：领航者的技术突围战
LiuSid7的博客
12-19 1041
《鸿蒙2025领航指南：技术突破与生态实践全景》 本文系统阐述了鸿蒙6.0在2025年的技术演进与生态建设路径。通过三大核心赛道展开：1）分布式能力、金融安全、跨设备办公等关键技术突破；2）开发者能力成长三维模型及社区影响力构建方法论；3）智能家居、工业互联网、医疗健康等行业的落地实践案例。文章提供了从技术攻坚到商业落地的完整框架，包含分布式数据管理、元服务编排等创新架构设计，以及性能优化、工程规范等实战经验，为开发者转型生态领航者提供可量化的成长路线图。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

红目香薰

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值