HarmonyOS API：自定义组件

joytrian

发布于 2023-3-30 19:53

浏览

0收藏

版本：v3.1 Beta

slot插槽

更新时间: 2023-02-17 09:19

说明

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

默认插槽

自定义组件中通过slot标签来承载父组件中定义的内容，使用slot标签可以更加灵活的控制自定义组件的内容元素，使用方式如下：

<!-- comp.hml -->
<div class="item">  
   <text class="text-style">下面使用父组件定义的内容</text> 
   <slot></slot> 
</div>

引用该自定义组件方式如下：

<!-- xxx.hml --> 
 <element name='comp' src='../../common/component/comp.hml'></element>  
 <div class="container">  
   <comp>
     <text class="text-style">父组件中定义的内容</text> 
   </comp>  
 </div>

具名插槽

当自定义组件中需要使用多个插槽时，可通过对插槽命名的方式进行区分，当填充插槽内容时，通过声明插槽名称，将内容加到对应的插槽中。

<!-- comp.hml -->
<div class="item">  
   <text class="text-style">下面使用父组件定义的内容</text> 
   <slot name="first"></slot>
   <slot name="second"></slot> 
</div>

引用该自定义组件方式如下：

<!-- xxx.hml --> 
 <element name='comp' src='../../common/component/comp.hml'></element>  
 <div class="container">  
   <comp>
     <text class="text-style" slot="second">插入第二个插槽中</text> 
     <text class="text-style" slot="first">插入第一个插槽中</text>
   </comp>  
 </div>

说明

name 和 slot 属性不支持绑定动态数据。

生命周期定义

更新时间: 2023-02-17 09:19

说明

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

我们为自定义组件提供了一系列生命周期回调方法，便于开发者管理自定义组件的内部逻辑。生命周期主要包括：onInit，onAttached，onDetached，onLayoutReady，onDestroy，onShow和onHide。下面我们依次介绍一下各个生命周期回调的时机。

属性	类型	描述	触发时机
onInit	Function	初始化自定义组件	自定义组件初始化生命周期回调，当自定义组件创建时，触发该回调，主要用于自定义组件中必须使用的数据初始化，该回调只会触发一次调用。
onAttached	Function	自定义组件装载	自定义组件被创建后，加入到Page组件树时，触发该回调，该回调触发时，表示组件将被进行显示，该生命周期可用于初始化显示相关数据，通常用于加载图片资源、开始执行动画等场景。
onLayoutReady	Function	自定义组件布局完成	自定义组件插入Page组件树后，将会对自定义组件进行布局计算，调整其内容元素尺寸与位置，当布局计算结束后触发该回调。
onDetached	Function	自定义组件卸载	自定义组件卸载时，触发该回调，常用于停止动画或异步逻辑停止执行的场景。
onDestroy	Function	自定义组件销毁	自定义组件销毁时，触发该回调，常用于资源释放。
onShow	Function	自定义组件Page显示	自定义组件所在Page显示后，触发该回调。
onHide	Function	自定义组件Page隐藏	自定义组件所在Page隐藏后，触发该回调。

示例

<!-- comp.hml -->
<div class="item">  
   <text class="text-style">{{ value }}</text>  
</div>

//comp.js
export default {
  data: {
    value: "组件创建"
  },
  onInit() {
    console.log("组件创建")
  },
  onAttached() {
    this.value = "组件挂载",
    console.log("组件挂载")
  },
  onShow() {
    console.log("Page显示")
  },
  onHide() {
    console.log("Page隐藏")
  }
}

动态创建组件

更新时间: 2023-02-17 09:19

提供在页面中动态添加组件，并为动态添加的组件设置属性与样式的能力。

说明

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

createElement

createElement(tag: string): Element

创建一个组件对象。

参数：

参数名	类型	必填	说明
tag	string	是	组件名称。

返回值：

类型	说明
Element	对应tag名称的组件对象。

let newImage = dom.createElement('image')

setAttribute

setAttribute(name: string, value: string): void

动态设置组件的属性。

参数：

参数名	类型	必填	说明
name	string	是	属性名称。
value	string	是	属性值。

newImage.setAttribute('src', 'common/testImage.jpg')

setStyle

setStyle(name: string, value: string): boolean

动态设置组件的样式。

参数：

参数名	类型	必填	说明
name	string	是	样式名称。
value	string	是	样式值。

返回值：

类型	说明
boolean	设置成功时返回true，失败时返回false。

newImage.setStyle('width', '120px')

addChild

addChild(child: Element): void

将动态创建的组件添加到父组件当中。

参数：

参数名	类型	必填	说明
child	Element	是	组件对象。

newDiv.addChild(newImage)

示例

<!-- xxx.hml -->
<div class="container">
  <div id="parentDiv" class="parent"></div>
  <button onclick="appendDiv" class="btn">动态创建div</button>
  <button onclick="appendImage" class="btn">动态创建image到创建的div中</button>
</div>

/* xxx.css */
.container {
  flex-direction: column;
  align-items: center;
  width: 100%;
}

.parent {
  flex-direction: column;
}

.btn {
  width: 70%;
  height: 60px;
  margin: 15px;
}

// xxx.js
let newDiv = null
let newImage = null

export default {
  appendDiv() {
    let parent = this.$element('parentDiv')
    newDiv = dom.createElement('div')
    newDiv.setStyle('width', '150px')
    newDiv.setStyle('height', '150px')
    newDiv.setStyle('backgroundColor', '#AEEEEE')
    newDiv.setStyle('marginTop', '15px')
    parent.addChild(newDiv)
  },
  appendImage() {
    newImage = dom.createElement('image')
    newImage.setAttribute('src', 'common/testImage.jpg')
    newImage.setStyle('width', '120px')
    newImage.setStyle('height', '120px')
    newDiv.addChild(newImage)
  }
}

