HarmonyOS API：自定义组件

joytrian

发布于 2023-3-29 21:54

浏览

0收藏

版本：v3.1 Beta

自定义组件的基本用法

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

自定义组件是用户根据业务需求，将已有的组件组合，封装成的新组件，可以在工程中多次调用，从而提高代码的可读性。自定义组件通过element引入到宿主页面，使用方法如下：

<element name='comp' src='../../common/component/comp.hml'></element>
<div>
  <comp prop1='xxxx' @child1="bindParentVmMethod"></comp>
</div>1.
2.
3.
4.

结合if-else使用自定义组件的示例，showComp1为true时显示自定义组件comp1，否则显示comp2：

<element name='comp1' src='../../common/component/comp1/comp1.hml'></element>
<element name='comp2' src='../../common/component/comp2/comp2.hml'></element>
<div>
  <comp1 if="{{showComp1}}" prop1='xxxx' @child1="bindParentVmMethodOne"></comp1>
  <comp2 else prop1='xxxx' @child1="bindParentVmMethodTwo"></comp2>
</div>1.
2.
3.
4.
5.
6.

自定义组件的name属性指自定义组件名称(非必填)，组件名称对大小写不敏感，默认使用小写。src属性指自定义组件hml文件路径(必填)，若没有设置name属性，则默认使用hml文件名作为组件名。

自定义事件

父组件中绑定自定义子组件的事件使用(on|@)event-name="bindParentVmMethod"语法，子组件中通过this.$emit('eventName', { params: '传递参数' })触发事件并向上传递参数，父组件执行bindParentVmMethod方法并接收子组件传递的参数。

说明

子组件中使用驼峰命名法命名的事件，在父组件中绑定时需要使用短横线分隔命名形式，例如：@children-event表示绑定子组件的childrenEvent事件。

示例1：无参数传递

子组件comp定义如下：

<!-- comp.hml -->
<div class="item">  
   <text class="text-style" onclick="childClicked">点击这里查看隐藏文本</text> 
   <text class="text-style" if="{{showObj}}">hello world</text> 
</div>1.
2.
3.
4.
5.

