自定义组件

创建自定义组件
类似于页面，一个自定义组件由 json wxml wxss js 4个文件组成。要编写一个自定义组件，首先需要在 json 文件中进行自定义组件声明（将 component 字段设为 true 可将这一组文件设为自定义组件）：

{
  "component": true
}

同时，还要在 wxml 文件中编写组件模板，在 wxss 文件中加入组件样式，它们的写法与页面的写法类似。

代码示例：

<view class="inner">
  {{innerText}}
</view>
<slot></slot>

/* 这里的样式只应用于这个自定义组件 */

.inner {
  color: red;
}

注意：在组件wxss中不应使用ID选择器、属性选择器和标签名选择器。

在自定义组件的 js 文件中，需要使用 Component() 来注册组件，并提供组件的属性定义、内部数据和自定义方法。

组件的属性值和内部数据将被用于组件 wxml 的渲染，其中，属性值是可由组件外部传入的。

代码示例：

Component({
  properties: {
    // 这里定义了innerText属性，属性值可以在组件使用时指定
    innerText: {
      type: String,
      value: 'default value',
    }
  },
  data: {
    // 这里是一些组件内部数据
    someData: {}
  },
  methods: {
    // 这里是一个自定义方法
    customMethod: function(){}
  }
})

使用自定义组件
使用已注册的自定义组件前，首先要在页面的 json 文件中进行引用声明。此时需要提供每个自定义组件的标签名和对应的自定义组件文件路径：

```bash
{
  "usingComponents": {
    "component-tag-name": "path/to/the/custom/component"
  }
}

这样，在页面的 wxml 中就可以像使用基础组件一样使用自定义组件。节点名即自定义组件的标签名，节点属性即传递给组件的属性值。

代码示例：

<view>
  <!-- 以下是对一个自定义组件的引用 -->
  <component-tag-name inner-text="Some text"></component-tag-name>
</view>
自定义组件的 wxml 节点结构在与数据结合之后，将被插入到引用位置内。

细节注意事项
一些需要注意的细节：

因为 WXML 节点标签名只能是小写字母、中划线和下划线的组合，所以自定义组件的标签名也只能包含这些字符。
自定义组件也是可以引用自定义组件的，引用方法类似于页面引用自定义组件的方式（使用 usingComponents 字段）。
自定义组件和页面所在项目根目录名不能以“wx-”为前缀，否则会报错。
注意，是否在页面文件中使用 usingComponents 会使得页面的 this 对象的原型稍有差异，包括：

使用 usingComponents 页面的原型与不使用时不一致，即 Object.getPrototypeOf(this) 结果不同。
使用 usingComponents 时会多一些方法，如 selectComponent 。
出于性能考虑，使用 usingComponents 时， setData 内容不会被直接深复制，即 this.setData({ field: obj }) 后 this.data.field === obj 。（深复制会在这个值被组件间传递时发生。）
如果页面比较复杂，新增或删除 usingComponents 定义段时建议重新测试一下。

组件模板和样式
类似于页面，自定义组件拥有自己的 wxml 模板和 wxss 样式。

组件模板
组件模板的写法与页面模板相同。组件模板与组件数据结合后生成的节点树，将被插入到组件的引用位置上。

在组件模板中可以提供一个<slot>节点，用于承载组件引用时提供的子节点。

代码示例：

```bash
<!-- 组件模板 -->
<view class="wrapper">
  <view>这里是组件的内部节点</view>
  <slot></slot>
</view>
<!-- 引用组件的页面模板 -->
<view>
  <component-tag-name>
    <!-- 这部分内容将被放置在组件 <slot> 的位置上 -->
    <view>这里是插入到组件slot中的内容</view>
  </component-tag-name>
</view>

注意，在模板中引用到的自定义组件及其对应的节点名需要在 json 文件中显式定义，否则会被当作一个无意义的节点。除此以外，节点名也可以被声明为抽象节点。

模板数据绑定
与普通的 WXML 模板类似，可以使用数据绑定，这样就可以向子组件的属性传递动态数据。

代码示例：

<!-- 引用组件的页面模板 -->
<view>
  <component-tag-name prop-a="{{dataFieldA}}" prop-b="{{dataFieldB}}">
    <!-- 这部分内容将被放置在组件 <slot> 的位置上 -->
    <view>这里是插入到组件slot中的内容</view>
  </component-tag-name>
