鸿蒙5.0开发进阶：UI框架-ArkTS组件（Chip）

最新推荐文章于 2025-03-15 20:57:23 发布

懂你的大海

最新推荐文章于 2025-03-15 20:57:23 发布

阅读量1k

点赞数 26

分类专栏： ArkTS 鸿蒙开发 ArkUI 文章标签： harmonyos 华为 android 前端 ArkUI ArkTS 鸿蒙系统

本文链接：https://blog.youkuaiyun.com/Androidbye/article/details/145208396

版权

鸿蒙开发同时被 3 个专栏收录

1034 篇文章

订阅专栏

ArkUI

762 篇文章

订阅专栏

ArkTS

556 篇文章

订阅专栏

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

Chip

操作块，用于搜索框历史记录或者邮件发送列表等场景。

说明

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

子组件

无

Chip

Chip({options:ChipOptions})

装饰器类型：@Builder

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

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

参数：

名称	类型	必填	装饰器类型	说明
options	ChipOptions	是	@Builder	定义chip组件的参数。

ChipOptions

ChipOptions定义chip的样式及具体式样参数。

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

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

名称	类型	必填	说明
size	ChipSize \| SizeOptions	否	操作块尺寸。默认值：ChipSize：ChipSize.NORMAL， SizeOptions类型参数不支持百分比设置。
enabled	boolean	否	操作块是否可选中。默认值：true
activated12+	boolean	否	操作块是否为激活态。默认值：false
prefixIcon	PrefixIconOptions	否	前缀图标属性。
prefixSymbol12+	ChipSymbolGlyphOptions	否	前缀图标属性，symbol类型。
label	LabelOptions	是	文本属性。
suffixIcon	SuffixIconOptions	否	后缀图标属性。
suffixSymbol12+	ChipSymbolGlyphOptions	否	后缀图标属性，symbol类型。
backgroundColor	ResourceColor	否	操作块背景颜色。默认值：$r('sys.color.ohos_id_color_button_normal')
activatedBackgroundColor12+	ResourceColor	否	操作块激活时的背景颜色。默认值：$r('sys.color.ohos_id_color_emphasize')。
borderRadius	Dimension	否	操作块背景圆角半径大小，不支持百分比。默认值：$r('sys.float.ohos_id_corner_radius_button')
allowClose	boolean	否	删除图标是否显示。默认值：true
onClose	()=>void	否	默认删除图标点击事件。
onClicked12+	()=>void	否	操作块点击事件。
direction12+	Direction	否	布局方向。默认值：Direction.Auto

说明

1.suffixSymbol有传入参数时，suffixIcon和allowClose不生效；suffixSymbol没有传入参数、suffixIcon有传入参数时，allowClose不生效；suffixSymbol和suffixIcon都没有传入参数时，allowClose决定是否显示删除图标。

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

3.prefixSymbol/suffixSymbol的fontColor默认值，normalFontColor: [$r('sys.color.ohos_id_color_primary')]、activatedFontColor: [$r('sys.color.ohos_id_color_text_primary_contrary')]。fontColor默认值为16。

4.prefixIcon的fillColor默认值：$r('sys.color.ohos_id_color_secondary')，suffixIcon的fillColor默认值：$r('sys.color.ohos_id_color_primary')。fillColor对颜色的解析与Image组件保持一致。

5.prefixIcon的activatedFillColor默认值：$r('sys.color.ohos_id_color_text_primary_contrary')，suffixIcon的activatedFillColor默认值：$r('sys.color.ohos_id_color_text_primary_contrary')。activatedFillColor对颜色的解析与Image组件保持一致。

ChipSize

ChipSize是chip可指定的尺寸类型，如普通型Chip。

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

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

名称	值	描述
NORMAL	"NORMAL"	normal尺寸操作块。
SMALL	"SMALL"	small尺寸操作块。

IconCommonOptions

IconCommonOptions定义图标的共通属性。

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

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

名称	类型	必填	说明
src	ResourceStr	是	图标图片或图片地址引用。
size	SizeOptions	否	图标大小，不支持百分比。默认值：{width: 16,height: 16}
fillColor	ResourceColor	否	图标填充颜色。
activatedFillColor12+	ResourceColor	否	操作块激活时图标填充颜色。

说明

仅在图片格式为svg时，fillColor和activatedFillColor生效。

PrefixIconOptions

PrefixIconOptions定义前缀图标的属性。

