输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS 5.0.1(13)

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
API参考
高级筛选
元服务API集不筛选

ChipGroup

更新时间: 2025-03-14 09:23
本文导读
展开章节

ChipGroup高级组件，提供操作块群组，用于对文件或者资源内容进行分类等场景。

说明

该组件从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

导入模块

收起
自动换行
深色代码主题
复制
  1. import { ChipSize, ChipGroup } from '@kit.ArkUI'

子组件

无

ChipGroup

收起
自动换行
深色代码主题
复制
  1. ChipGroup({
  2.   items: ChipGroupItemOptions[],
  3.   itemStyle?: ChipItemStyle,
  4.   selectedIndexes?: Array<number>,
  5.   multiple?: boolean,
  6.   chipGroupSpace?: ChipGroupSpaceOptions,
  7.   chipGroupPadding?: ChipGroupPaddingOptions,
  8.   onChange?: (selectedIndexes: Array<number>) => void,
  9.   suffix?: Callback<void>
  10. })

装饰器类型：@Component

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 装饰器类型 说明
items ChipGroupItemOptions[] 是 @Require @Prop

每个chip特定的属性，参考ChipGroupItemOptions[]类型。

为undefined时，ChipGroup默认为空。
itemStyle ChipItemStyle 否 @Prop

chip的style属性，比如颜色，大小等，参考ChipItemStyle类型。

为undefined时，ChipGroup中的Chip式样为默认值。
selectedIndexes Array<number> 否 @Prop

被选中chip的索引。

为undefined时，默认第一个Chip被选中。
multiple boolean 否 @Prop

true：支持多个chip被选中；false：只能是单个chip被选中。

默认值：false

为undefined时，multiple走默认值。
chipGroupSpace ChipGroupSpaceOptions 否 @Prop

左右内边距，和chip与chip之间的间距。参考ChipGroupSpaceOptions类型。

为undefined时，chipGroupSpace走默认值。
chipGroupPadding ChipGroupPaddingOptions 否 @Prop

chipGroup的上下内边距，以便控制整体高度。参考ChipGroupPaddingOptions类型。

为undefined时，chipGroupPadding走默认值。
onChange Callback<Array<number>> 否 -

chip状态改变时候的回调方法。

为undefined时，表示解绑事件。
suffix ()=>void 否 @BuilderParam

最右侧的builder，由使用者自定义，使用时候需引入IconGroupSuffix接口。

默认值：不传入的情况，没有suffix。
说明

  1. 针对selectedIndexes和multiple接口，multiple等于false的时候，当没有传入selectedIndexes时候，默认是第一个chip被选中，当传入的selectedIndexes有一个以上的元素时候，默认第一个索引的chip被选中。

  2. 针对suffix接口，使用时候需要引入IconGroupSuffix接口，不传入的情况，没有suffix。

  3. 关于图标填充色（fillColor以及activedFillColor）的设置，跟随字体颜色（fontColor）保持一致。若想两者颜色不同，则需要在传入ChipGroupSpaceOptions时，使用prefixSymbol。

ChipGroupItemOptions

ChipGroupItemOptions定义每个chip的非共通属性。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 说明
prefixIcon IconOptions 否 前缀Image图标属性。
prefixSymbol ChipSymbolGlyphOptions 否 前缀SymbolGlyph图标属性。
label LabelOptions 是 文本属性。
suffixIcon IconOptions 否 后缀Image图标属性。
suffixSymbol ChipSymbolGlyphOptions 否 后缀SymbolGlyph图标属性。
allowClose boolean 否

删除图标是否显示。

默认值：false。
说明

suffixIcon有传入参数时，allowClose不生效，suffixIcon没有传入参数时，allowClose决定是否显示删除图标。

ChipItemStyle

ChipItemStyle定义了chip的共通属性。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 说明
size ChipSize | SizeOptions 否

chip尺寸，使用时需要从chip组件引入ChipSize类型。

默认值：ChipSize：ChipSize.NORMAL。

为undefined时，ChipSize走默认值。
backgroundColor ResourceColor 否

chip背景颜色。

默认值：$r('sys.color.ohos_id_color_button_normal')。