</view>

在以上例子中，组件的属性 propA 和 propB 将收到页面传递的数据。页面可以通过 setData 来改变绑定的数据字段。

注意：这样的数据绑定只能传递 JSON 兼容数据。自基础库版本 2.0.9 开始，还可以在数据中包含函数（但这些函数不能在 WXML 中直接调用，只能传递给子组件）。

组件 wxml 的 slot
在组件的 wxml 中可以包含 slot 节点，用于承载组件使用者提供的 wxml 结构。

默认情况下，一个组件的 wxml 中只能有一个 slot 。需要使用多 slot 时，可以在组件 js 中声明启用。

Component({
  options: {
    multipleSlots: true // 在组件定义时的选项中启用多slot支持
  },
  properties: { /* ... */ },
  methods: { /* ... */ }
})

此时，可以在这个组件的 wxml 中使用多个 slot ，以不同的 name 来区分。

<!-- 组件模板 -->
<view class="wrapper">
  <slot name="before"></slot>
  <view>这里是组件的内部细节</view>
  <slot name="after"></slot>
</view>

使用时，用 slot 属性来将节点插入到不同的 slot 上。

这里是插入到组件slot name="before"中的内容 这里是插入到组件slot name="after"中的内容 组件样式 组件对应 wxss 文件的样式，只对组件wxml内的节点生效。编写组件样式时，需要注意以下几点：

组件和引用组件的页面不能使用id选择器（#a）、属性选择器（[a]）和标签名选择器，请改用class选择器。
组件和引用组件的页面中使用后代选择器（.a .b）在一些极端情况下会有非预期的表现，如遇，请避免使用。
子元素选择器（.a>.b）只能用于 view 组件与其子节点之间，用于其他组件可能导致非预期的情况。
继承样式，如 font 、 color ，会从组件外继承到组件内。
除继承样式外， app.wxss 中的样式、组件所在页面的的样式对自定义组件无效（除非更改组件样式隔离选项）。
#a { } /* 在组件中不能使用 /
[a] { } / 在组件中不能使用 /
button { } / 在组件中不能使用 /
.a > .b { } / 除非 .a 是 view 组件节点，否则不一定会生效*/
代码示例：

/* 组件 custom-component.wxss */
:host {
color: yellow;
}

这段文本是黄色的
组件样式隔离
默认情况下，自定义组件的样式只受到自定义组件 wxss 的影响。除非以下两种情况：

app.wxss 或页面的 wxss 中使用了标签名选择器（或一些其他特殊选择器）来直接指定样式，这些选择器会影响到页面和全部组件。通常情况下这是不推荐的做法。
指定特殊的样式隔离选项 styleIsolation 。
Component({
options: {
styleIsolation: ‘isolated’
}
})
styleIsolation 选项从基础库版本 2.6.5开始支持。它支持以下取值：

isolated 表示启用样式隔离，在自定义组件内外，使用 class 指定的样式将不会相互影响（一般情况下的默认值）；
apply-shared 表示页面 wxss 样式将影响到自定义组件，但自定义组件 wxss 中指定的样式不会影响页面；
shared 表示页面 wxss 样式将影响到自定义组件，自定义组件 wxss 中指定的样式也会影响页面和其他设置了 apply-shared 或 shared 的自定义组件。（这个选项在插件中不可用。）
使用后两者时，请务必注意组件间样式的相互影响。

如果这个 Component 构造器用于构造页面，则默认值为 shared ，且还有以下几个额外的样式隔离选项可用：

page-isolated 表示在这个页面禁用 app.wxss ，同时，页面的 wxss 不会影响到其他自定义组件；
page-apply-shared 表示在这个页面禁用 app.wxss ，同时，页面 wxss 样式不会影响到其他自定义组件，但设为 shared 的自定义组件会影响到页面；
page-shared 表示在这个页面禁用 app.wxss ，同时，页面 wxss 样式会影响到其他设为 apply-shared 或 shared 的自定义组件，也会受到设为 shared 的自定义组件的影响。
从小程序基础库版本 2.10.1 开始，也可以在页面或自定义组件的 json 文件中配置 styleIsolation （这样就不需在 js 文件的 options 中再配置）。例如：