继承于IconCommonOptions。

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

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

SuffixIconOptions

SuffixIconOptions定义后缀图标的属性。

继承于IconCommonOptions。

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

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

名称	类型	必填	说明
action	() => void	否	后缀图标设定事件。

ChipSymbolGlyphOptions12+

ChipSymbolGlyphOptions定义前缀图标和后缀图标的属性。

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

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

名称	类型	必填	说明
normal	SymbolGlyphModifier	否	图标设定事件。
activated	SymbolGlyphModifier	否	激活时图标设定事件。

说明

不支持通过symbolEffect修改动效类型和effectStrategy设置动效。

LabelOptions

LabelOptions定义文本的属性。

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

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

名称	类型	必填	说明
text	string	是	文本文字内容。
fontSize	Dimension	否	文字字号，不支持百分比。默认值：$r('sys.float.ohos_id_text_size_button2')
fontColor	ResourceColor	否	文字颜色。默认值：$r('sys.color.ohos_id_color_text_primary')
activatedFontColor12+	ResourceColor	否	操作块激活时的文字颜色。默认值：$r('sys.color.ohos_id_color_text_primary_contrary')
fontFamily	string	否	文字字体。默认值："HarmonyOS Sans"
labelMargin	LabelMarginOptions	否	文本与左右侧图标之间间距。
localizedLabelMargin12+	LocalizedLabelMarginOptions	否	本地化文本与左右侧图标之间间距。默认值：{ start: LengthMetrics.vp(6), end: LengthMetrics.vp(6) }

LabelMarginOptions

LabelMarginOptions定义文本与左右侧图标之间间距。

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

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

名称	类型	必填	说明
left	Dimension	否	文本与左侧图标之间间距，不支持百分比。
right	Dimension	否	文本与右侧图标之间间距，不支持百分比。

LocalizedLabelMarginOptions12+

LocalizedLabelMarginOptions定义本地化文本与左右侧图标之间间距。

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

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

名称	类型	必填	说明
start	LengthMetrics	否	文本与左侧图标之间间距，不支持百分比。
end	LengthMetrics	否	文本与右侧图标之间间距，不支持百分比。

示例

示例1（自定义后缀图标）

该示例通过配置suffixIcon实现自定义操作块的后缀图标。

import { Chip, ChipSize } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    Column({ space: 10 }) {
      Chip({
        prefixIcon: {
          src: $r('app.media.chips'),
          size: { width: 16, height: 16 },
          fillColor: Color.Red
        },
        label: {
          text: "操作块",
          fontSize: 12,
          fontColor: Color.Blue,
          fontFamily: "HarmonyOS Sans",
          labelMargin: { left: 20, right: 30 }
        },
        suffixIcon: {
          src: $r('app.media.close'),
          size: { width: 16, height: 16 },
          fillColor: Color.Red
        },
        size: ChipSize.NORMAL,
        allowClose: false,
        enabled: true,
        backgroundColor: $r('sys.color.ohos_id_color_button_normal'),
        borderRadius: $r('sys.float.ohos_id_corner_radius_button')
      })
    }
  }
}

示例2（设置默认后缀图标）

该示例通过配置allowClose为true显示后缀删除图标。

import { Chip, ChipSize } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    Column({ space: 10 }) {
      Chip({
        prefixIcon: {
          src: $r('app.media.chips'),
          size: { width: 16, height: 16 },
          fillColor: Color.Blue
        },
        label: {
          text: "操作块",
          fontSize: 12,
          fontColor: Color.Blue,
          fontFamily: "HarmonyOS Sans",
          labelMargin: { left: 20, right: 30 }
        },
        size: ChipSize.NORMAL,
        allowClose: true,
        enabled: true,
        backgroundColor: $r('sys.color.ohos_id_color_button_normal'),
        borderRadius: $r('sys.float.ohos_id_corner_radius_button')
      })
    }
  }
}

示例3（不显示后缀图标）

该示例通过配置allowClose为false不显示后缀删除图标。

import { Chip, ChipSize } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    Column({ space: 10 }) {
      Chip({
        prefixIcon: {
          src: $r('app.media.chips'),
          size: { width: 16, height: 16 },
          fillColor: Color.Blue
        },
        label: {
          text: "操作块",
          fontSize: 12,
          fontColor: Color.Blue,
          fontFamily: "HarmonyOS Sans",
          labelMargin: { left: 20, right: 30 }
        },
        size: ChipSize.SMALL,
        allowClose: false,
        enabled: true,
        backgroundColor: $r('sys.color.ohos_id_color_button_normal'),
        borderRadius: $r('sys.float.ohos_id_corner_radius_button'),
        onClose:()=>{
          console.log("chip on close")
      }
      })
    }
  }
}