为undefined时，backgroundColor走默认值。
fontColor ResourceColor 否

chip文字颜色。

默认值：$r('sys.color.ohos_id_color_text_primary')。

为undefined时，fontColor走默认值。
selectedFontColor ResourceColor 否

chip激活时的文字颜色。

默认值：$r('sys.color.ohos_id_color_text_primary_contrary')。

为undefined时，selectedFontColor走默认值。
selectedBackgroundColor ResourceColor 否

chip激活时的背景颜色。

默认值：$r('sys.color.ohos_id_color_emphasize')。

为undefined时，selectedBackgroundColor走默认值。
说明

1.操作块的大小可以是两种类型，一种是ChipSize，为方便使用，有两种尺寸可选分别是NORMAL和SMALL；另一种是SizeOptions。

2.backgroundColor、selectedBackgroundColor赋值undefined时，显示默认背景颜色，赋值非法值时，背景色透明。

ChipGroupSpaceOptions

ChipGroupSpaceOptions 定义了chipGroup左右内边距，以及chip与chip直接的间距。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 说明
itemSpace string | number 否

chip与chip之间的间距（不支持百分比）。

默认值：8

单位：vp

为undefined时，itemSpace走默认值。
startSpace Length 否

左侧内边距（不支持百分比）。

默认值：16

单位：vp

为undefined时，startSpace走默认值。
endSpace Length 否

右侧内边距（不支持百分比）。

默认值：16

单位：vp

为undefined时，endSpace走默认值。

ChipGroupPaddingOptions

ChipGroupPaddingOptions 定义了chipGroup上下内边距，以便控制chipGroup的整体高度。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 说明
top Length 是

chipGroup的上方内边距（不支持百分比）。

默认值：14

为undefined时，top走默认值。
bottom Length 是

chipGroup的上方内边距（不支持百分比）。

默认值：14

为undefined时，bottom走默认值。

IconGroupSuffix

装饰器类型：@Component

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 装饰器类型 说明
items Array<IconItemOptions | SymbolGlyphModifier> 是 @Require @Prop 自定义builder items。
说明

传参SymbolGlyphModifier时，不支持通过symbolEffect修改动效类型和effectStrategy设置动效。

IconItemOptions

尾部builder接口定义，针对背板大小及颜色设置限制。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 说明
icon IconOptions 是

自定义Builder icon。

chip大小是ChipSize.SMALL时，suffix默认值：{width: 16,height: 16}。

chip大小是ChipSize.NORMAL时，suffix默认值：{width: 24,height: 24}。

如果想动态修改size，那么必须在引入IconGroupSuffix时，使用SymbolGlyphModifier类型。
action Callback<void> 是

自定义Builder items 的Callback

为undefined时，表示解绑事件。

IconOptions

IconOptions定义图标的共通属性。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 说明
src ResourceStr 是 图标图片或图片地址引用。
size SizeOptions 否 图标大小，不支持百分比。

LabelOptions

Label定义图标的共通属性。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 说明
text string 是 文本属性

示例

示例1（无最右侧的builder）

该示例实现了无最右侧的builder时效果。