{
“styleIsolation”: “isolated”
}
此外，小程序基础库版本 2.2.3 以上支持 addGlobalClass 选项，即在 Component 的 options 中设置 addGlobalClass: true 。 这个选项等价于设置 styleIsolation: apply-shared ，但设置了 styleIsolation 选项后这个选项会失效。

代码示例：

/* 组件 custom-component.js */
Component({
options: {
addGlobalClass: true,
}
})

这段文本的颜色由 app.wxss 和页面 wxss 中的样式定义来决定
/* app.wxss */
.red-text {
color: red;
}
外部样式类
基础库 1.9.90 开始支持，低版本需做兼容处理。

有时，组件希望接受外部传入的样式类。此时可以在 Component 中用 externalClasses 定义段定义若干个外部样式类。

这个特性可以用于实现类似于 view 组件的 hover-class 属性：页面可以提供一个样式类，赋予 view 的 hover-class ，这个样式类本身写在页面中而非 view 组件的实现中。

注意：在同一个节点上使用普通样式类和外部样式类时，两个类的优先级是未定义的，因此最好避免这种情况。

代码示例：

/* 组件 custom-component.js */
Component({
externalClasses: [‘my-class’]
})

这段文本的颜色由组件外的 class 决定
这样，组件的使用者可以指定这个样式类对应的 class ，就像使用普通属性一样。在 2.7.1 之后，可以指定多个对应的 class 。

代码示例：

.red-text { color: red; } .large-text { font-size: 1.5em; } 引用页面或父组件的样式 基础库 2.9.2 开始支持，低版本需做兼容处理即使启用了样式隔离 isolated ，组件仍然可以在局部引用组件所在页面的样式或父组件的样式。

例如，如果在页面 wxss 中定义了：

.blue-text {
color: blue;
}
在这个组件中可以使用 ~ 来引用这个类的样式：

这段文本是蓝色的
如果在一个组件的父组件 wxss 中定义了：

.red-text {
color: red;
}
在这个组件中可以使用 ^ 来引用这个类的样式：

这段文本是红色的
也可以连续使用多个 ^ 来引用祖先组件中的样式。

注意：如果组件是比较独立、通用的组件，请优先使用外部样式类的方式，而非直接引用父组件或页面的样式。

虚拟化组件节点
基础库 2.11.2 开始支持，低版本需做兼容处理。

默认情况下，自定义组件本身的那个节点是一个“普通”的节点，使用时可以在这个节点上设置 class style 、动画、 flex 布局等，就如同普通的 view 组件节点一样。

蓝色、满宽的 但有些时候，自定义组件并不希望这个节点本身可以设置样式、响应 flex 布局等，而是希望自定义组件内部的第一层节点能够响应 flex 布局或者样式由自定义组件本身完全决定。

这种情况下，可以将这个自定义组件设置为“虚拟的”：

Component({
options: {
virtualHost: true
},
properties: {
style: { // 定义 style 属性可以拿到 style 属性上设置的值
type: String,
}
},
externalClasses: [‘class’], // 可以将 class 设为 externalClasses
})
这样，可以将 flex 放入自定义组件内：

不是蓝色的 满宽的 需要注意的是，自定义组件节点上的 class style 和动画将不再生效，但仍可以：

将 style 定义成 properties 属性来获取 style 上设置的值；
将 class 定义成 externalClasses 外部样式类使得自定义组件 wxml 可以使用 class 值。
Component 构造器
Component 构造器可用于定义组件，调用 Component 构造器时可以指定组件的属性、数据、方法等。

