鸿蒙5.0开发进阶：ArkTS组件-安全控件通用属性

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

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

安全控件通用属性

安全控件的基础属性，用于设置安全控件通用的属性。

说明

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

iconSize

iconSize(value: Dimension): T

设置安全控件上图标的尺寸。

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

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

参数：

参数名	类型	必填	说明
value	Dimension	是	安全控件上图标的尺寸。 默认值：16vp

返回值：

类型	说明
T	返回安全控件的属性。

layoutDirection

layoutDirection(value: SecurityComponentLayoutDirection): T

设置安全控件上图标和文字分布的方向。

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

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

参数：

参数名	类型	必填	说明
value	SecurityComponentLayoutDirection	是	安全控件上图标和文字分布的方向。 默认值：SecurityComponentLayoutDirection.HORIZONTAL

返回值：

类型	说明
T	返回安全控件的属性。

position

position(value: Position): T

设置绝对定位，设置安全控件的左上角相对于父容器左上角的偏移位置。

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

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

参数：

参数名	类型	必填	说明
value	Position	是	安全控件的左上角相对于父容器左上角的偏移位置。 默认值： { x: 0, y: 0 }

返回值：

类型	说明
T	返回安全控件的属性。

markAnchor

markAnchor(value: Position): T

设置安全控件在位置定位时的锚点，以控件左上角作为基准点进行偏移。

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

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

参数：

参数名	类型	必填	说明
value	Position	是	安全控件在位置定位时的锚点，以控件左上角作为基准点进行偏移。通常配合position和offset属性使用，单独使用时，效果类似offset。 默认值： { x: 0, y: 0 }

返回值：

类型	说明
T	返回安全控件的属性。

offset

offset(value: Position | Edges | LocalizedEdges): T

设置安全控件相对于自身布局位置的坐标偏移。

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

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

参数：

参数名	类型	必填	说明
value	Position | Edges12+ | LocalizedEdges12+	是	安全控件相对于自身布局位置的坐标偏移。设置此属性不会影响父容器的布局，仅在绘制过程中调整位置。 默认值： { x: 0, y: 0 }

返回值：

类型	说明
T	返回安全控件的属性。

fontSize

fontSize(value: Dimension): T

设置安全控件上文字的尺寸。

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

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

参数：

参数名	类型	必填	说明
value	Dimension	是	安全控件上文字的尺寸。 默认值：16fp

返回值：

类型	说明
T	返回安全控件的属性。

fontStyle

fontStyle(value: FontStyle): T

设置安全控件上文字的样式。

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

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

参数：

参数名	类型	必填	说明
value	FontStyle	是	安全控件上文字的样式。 默认值：FontStyle.Normal

返回值：

类型	说明
T	返回安全控件的属性。

fontWeight

fontWeight(value: number | FontWeight | string): T

设置安全控件上文字粗细。

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

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

参数：

参数名	类型	必填	说明
value	number | FontWeight | string	是	安全控件上文字粗细。 默认值：FontWeight.Medium

返回值：

类型	说明
T	返回安全控件的属性。

fontFamily

fontFamily(value: string | Resource): T

设置安全控件上文字的字体。

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

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

参数：

参数名	类型	必填	说明
value	string | Resource	是	安全控件上文字的字体。 默认字体：'HarmonyOS Sans'

返回值：

类型	说明
T	返回安全控件的属性。

fontColor

fontColor(value: ResourceColor): T

设置安全控件上文字的颜色。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	安全控件上文字的颜色。 默认值：$r('sys.color.font_on_primary')

返回值：

类型	说明
T	返回安全控件的属性。

iconColor

iconColor(value: ResourceColor): T

设置安全控件上图标的颜色。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	安全控件上图标的颜色。 默认值：$r('sys.color.icon_on_primary')

返回值：

类型	说明
T	返回安全控件的属性。

backgroundColor

backgroundColor(value: ResourceColor): T

设置安全控件的背景颜色。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	安全控件的背景颜色。 默认值：$r('sys.color.icon_emphasize') 安全控件按钮背景色高八位的α值低于0x1a（例如0x1800ff00）时，安全控件按钮背景色高八位的α值会被系统强制调整为0xff。

返回值：

类型	说明
T	返回安全控件的属性。

borderStyle

borderStyle(value: BorderStyle): T

设置安全控件的边框的样式。

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

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

参数：

参数名	类型	必填	说明
value	BorderStyle	是	安全控件的边框的样式。 默认不设置边框样式

返回值：

类型	说明
T	返回安全控件的属性。

borderWidth