/* comp.css */
.item {  
  width: 700px;   
  flex-direction: column;   
  height: 300px;   
  align-items: center;   
  margin-top: 100px;  
} 
.text-style { 
  font-weight: 500; 
  font-family: Courier; 
  font-size: 40px;
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

// comp.js
export default { 
  data: {  
    showObj: false,  
  },  
  childClicked () {  
    this.$emit('eventType1'); 
    this.showObj = !this.showObj;  
  },  
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

引入子组件comp的父组件示例如下：

<!-- xxx.hml --> 
<element name='comp' src='../../common/component/comp.hml'></element>  
<div class="container">  
  <comp @event-type1="textClicked"></comp>  
</div>1.
2.
3.
4.
5.

/* xxx.css */
.container {  
  background-color: #f8f8ff;  
  flex: 1;  
  flex-direction: column;  
  align-content: center; 
} 1.
2.
3.
4.
5.
6.
7.

// xxx.js
export default {    
  textClicked () {} 
}1.
2.
3.
4.

示例2：有参数传递

子组件comp定义如下：

<!-- comp.hml -->
<div class="item">  
   <text class="text-style" onclick="childClicked">点击这里查看隐藏文本</text> 
   <text class="text-style" if="{{ showObj }}">hello world</text> 
</div>1.
2.
3.
4.
5.

// comp.js
export default { 
  childClicked () {
    this.$emit('eventType1', { text: '收到子组件参数' });
    this.showObj = !this.showObj;
  },
}1.
2.
3.
4.
5.
6.
7.

子组件向上传递参数text，父组件接收时通过e.detail来获取该参数：

<!-- xxx.hml -->
<element name='comp' src='../../common/comp/comp.hml'></element>
<div class="container">  
   <text>父组件：{{text}}</text> 
   <comp @event-type1="textClicked"></comp>  
</div>1.
2.
3.
4.
5.
6.

// xxx.js
export default { 
  data: {
    text: '开始',
  },
  textClicked (e) {
    this.text = e.detail.text;
  },
}1.
2.
3.
4.
5.
6.
7.
8.
9.

HarmonyOS API：自定义组件-鸿蒙开发者社区

自定义组件数据

自定义组件的js文件中可以通过声明data、props、computed等字段完成数据的定义、传递与处理，其中props与computed的具体使用请参考数据传递与处理章节。

表1 自定义组件数据

名称	类型	描述
data	Object \| Function	页面的数据模型，类型是对象或者函数，如果类型是函数，返回值必须是对象。属性名不能以$或_开头，不要使用保留字for, if, show, tid。 data与private和public不能重合使用。
props	Array \| Object	props用于组件之间的数据通信，可以通过<tag xxxx='value'>方式传递给组件；props名称必须用小写，不能以$或_开头，不要使用保留字for, if, show, tid。目前props的数据类型不支持Function。
computed	Object	计算属性，用于在读取或设置参数时，进行预先处理，其结果会被缓存。计算属性名不能以$或_开头，不要使用保留字。

数据传递与处理

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

Props

自定义组件可以通过props声明属性，父组件通过设置属性向子组件传递参数，props支持类型包括：String，Number，Boolean，Array，Object，Function。camelCase (驼峰命名法) 的 prop 名，在外部父组件传递参数时需要使用 kebab-case (短横线分隔命名) 形式，即当属性compProp在父组件引用时需要转换为comp-prop。给自定义组件添加props，通过父组件向下传递参数的示例如下：

<!-- comp.hml -->
<div class="item"> 
   <text class="title-style">{{compProp}}</text> 
</div>1.
2.
3.
4.

// comp.js 
export default { 
  props: ['compProp'],
}1.
2.
3.
4.

<!-- xxx.hml -->
<element name='comp' src='../../common/component/comp/comp.hml'></element>
<div class="container"> 
   <comp comp-prop="{{title}}"></comp> 
</div>1.
2.
3.
4.
5.

说明

自定义属性命名时禁止以on、@、on:、grab: 等保留关键字为开头。

添加默认值

子组件可以通过固定值default设置默认值，当父组件没有设置该属性时，将使用其默认值。此情况下props属性必须为对象形式，不能用数组形式，示例如下：

<!-- comp.hml -->
<div class="item"> 
   <text class="title-style">{{title}}</text> 
</div>1.
2.
3.
4.

// comp.js
export default { 
  props: {
    title: {
      default: 'title',
    },
  },
}1.
2.
3.
4.
5.
6.
7.
8.

本示例中加入了一个text组件显示标题，标题的内容是一个自定义属性，显示用户设置的标题内容，当用户没有设置时显示默认值title。在引用该组件时添加该属性的设置：

<!-- xxx.hml -->
<element name='comp' src='../../common/component/comp/comp.hml'></element>
<div class="container"> 
   <comp title="自定义组件"></comp> 
</div>1.
2.
3.
4.
5.

数据单向性

父子组件之间数据的传递是单向的，只能从父组件传递给子组件，子组件不能直接修改父组件传递下来的值，可以将props传入的值用data接收后作为默认值，再对data的值进行修改。

// comp.js
export default { 
  props: ['defaultCount'],
  data() {
    return {
      count: this.defaultCount,
    };
  },
  onClick() {
    this.count = this.count + 1;
  },
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

$watch 感知数据改变

如果需要观察组件中属性变化，可以通过$watch方法增加属性变化回调。使用方法如下：

// comp.js
export default { 
  props: ['title'],
  onInit() {
    this.$watch('title', 'onPropertyChange');
  },
  onPropertyChange(newV, oldV) {
    console.info('title 属性变化 ' + newV + ' ' + oldV);
  },
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

computed

自定义组件中经常需要在读取或设置某个属性时进行预先处理，提高开发效率，此种情况就需要使用computed计算属性。computed字段中可通过设置属性的getter和setter方法在属性读写的时候进行触发，使用方式如下：

// comp.js
export default { 
  props: ['title'],
  data() {
    return {
      objTitle: this.title,
      time: 'Today',
    };
  },
  computed: {
    message() {
      return this.time + ' ' + this.objTitle;
    },
    notice: {
      get() {
        return this.time;
      },
      set(newValue) {
        this.time = newValue;
      },
    },
  },
  onClick() {
    console.info('get click event ' + this.message);
    this.notice = 'Tomorrow';
  },
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.

这里声明的第一个计算属性message默认只有getter函数，message的值会取决于objTitle的值的变化。getter函数只能读取不能改变参数值，例如data中初始化定义的time，当需要赋值给计算属性的时候可以提供一个setter函数，如示例中的notice。

继承样式

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

说明

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

自定义组件具有inherit-class属性，定义如下：

名称	类型	默认值	必填	描述
inherit-class	string	-	否	从父组件继承的class样式，多个class样式之间用空格分隔。

可以通过设置inherit-calss属性来继承父组件的样式。

父组件的hml文件，其中自定义组件comp通过inherit-class属性来指定继承其父组件的样式，即parent-class1和parent-class2：

<!-- xxx.hml -->
<element name='comp' src='../../common/component/comp.hml'></element>

<div class="container">
    <comp inherit-class="parent-class1 parent-class2" ></comp>
</div>1.
2.
3.
4.
5.
6.

父组件的css文件：

/* xxx.css */
.parent-class1 {
    background-color:red;
    border:2px;
}
.parent-class2 {
    background-color:green;
    border:2px;
}1.
2.
3.
4.
5.
6.
7.
8.
9.

自定义组件的hml文件，其中parent-class1和parent-class2是从父组件继承的样式：

<!--comp.hml-->
<div class="item">
    <text class="parent-class1">继承父组件的样式1</text>
    <text class="parent-class2">继承父组件的样式2</text>
</div>1.
2.
3.
4.
5.