Component({

behaviors: [],

properties: {
myProperty: { // 属性名
type: String,
value: ‘’
},
myProperty2: String // 简化的定义方式
},

data: {}, // 私有数据，可用于模板渲染

lifetimes: {
// 生命周期函数，可以为函数，或一个在methods段中定义的方法名
attached: function () { },
moved: function () { },
detached: function () { },
},

// 生命周期函数，可以为函数，或一个在methods段中定义的方法名
attached: function () { }, // 此处attached的声明会被lifetimes字段中的声明覆盖
ready: function() { },

pageLifetimes: {
// 组件所在页面的生命周期函数
show: function () { },
hide: function () { },
resize: function () { },
},

methods: {
onMyButtonTap: function(){
this.setData({
// 更新属性和数据的方法与更新页面数据的方法类似
})
},
// 内部方法建议以下划线开头
_myPrivateMethod: function(){
// 这里将 data.A[0].B 设为 ‘myPrivateData’
this.setData({
‘A[0].B’: ‘myPrivateData’
})
},
_propertyChange: function(newVal, oldVal) {

}

}

})
使用 Component 构造器构造页面
事实上，小程序的页面也可以视为自定义组件。因而，页面也可以使用 Component 构造器构造，拥有与普通组件一样的定义段与实例方法。但此时要求对应 json 文件中包含 usingComponents 定义段。

此时，组件的属性可以用于接收页面的参数，如访问页面 /pages/index/index?paramA=123&paramB=xyz ，如果声明有属性 paramA 或 paramB ，则它们会被赋值为 123 或 xyz 。

页面的生命周期方法（即 on 开头的方法），应写在 methods 定义段中。

代码示例：

{
“usingComponents”: {}
}
Component({

properties: {
paramA: Number,
paramB: String,
},

methods: {
onLoad: function() {
this.data.paramA // 页面参数 paramA 的值
this.data.paramB // 页面参数 paramB 的值
}
}

})
使用 Component 构造器来构造页面的一个好处是可以使用 behaviors 来提取所有页面中公用的代码段。

例如，在所有页面被创建和销毁时都要执行同一段代码，就可以把这段代码提取到 behaviors 中。

代码示例：

// page-common-behavior.js
module.exports = Behavior({
attached: function() {
// 页面创建时执行
console.info(‘Page loaded!’)
},
detached: function() {
// 页面销毁时执行
console.info(‘Page unloaded!’)
}
})
// 页面 A
var pageCommonBehavior = require(’./page-common-behavior’)
Component({
behaviors: [pageCommonBehavior],
data: { /* … / },
methods: { / … / },
})
// 页面 B
var pageCommonBehavior = require(’./page-common-behavior’)
Component({
behaviors: [pageCommonBehavior],
data: { / … / },
methods: { / … */ },
})
组件间通信
组件间的基本通信方式有以下几种。

WXML 数据绑定：用于父组件向子组件的指定属性设置数据，仅能设置 JSON 兼容数据（自基础库版本 2.0.9 开始，还可以在数据中包含函数）。具体在 组件模板和样式 章节中介绍。
事件：用于子组件向父组件传递数据，可以传递任意数据。
如果以上两种方式不足以满足需要，父组件还可以通过 this.selectComponent 方法获取子组件实例对象，这样就可以直接访问组件的任意数据和方法。
监听事件
事件系统是组件间通信的主要方式之一。自定义组件可以触发任意的事件，引用组件的页面可以监听这些事件。关于事件的基本概念和用法，参见 事件 。

监听自定义组件事件的方法与监听基础组件事件的方法完全一致：

代码示例：