示例4（激活态操作块）

该示例通过配置activated实现激活态操作块。

import { Chip, ChipSize } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  @State isActivated: boolean = false

  build() {
    Column({ space: 10 }) {
      Chip({
        prefixIcon: {
          src: $r('app.media.chips'),
          size: { width: 16, height: 16 },
          fillColor: Color.Blue,
          activatedFillColor: $r('sys.color.ohos_id_color_text_primary_contrary')
        },
        label: {
          text: "操作块",
          fontSize: 12,
          fontColor: Color.Blue,
          activatedFontColor: $r('sys.color.ohos_id_color_text_primary_contrary'),
          fontFamily: "HarmonyOS Sans",
          labelMargin: { left: 20, right: 30 }
        },
        size: ChipSize.NORMAL,
        allowClose: true,
        enabled: true,
        activated: this.isActivated,
        backgroundColor: $r('sys.color.ohos_id_color_button_normal'),
        activatedBackgroundColor: $r('sys.color.ohos_id_color_emphasize'),
        borderRadius: $r('sys.float.ohos_id_corner_radius_button'),
        onClose:()=>{
          console.log("chip on close")
        },
        onClicked:()=>{
          console.log("chip on clicked")
        }
      })

      Button('改变激活状态').onClick(()=>{
        this.isActivated = !this.isActivated
      })
    }
  }
}

示例5（设置symbol类型图标）

Chip组件的前缀、后缀图标使用symbol类型资源展示。

import { Chip, ChipSize, SymbolGlyphModifier } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  @State isActivated: boolean = false

  build() {
    Column({ space: 10 }) {
      Chip({
        prefixIcon: {
          src: $r('app.media.chips'),
          size: { width: 16, height: 16 },
          fillColor: Color.Blue,
          activatedFillColor: $r('sys.color.ohos_id_color_text_primary_contrary')
        },
        prefixSymbol: {
          normal: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontSize(16).fontColor([Color.Green]),
          activated: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontSize(16).fontColor([Color.Red]),
        },
        label: {
          text: "操作块",
          fontSize: 12,
          fontColor: Color.Blue,
          activatedFontColor: $r('sys.color.ohos_id_color_text_primary_contrary'),
          fontFamily: "HarmonyOS Sans",
          labelMargin: { left: 20, right: 30 },
        },
        size: ChipSize.NORMAL,
        allowClose: true,
        enabled: true,
        activated: this.isActivated,
        backgroundColor: $r('sys.color.ohos_id_color_button_normal'),
        activatedBackgroundColor: $r('sys.color.ohos_id_color_emphasize'),
        borderRadius: $r('sys.float.ohos_id_corner_radius_button'),
        onClose:()=>{
          console.log("chip on close")
        },
        onClicked:()=>{
          console.log("chip on clicked")
        }
      })

      Button('改变激活状态').onClick(()=>{
        this.isActivated = !this.isActivated
      })
    }
  }
}

示例6（设置镜像效果）

该示例通过配置direction实现Chip布局镜像化展示。

import { Chip, ChipSize,LengthMetrics } from '@kit.ArkUI';

@Entry
@Component
struct ChipPage {

  build() {
    Column() {
      Chip({
        direction: Direction.Rtl,
        prefixIcon: {
          src: $r('app.media.chips'),
          size: { width: 16, height: 16 },
          fillColor: Color.Red,
        },
        label: {
          text: "操作块",
          fontSize: 12,
          fontColor: Color.Blue,
          fontFamily: "HarmonyOS Sans",
          localizedLabelMargin: { start: LengthMetrics.vp(20), end: LengthMetrics.vp(20) },
        },
        suffixIcon: {
          src: $r('app.media.close'),
          size: { width: 16, height: 16 },
          fillColor: Color.Red,
        },
        size: ChipSize.NORMAL,
        allowClose: false,
        enabled: true,
        backgroundColor: $r('sys.color.ohos_id_color_button_normal'),
        borderRadius: $r('sys.float.ohos_id_corner_radius_button')
      })
    }.justifyContent(FlexAlign.Center)
    .width('100%')
    .height('100%')
  }
}