收起
自动换行
深色代码主题
复制
  1. import { ChipSize, ChipGroup } from '@kit.ArkUI'
  2. 

  3. @Entry
  4. @Preview
  5. @Component
  6. struct Index {
  7.   @State selected_index: Array<number> = [0, 1, 2, 3, 4, 5, 6]
  8.   build() {
  9.     Column() {
  10.       ChipGroup({
  11.         items: [
  12.           {
  13.             prefixIcon: { src: $r('app.media.icon') },
  14.             label: { text: "操作块1" },
  15.             suffixIcon: { src: $r('sys.media.ohos_ic_public_cut') },
  16.             allowClose: false
  17.           },
  18.           {
  19.             prefixIcon: { src: $r('sys.media.ohos_ic_public_copy') },
  20.             label: { text: "操作块2" },
  21.             allowClose: true
  22.           },
  23.           {
  24.             prefixIcon: { src: $r('sys.media.ohos_ic_public_clock') },
  25.             label: { text: "操作块3" },
  26.             allowClose: true
  27.           },
  28.           {
  29.             prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') },
  30.             label: { text: "操作块4" },
  31.             allowClose: true
  32.           },
  33.           {
  34.             prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_mirror') },
  35.             label: { text: "操作块5" },
  36.             allowClose: true
  37.           },
  38.           {
  39.             prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') },
  40.             label: { text: "操作块6" },
  41.             allowClose: true
  42.           },
  43.         ],
  44.         itemStyle: {
  45.           size: ChipSize.SMALL,
  46.           backgroundColor: $r('sys.color.ohos_id_color_button_normal'),
  47.           fontColor: $r('sys.color.ohos_id_color_text_primary'),
  48.           selectedBackgroundColor: $r('sys.color.ohos_id_color_emphasize'),
  49.           selectedFontColor: $r('sys.color.ohos_id_color_text_primary_contrary'),
  50.         },
  51.         selectedIndexes: this.selected_index,
  52.         multiple: false,
  53.         chipGroupSpace: { itemSpace: 8, endSpace: 0 },
  54.         chipGroupPadding: { top: 10, bottom: 10 },
  55.         onChange: (activatedChipsIndex:Array<number>) => {
  56.           console.log('chips on clicked, activated index ' + activatedChipsIndex)
  57.         },
  58.       })
  59.     }
  60.   }
  61. }

示例2（有最右侧的builder）

该示例通过配置suffix实现最右侧的自定义组件效果。

收起
自动换行
深色代码主题
复制
  1. import { ChipSize, ChipGroup, IconGroupSuffix  } from '@kit.ArkUI'
  2. 

  3. @Entry
  4. @Preview
  5. @Component
  6. struct Index {
  7.   @State selected_index: Array<number> = [0, 1, 2, 3, 4, 5, 6]
  8.   @State selected_state: boolean = true;
  9. 

  10.   @LocalBuilder
  11.   ChipGroupSuffix(): void {
  12.     IconGroupSuffix({
  13.       items: [{
  14.         icon: { src: $r('sys.media.ohos_ic_public_search_filled'), size: { width: 36, height: 36 } },
  15.         action: () => {
  16.           if (this.selected_state == false) {
  17.             this.selected_index = [0, 1, 2, 3, 4, 5, 6]
  18.             this.selected_state = true
  19.           } else {
  20.             this.selected_index = []
  21.             this.selected_state = false
  22.           }
  23.         }
  24.       }
  25.       ]
  26.     })
  27.   }
  28. 

  29.   build() {
  30.     Column() {
  31.       ChipGroup({
  32.         items: [
  33.           {
  34.             prefixIcon: { src: $r('app.media.icon') },
  35.             label: { text: "操作块1" },
  36.             suffixIcon: { src: $r('sys.media.ohos_ic_public_cut') },
  37.             allowClose: false
  38.           },
  39.           {
  40.             prefixIcon: { src: $r('sys.media.ohos_ic_public_copy') },
  41.             label: { text: "操作块2" },
  42.             allowClose: true
  43.           },
  44.           {
  45.             prefixIcon: { src: $r('sys.media.ohos_ic_public_clock') },
  46.             label: { text: "操作块3" },
  47.             allowClose: true
  48.           },
  49.           {
  50.             prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') },
  51.             label: { text: "操作块4" },
  52.             allowClose: true
  53.           },
  54.           {
  55.             prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_mirror') },
  56.             label: { text: "操作块5" },
  57.             allowClose: true
  58.           },
  59.           {
  60.             prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') },
  61.             label: { text: "操作块6" },
  62.             allowClose: true
  63.           },
  64.         ],
  65.         itemStyle: {
  66.           size: ChipSize.NORMAL,
  67.           backgroundColor: $r('sys.color.ohos_id_color_button_normal'),
  68.           fontColor: $r('sys.color.ohos_id_color_text_primary'),
  69.           selectedBackgroundColor: $r('sys.color.ohos_id_color_emphasize'),
  70.           selectedFontColor: $r('sys.color.ohos_id_color_text_primary_contrary'),
  71.         },
  72.         selectedIndexes: this.selected_index,
  73.         multiple: true,
  74.         chipGroupSpace: { itemSpace: 8, endSpace: 0 },
  75.         chipGroupPadding: { top: 10, bottom: 10 },
  76.         onChange: (activatedChipsIndex: Array<number>) => {
  77.           console.log('chips on clicked, activated index ' + activatedChipsIndex)
  78.         },
  79.         suffix: this.ChipGroupSuffix
  80.       })
  81.     }
  82.   }
  83. }