borderWidth(value: Dimension): T

设置安全控件的边框的宽度。

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

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

参数：

参数名	类型	必填	说明
value	Dimension	是	安全控件的边框的宽度。 默认不设置边框宽度

返回值：

类型	说明
T	返回安全控件的属性。

borderColor

borderColor(value: ResourceColor): T

设置安全控件的边框的颜色。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	安全控件的边框的颜色。 默认不设置边框颜色

返回值：

类型	说明
T	返回安全控件的属性。

borderRadius

borderRadius(value: Dimension): T

设置安全控件的边框圆角半径。

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

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

参数：

参数名	类型	必填	说明
value	Dimension	是	安全控件的边框圆角半径。

返回值：

类型	说明
T	返回安全控件的属性。

padding

padding(value: Padding | Dimension): T

设置安全控件的内边距。

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

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

参数：

参数名	类型	必填	说明
value	Padding | Dimension	是	安全控件的内边距。 默认值：上下8vp, 左右16vp

返回值：

类型	说明
T	返回安全控件的属性。

textIconSpace

textIconSpace(value: Dimension): T

设置安全控件中图标和文字的间距。

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

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

参数：

参数名	类型	必填	说明
value	Dimension	是	安全控件中图标和文字的间距。 默认值：4vp

返回值：

类型	说明
T	返回安全控件的属性。

width11+

width(value: Length): T

设置安全控件自身的宽度，缺省时将根据元素内容自适配宽度。

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

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

参数：

参数名	类型	必填	说明
value	Length	是	安全控件自身的宽度，缺省时将根据元素内容自适配宽度。若设置宽度小于当前属性组合下允许的最小宽度时，宽度会调整为设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。

返回值：

类型	说明
T	返回安全控件的属性。

height11+

height(value: Length): T

设置安全控件自身的高度，缺省时将根据元素内容自适配高度。

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

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

参数：

参数名	类型	必填	说明
value	Length	是	安全控件自身的高度，缺省时将根据元素内容自适配高度。若设置高度小于当前属性组合下允许的最小高度时，高度不会缩减到设置值，此时高度会大于设置高度，以保证安全控件显示的完整性。

返回值：

类型	说明
T	返回安全控件的属性。

size11+

size(value: SizeOptions): T

设置高宽尺寸，缺省时将根据元素内容自适配高宽尺寸。

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

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

参数：

参数名	类型	必填	说明
value	SizeOptions	是	高宽尺寸，缺省时将根据元素内容自适配高宽尺寸。若设置尺寸小于当前属性组合下允许的最小尺寸时，高度不会缩减到设置值，宽度会调整到设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。

返回值：

类型	说明
T	返回安全控件的属性。

constraintSize11+

constraintSize(value: ConstraintSizeOptions): T

设置约束尺寸，组件布局时，进行尺寸范围限制。

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

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

参数：

参数名	类型	必填	说明
value	ConstraintSizeOptions	是	约束尺寸，组件布局时，进行尺寸范围限制。constraintSize的优先级高于Width和Height。 同width/height一样，若设置尺寸小于当前属性组合下允许的最小尺寸时, 高度不会缩减到设置值，宽度会调整到设置值，此时按钮文本信息会自动换行，以保证安全控件显示的完整性。 默认值： { minWidth: 0, maxWidth: Infinity, minHeight: 0, maxHeight: Infinity }

返回值：

类型	说明
T	返回安全控件的属性。

SecurityComponentLayoutDirection枚举说明

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

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

名称	值	说明
HORIZONTAL	0	安全控件上图标和文字分布的方向为水平排列。
VERTICAL	1	安全控件上图标和文字分布的方向为垂直排列。

示例

说明

为避免控件样式不合法导致授权失败，请开发者先了解安全控件样式的约束与限制。

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Row() {
      Column({space:5}) {
        // 生成一个保存按钮，并设置它的SecurityComponent属性
        SaveButton()
          .fontSize(35)
          .fontColor(Color.White)
          .iconSize(30)
          .layoutDirection(SecurityComponentLayoutDirection.HORIZONTAL)
          .borderWidth(1)
          .borderStyle(BorderStyle.Dashed)
          .borderColor(Color.Blue)
          .borderRadius(20)
          .fontWeight(100)
          .iconColor(Color.White)
          .padding({left:50, top:50, bottom:50, right:50})
          .textIconSpace(20)
          .backgroundColor(0x3282f6)
        SaveButton().size({width:200, height:100})
        SaveButton().constraintSize({maxWidth:60})
      }.width('100%')
    }.height('100%')
  }
}