数据类型说明

更新时间: 2023-02-17 09:19

长度类型

名称	类型定义	描述
length	string \| number	用于描述尺寸单位，输入为number类型时，使用px单位；输入为string类型时，需要显式指定像素单位，当前支持的像素单位有： - px：逻辑尺寸单位。 - fp⁶⁺：字体尺寸单位，会随系统字体大小设置发生变化，仅支持文本类组件设置相应的字体大小。
percentage	string	百分比尺寸单位，如“50%”。

颜色类型

名称	类型定义	描述
color	string \| 颜色枚举字符串	用于描述颜色信息，JS脚本中不支持颜色枚举格式。字符串格式如下： - 'rgb(255, 255, 255)' - 'rgba(255, 255, 255, 1.0)' - HEX格式：'#rrggbb'，'#aarrggbb' - 枚举格式：'black'，'white'。

表1 当前支持的颜色枚举

枚举名称	对应颜色	颜色
aliceblue	#f0f8ff
antiquewhite	#faebd7
aqua	#00ffff
aquamarine	#7fffd4
azure	#f0ffff
beige	#f5f5dc
bisque	#ffe4c4
black	#000000
blanchedalmond	#ffebcd
blue	#0000ff
blueviolet	#8a2be2
brown	#a52a2a
burlywood	#deB887
cadetblue	#5f9ea0
chartreuse	#7fff00
chocolate	#d2691e
coral	#ff7f50
cornflowerblue	#6495ed
cornsilk	#fff8dc
crimson	#dc143c
cyan	#00ffff
darkblue	#00008b
darkcyan	#008b8b
darkgoldenrod	#b8860b
darkgray	#a9a9a9
darkgreen	#006400
darkgrey	#a9a9a9
darkkhaki	#bdb76b
darkmagenta	#8b008b
darkolivegreen	#556b2f
darkorange	#ff8c00
darkorchid	#9932cc
darkred	#8b0000
darksalmon	#e9967a
darkseagreen	#8fbc8f
darkslateblue	#483d8b
darkslategray	#2f4f4f
darkslategrey	#2f4f4f
darkturquoise	#00ced1
darkviolet	#9400d3
deeppink	#ff1493
deepskyblue	#00bfff
dimgray	#696969
dimgrey	#696969
dodgerblue	#1e90ff
firebrick	#b22222
floralwhite	#fffaf0
forestgreen	#228b22
fuchsia	#ff00ff
gainsboro	#dcdcdc
ghostwhite	#f8f8ff
gold	#ffd700
goldenrod	#daa520
gray	#808080
green	#008000
greenyellow	#adff2f
grey	#808080
honeydew	#f0fff0
hotpink	#ff69b4
indianred	#cd5c5c
indigo	#4b0082
ivory	#fffff0
khaki	#f0e68c
lavender	#e6e6fa
lavenderblush	#fff0f5
lawngreen	#7cfc00
lemonchiffon	#fffacd
lightblue	#add8e6
lightcoral	#f08080
lightcyan	#e0ffff
lightgoldenrodyellow	#fafad2
lightgray	#d3d3d3
lightgreen	#90ee90
lightpink	#ffb6c1
lightsalmon	#ffa07a
lightseagreen	#20b2aa
lightskyblue	#87cefa
lightslategray	#778899
lightslategrey	#778899
lightsteelblue	#b0c4de
lightyellow	#ffffe0
lime	#00ff00
limegreen	#32cd32
linen	#faf0e6
magenta	#ff00ff
maroon	#800000
mediumaquamarine	#66cdaa
mediumblue	#0000cd
mediumorchid	#ba55d3
mediumpurple	#9370db
mediumseagreen	#3cb371
mediumslateblue	#7b68ee
mediumspringgreen	#00fa9a
mediumturquoise	#48d1cc
mediumvioletred	#c71585
midnightblue	#191970
mintcream	#f5fffa
mistyrose	#ffe4e1
moccasin	#ffe4b5
navajowhite	#ffdead
navy	#000080
oldlace	#fdf5e6
olive	#808000
olivedrab	#6b8e23
orange	#ffa500
orangered	#ff4500
orchid	#da70d6
palegoldenrod	#eee8aa
palegreen	#98fb98
paleturquoise	#afeeee
palevioletred	#db7093
papayawhip	#ffefd5
peachpuff	#ffdab9
peru	#cd853f
pink	#ffc0cb
plum	#dda0dd
powderblue	#b0e0e6
purple	#800080
rebeccapurple	#663399
red	#ff0000
rosybrown	#bc8f8f
royalblue	#4169e1
saddlebrown	#8b4513
salmon	#fa8072
sandybrown	#f4a460
seagreen	#2e8b57
seashell	#fff5ee
sienna	#a0522d
silver	#c0c0c0
skyblue	#87ceeb
slateblue	#6a5acd
slategray	#708090
slategrey	#708090
snow	#fffafa
springgreen	#00ff7f
steelblue	#4682b4
tan	#d2b48c
teal	#008080
thistle	#d8Bfd8
tomato	#ff6347
turquoise	#40e0d0
violet	#ee82ee
wheat	#f5deb3
white	#ffffff
whitesmoke	#f5f5f5
yellow	#ffff00
yellowgreen	#9acd32