示例3（设置Symbol类型图标）

该示例实现了IconGroupSuffix及ChipGroup传入SymbolGlyph资源。

收起
自动换行
深色代码主题
复制
  1. import { ChipSize, ChipGroup, IconGroupSuffix, SymbolGlyphModifier } from '@kit.ArkUI'
  2. 

  3. @Entry
  4. @Preview
  5. @Component
  6. struct Index {
  7.   @State selected_index: Array<number> = [0, 1, 2, 3, 4, 5, 6];
  8.   @State selected_state: boolean = true;
  9.   @State prefixModifierNormal: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_star'));
  10.   @State prefixModifierActivated: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Red]);
  11.   @State suffixModifierNormal: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_wifi'));
  12.   @State suffixModifierActivated: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_wifi')).fontColor([Color.Red]);
  13. 

  14.   @LocalBuilder
  15.   ChipGroupSuffix(): void {
  16.     IconGroupSuffix({
  17.       items: [
  18.         new SymbolGlyphModifier($r('sys.symbol.magnifyingglass'))
  19.           .onClick(() => {
  20.             if (this.selected_state == false) {
  21.               this.selected_index = [0, 1, 2, 3, 4, 5, 6];
  22.               this.selected_state = true;
  23.             } else {
  24.               this.selected_index = [];
  25.               this.selected_state = false;
  26.             }
  27.           })
  28.       ]
  29.     })
  30.   }
  31. 

  32.   build() {
  33.     Column() {
  34.       ChipGroup({
  35.         items: [
  36.           {
  37.             prefixSymbol: { normal: this.prefixModifierNormal, activated: this.prefixModifierActivated },
  38.             label: { text: "操作块1" },
  39.             suffixSymbol: { normal: this.suffixModifierNormal, activated: this.suffixModifierActivated },
  40.             allowClose: false,
  41.           },
  42.           {
  43.             prefixSymbol: { normal: this.prefixModifierNormal, activated: this.prefixModifierActivated },
  44.             label: { text: "操作块2" },
  45.             allowClose: true,
  46.           },
  47.           {
  48.             prefixIcon: { src: $r('sys.media.ohos_ic_public_clock') },
  49.             label: { text: "操作块3" },
  50.             allowClose: true,
  51.           },
  52.           {
  53.             prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') },
  54.             label: { text: "操作块4" },
  55.             allowClose: true,
  56.           },
  57.           {
  58.             prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_mirror') },
  59.             label: { text: "操作块5" },
  60.             allowClose: true,
  61.           },
  62.           {
  63.             prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') },
  64.             label: { text: "操作块6" },
  65.             allowClose: true,
  66.           },
  67.         ],
  68.         itemStyle: {
  69.           size: ChipSize.NORMAL,
  70.           backgroundColor: $r('sys.color.ohos_id_color_button_normal'),
  71.           fontColor: $r('sys.color.ohos_id_color_text_primary'),
  72.           selectedBackgroundColor: $r('sys.color.ohos_id_color_emphasize'),
  73.           selectedFontColor: $r('sys.color.ohos_id_color_text_primary_contrary'),
  74.         },
  75.         selectedIndexes: this.selected_index,
  76.         multiple: true,
  77.         chipGroupSpace: { itemSpace: 8, endSpace: 0 },
  78.         chipGroupPadding: { top: 10, bottom: 10 },
  79.         onChange: (activatedChipsIndex: Array<number>) => {
  80.           console.log('chips on clicked, activated index ' + activatedChipsIndex)
  81.         },
  82.         suffix: this.ChipGroupSuffix
  83.       })
  84.     }
  85.   }
  86. }

简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词