Page({ onMyEvent: function(e){ e.detail // 自定义组件触发事件时提供的detail对象 } }) 触发事件 自定义组件触发事件时，需要使用 triggerEvent 方法，指定事件名、detail对象和事件选项：

代码示例：

在开发者工具中预览效果

点击这个按钮将触发“myevent”事件
Component({
properties: {},
methods: {
onTap: function(){
var myEventDetail = {} // detail对象，提供给事件监听函数
var myEventOption = {} // 触发事件的选项
this.triggerEvent(‘myevent’, myEventDetail, myEventOption)
}
}
})
触发事件的选项包括：

选项名 类型 是否必填 默认值 描述
bubbles Boolean 否 false 事件是否冒泡
composed Boolean 否 false 事件是否可以穿越组件边界，为false时，事件将只能在引用组件的节点树上触发，不进入其他任何组件内部
capturePhase Boolean 否 false 事件是否拥有捕获阶段
关于冒泡和捕获阶段的概念，请阅读 事件 章节中的相关说明。

代码示例：

在开发者工具中预览效果

// 页面 page.wxml



// 组件 another-component.wxml



// 组件 my-component.wxml



// 组件 my-component.js
Component({
methods: {
onTap: function(){
this.triggerEvent(‘customevent’, {}) // 只会触发 pageEventListener2
this.triggerEvent(‘customevent’, {}, { bubbles: true }) // 会依次触发 pageEventListener2 、 pageEventListener1
this.triggerEvent(‘customevent’, {}, { bubbles: true, composed: true }) // 会依次触发 pageEventListener2 、 anotherEventListener 、 pageEventListener1
}
}
})
获取组件实例
可在父组件里调用 this.selectComponent ，获取子组件的实例对象。

调用时需要传入一个匹配选择器 selector，如：this.selectComponent(".my-component")。

代码示例：

// 父组件
Page({
data: {},
getChildComponent: function () {
const child = this.selectComponent(’.my-component’);
console.log(child)
}
})
在上例中，父组件将会获取 class 为 my-component 的子组件实例对象，即子组件的 this 。

注意 ：默认情况下，小程序与插件之间、不同插件之间的组件将无法通过 selectComponent 得到组件实例（将返回 null）。如果想让一个组件在上述条件下依然能被 selectComponent 返回，可以自定义其返回结果（见下）。

自定义的组件实例获取结果
若需要自定义 selectComponent 返回的数据，可使用内置 behavior: wx://component-export

从基础库版本 2.2.3 开始提供支持。

使用该 behavior 时，自定义组件中的 export 定义段将用于指定组件被 selectComponent 调用时的返回值。

代码示例：

// 自定义组件 my-component 内部
Component({
behaviors: [‘wx://component-export’],
export() {
return { myField: ‘myValue’ }
}
})

// 父组件调用 const child = this.selectComponent('#the-id') // 等于 { myField: 'myValue' } 在上例中，父组件获取 id 为 the-id 的子组件实例的时候，得到的是对象 { myField: 'myValue' } 。

组件生命周期
组件的生命周期，指的是组件自身的一些函数，这些函数在特殊的时间点或遇到一些特殊的框架事件时被自动触发。

其中，最重要的生命周期是 created attached detached ，包含一个组件实例生命流程的最主要时间点。

组件实例刚刚被创建好时， created 生命周期被触发。此时，组件数据 this.data 就是在 Component 构造器中定义的数据 data 。 此时还不能调用 setData 。 通常情况下，这个生命周期只应该用于给组件 this 添加一些自定义属性字段。
在组件完全初始化完毕、进入页面节点树后， attached 生命周期被触发。此时， this.data 已被初始化为组件的当前值。这个生命周期很有用，绝大多数初始化工作可以在这个时机进行。
在组件离开页面节点树后， detached 生命周期被触发。退出一个页面时，如果组件还在页面节点树中，则 detached 会被触发。
定义生命周期方法
生命周期方法可以直接定义在 Component 构造器的第一级参数中。

自小程序基础库版本 2.2.3 起，组件的的生命周期也可以在 lifetimes 字段内进行声明（这是推荐的方式，其优先级最高）。

代码示例：

Component({
lifetimes: {
attached: function() {
// 在组件实例进入页面节点树时执行
},
detached: function() {
// 在组件实例被从页面节点树移除时执行
},
},
// 以下是旧式的定义方式，可以保持对 <2.2.3 版本基础库的兼容
attached: function() {
// 在组件实例进入页面节点树时执行
},
detached: function() {
// 在组件实例被从页面节点树移除时执行
},
// …
})
在 behaviors 中也可以编写生命周期方法，同时不会与其他 behaviors 中的同名生命周期相互覆盖。但要注意，如果一个组件多次直接或间接引用同一个 behavior ，这个 behavior 中的生命周期函数在一个执行时机内只会执行一次。

可用的全部生命周期如下表所示。

生命周期 参数 描述 最低版本
created 无 在组件实例刚刚被创建时执行 1.6.3
attached 无 在组件实例进入页面节点树时执行 1.6.3
ready 无 在组件在视图层布局完成后执行 1.6.3
moved 无 在组件实例被移动到节点树另一个位置时执行 1.6.3
detached 无 在组件实例被从页面节点树移除时执行 1.6.3
error Object Error 每当组件方法抛出错误时执行 2.4.1
组件所在页面的生命周期
还有一些特殊的生命周期，它们并非与组件有很强的关联，但有时组件需要获知，以便组件内部处理。这样的生命周期称为“组件所在页面的生命周期”，在 pageLifetimes 定义段中定义。其中可用的生命周期包括：

生命周期 参数 描述 最低版本
show 无 组件所在的页面被展示时执行 2.2.3
hide 无 组件所在的页面被隐藏时执行 2.2.3
resize Object Size 组件所在的页面尺寸变化时执行 2.4.0
代码示例：

Component({
pageLifetimes: {
show: function() {
// 页面被展示
},
hide: function() {
// 页面被隐藏
},
resize: function(size) {
// 页面尺寸变化
}
}
})
组件间关系
定义和使用组件间关系
有时需要实现这样的组件：

item 1 item 2 这个例子中， custom-ul 和 custom-li 都是自定义组件，它们有相互间的关系，相互间的通信往往比较复杂。此时在组件定义时加入 relations 定义段，可以解决这样的问题。示例：

// path/to/custom-ul.js
Component({
relations: {
‘./custom-li’: {
type: ‘child’, // 关联的目标节点应为子节点
linked: function(target) {
// 每次有custom-li被插入时执行，target是该节点实例对象，触发在该节点attached生命周期之后
},
linkChanged: function(target) {
// 每次有custom-li被移动后执行，target是该节点实例对象，触发在该节点moved生命周期之后
},
unlinked: function(target) {
// 每次有custom-li被移除时执行，target是该节点实例对象，触发在该节点detached生命周期之后
}
}
},
methods: {
_getAllLi: function(){
// 使用getRelationNodes可以获得nodes数组，包含所有已关联的custom-li，且是有序的
var nodes = this.getRelationNodes(‘path/to/custom-li’)
}
},
ready: function(){
this._getAllLi()
}
})
// path/to/custom-li.js
Component({
relations: {
‘./custom-ul’: {
type: ‘parent’, // 关联的目标节点应为父节点
linked: function(target) {
// 每次被插入到custom-ul时执行，target是custom-ul节点实例对象，触发在attached生命周期之后
},
linkChanged: function(target) {
// 每次被移动后执行，target是custom-ul节点实例对象，触发在moved生命周期之后
},
unlinked: function(target) {
// 每次被移除时执行，target是custom-ul节点实例对象，触发在detached生命周期之后
}
}
}
})
注意：必须在两个组件定义中都加入relations定义，否则不会生效。

关联一类组件
有时，需要关联的是一类组件，如：

input submit custom-form 组件想要关联 custom-input 和 custom-submit 两个组件。此时，如果这两个组件都有同一个behavior：

// path/to/custom-form-controls.js
module.exports = Behavior({
// …
})
// path/to/custom-input.js
var customFormControls = require(’./custom-form-controls’)
Component({
behaviors: [customFormControls],
relations: {
‘./custom-form’: {
type: ‘ancestor’, // 关联的目标节点应为祖先节点
}
}
})
// path/to/custom-submit.js
var customFormControls = require(’./custom-form-controls’)
Component({
behaviors: [customFormControls],
relations: {
‘./custom-form’: {
type: ‘ancestor’, // 关联的目标节点应为祖先节点
}
}
})
则在 relations 关系定义中，可使用这个behavior来代替组件路径作为关联的目标节点：

// path/to/custom-form.js
var customFormControls = require(’./custom-form-controls’)
Component({
relations: {
‘customFormControls’: {
type: ‘descendant’, // 关联的目标节点应为子孙节点
target: customFormControls
}
}
})
relations 定义段
relations 定义段包含目标组件路径及其对应选项，可包含的选项见下表。

选项 类型 是否必填 描述
type String 是 目标组件的相对关系，可选的值为 parent 、 child 、 ancestor 、 descendant
linked Function 否 关系生命周期函数，当关系被建立在页面节点树中时触发，触发时机在组件attached生命周期之后
linkChanged Function 否 关系生命周期函数，当关系在页面节点树中发生改变时触发，触发时机在组件moved生命周期之后
unlinked Function 否 关系生命周期函数，当关系脱离页面节点树时触发，触发时机在组件detached生命周期之后
target String 否 如果这一项被设置，则它表示关联的目标节点所应具有的behavior，所有拥有这一behavior的组件节点都会被关联