分类： 指南

不同的组件之间常常需要有逻辑上的交互。组件框架提供了多种组件间交互的方式。

父组件与子组件间的通信

两个有引用与被引用关系的组件，通常可以称为父组件和子组件。父组件通过 usingComponents 引用子组件，并在 WXML 中使用子组件的节点。

• 如果父组件想要传递数据给子组件、触发子组件的特定逻辑，最佳的方式是通过 组件属性 来传递。
• 如果子组件想要传递数据给父组件、触发父组件的特定逻辑，最佳的方式是通过 事件系统 来传递。
• 如果想要在父组件和子组件之间同步数据，可以通过 双向绑定 来同步。

slot 也可以用于向 slot 内容节点树中传递数据，请参考 动态 slot 。

同一个 Shadow 树内节点之间的通信

在同一个 Shadow 树内，节点之间有时也需要有逻辑交互。

例如，想要自行实现 <my-form> 和 <my-button> 组件，它们是被页面这样使用的：

<!-- 页面的 WXML -->
<my-form>
  <my-button> Submit </my-button>
</my-form>

在 <my-button> 被点击时，需要触发在 Shadow 树上的 <my-form> 组件的提交行为。

这种情况下就需要使用 组件间关系 来实现。

直接组件实例访问

有时，上述方式都不够灵活、难以满足复杂的组件交互要求。此时可以使用 节点树访问 的方式，直接获得想要的组件实例 this。

不过，这种方式如果不当使用，容易导致组件间过度耦合，因此不优先推荐。如果需要使用，建议配合 trait behaviors 来进行组件间逻辑解耦。

事件处理函数的第一个参数是一个事件对象。

所有事件对象都具有以下属性：

触摸和点击类事件额外具有以下属性：

type

代表事件的类型。

timeStamp

一个时间戳，表示页面打开到触发事件所经过的毫秒数。

target

触发事件的源组件（即冒泡事件的起点）。以点击事件为例，它表示用户最终点击到的那个组件。

currentTarget

事件绑定的当前组件。它指代 bind 或 catch 事件绑定所在的那个组件。

对于非冒泡事件，currentTarget 和 target 相同。

在实践中，大多数情况下使用 currentTarget 更符合预期。

事件节点数据

在组件节点上可以附加一些自定义数据。这样，在事件中可以获取这些自定义的节点数据，用于事件的逻辑处理。

有两种方式为节点附件自定义数据：dataset 和 mark。现在更推荐使用 mark。

dataset

对于 dataset，这些自定义数据以 data- 开头，多个单词由连字符 - 连接。这种写法中，连字符写法会转换成驼峰写法，而大写字符会自动转成小写字符。如：

• data-element-type ，最终会呈现为 event.currentTarget.dataset.elementType ；
• data-elementType ，最终会呈现为 event.currentTarget.dataset.elementtype 。

<view data-alpha-beta="1" data-alphaBeta="2" bind:tap="bindViewTap"> DataSet Test </view>

export default Page({
  bindViewTap:function(event){
    event.currentTarget.dataset.alphaBeta === 1 // 会转为驼峰写法
    event.currentTarget.dataset.alphabeta === 2 // 大写会转为小写
  }
})

在 glass-easel 组件框架中，可以使用 data: 写法，这种写法不会进行任何转换，通常更容易理解。

<view data:alphaBeta="1" bind:tap="bindViewTap"> DataSet Test </view>

export default Page({
  bindViewTap:function(event){
    event.currentTarget.dataset.alphaBeta === 1
  }
})

mark

在基础库版本 2.7.1 以上，可以使用 mark 来识别具体触发事件的 target 节点。此外，mark 还可以用于承载一些自定义数据（类似于 dataset）。

当事件触发时，事件冒泡路径上所有的 mark 会被合并，并返回给事件回调函数（即使事件不是冒泡事件，也会有这样的 mark 合并）。这使得 mark 通常比 dataset 更实用。

<view mark:myMark="last" bind:tap="bindViewTap">
  <button mark:anotherMark="leaf" bind:tap="bindButtonTap">按钮</button>
</view>

在上述 WXML 中，如果按钮被点击，将触发 bindViewTap 和 bindButtonTap 两个事件，事件携带的 event.mark 将包含 myMark 和 anotherMark 两项。

export default Page({
  bindViewTap: function(e) {
    e.mark.myMark === "last" // true
    e.mark.anotherMark === "leaf" // true
  }
})

mark 和 dataset 很相似，主要区别在于：mark 会包含从触发事件的节点到根节点上所有的 mark: 属性值；而 dataset 仅包含一个节点的 data- 属性值。

细节注意事项：

• 如果存在同名的 mark ，父节点的 mark 会被子节点覆盖。
• 在自定义组件中接收事件时， mark 不包含自定义组件外的节点的 mark 。
• 不同于 dataset ，节点的 mark 不会做连字符和大小写转换。

touches

touches 是一个数组，每个元素为一个 Touch 对象，表示当前停留在屏幕上的触摸点。

changedTouches 与其类似，但是它包含所有变化的触摸点，包括从无变有（touchstart），位置变化（touchmove），从有变无（touchend、touchcancel）。

Touch 对象内部属性如下：

对于 canvas 组件生成的触摸类事件，Touch 对象还包含以下属性：

detail

表示事件的详细信息，它包含的字段根据事件的不同而不同。

自定义组件在 触发事件 时可以指定这个字段的值。

点击类事件的 detail 带有的 x, y 同 pageX, pageY 代表距离文档左上角的距离。

常用的微信小程序事件绑定类型是 bind 和 catch。它们的区别是，catch 会阻止事件冒泡，可参考 事件 。

在事件绑定中使用数据绑定

在事件绑定中，可以使用数据绑定来动态指定事件处理函数。

<view bind:tap="{{ handler }}">Click me</view>

此时，this.data.handler 应当是一个字符串，表示事件处理方法函数名。如果它是个空字符串，则这个绑定会失效：可以利用这个特性来暂时禁用一些事件。

互斥事件绑定

自基础库版本 2.8.2 起，除 bind 和 catch 外，还可以使用 mut-bind 来绑定事件。一个 mut-bind 触发后，如果事件冒泡到其他节点上，其他节点上的 mut-bind 绑定函数不会被触发，但 bind 绑定函数和 catch 绑定函数依旧会被触发。

换而言之，所有 mut-bind 是“互斥”的，只会有其中一个绑定函数被触发。同时，它完全不影响 bind 和 catch 的绑定效果。

例如在下边这个例子中，点击 inner view 会先后调用 handleTap3 和 handleTap2 ，点击 middle view 会调用 handleTap2 和 handleTap1 。

<view id="outer" mut-bind:tap="handleTap1">
  outer view
  <view id="middle" bind:tap="handleTap2">
    middle view
    <view id="inner" mut-bind:tap="handleTap3">
      inner view
    </view>
  </view>
</view>

事件的捕获阶段

自基础库版本 1.5.0 起， 触摸与点击事件 支持捕获阶段。捕获阶段位于冒泡阶段之前，且在捕获阶段中，事件到达节点的顺序与冒泡阶段恰好相反。需要在捕获阶段监听事件时，可以采用 capture-bind、capture-catch 关键字，后者将中断捕获阶段和取消冒泡阶段。

在下面的代码中，点击 inner view 会先后调用 handleTap2、handleTap4、handleTap3、handleTap1。

<view id="outer" bind:touchstart="handleTap1" capture-bind:touchstart="handleTap2">
  outer view
  <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">
    inner view
  </view>
</view>

如果将上面代码中的第一个 capture-bind 改为 capture-catch，将只触发 handleTap2。

<view id="outer" bind:touchstart="handleTap1" capture-catch:touchstart="handleTap2">
  outer view
  <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">
    inner view
  </view>
</view>

事件系统是组件间通信的主要方式之一。组件可以触发任意的事件，组件的使用者可以监听这些事件。

关于事件的基本概念和用法，参见 事件 。

监听事件

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

<component-tag-name bind:myevent="onMyEvent" />

export default Page({
  onMyEvent: function(e){
    e.detail // 自定义组件触发事件时提供的 detail 对象
  }
})

触发事件

自定义组件触发事件时，需要使用 triggerEvent 方法，指定事件名、detail 对象和事件选项，例如：

<button bind:tap="onTap"> 点击这个按钮将触发 myevent 事件 </button>

export default Component({
  properties: {},
  methods: {
    onTap: function(){
      const myEventDetail = {} // detail对象，提供给事件监听函数
      const myEventOption = {} // 触发事件的选项
      this.triggerEvent('myevent', myEventDetail, myEventOption)
    }
  }
})

触发事件的选项包括：

关于 bubbles 和 composed，可以参考下面这个例子。

<!-- 页面 page.wxml -->
<another-component bind:customevent="pageEventListener1">
  <my-component bind:customevent="pageEventListener2"></my-component>
</another-component>

<!-- 组件 another-component.wxml -->
<view bind:customevent="anotherEventListener">
  <slot />
</view>

<!-- 组件 my-component.wxml -->
<view bind:customevent="myEventListener">
  <slot />
</view>

// 组件 my-component.js
export default Component({
  methods: {
    onTap: function(){
      // 不冒泡
      // （只会触发 pageEventListener2）
      this.triggerEvent('customevent', {})

      // 在 Shadow 树上冒泡
      // （会依次触发 pageEventListener2、pageEventListener1）
      this.triggerEvent('customevent', {}, { bubbles: true })

      // 在 Composed 树上冒泡
      // （会依次触发 pageEventListener2、anotherEventListener、pageEventListener1）
      this.triggerEvent('customevent', {}, { bubbles: true, composed: true })
    }
  }
})

在独立任务中触发事件

triggerEvent 会同步触发事件。

有时候这会导致一些问题，例如，在属性 observer 或数据监听器中调用，可能会导致 递归更新问题 。此时，应该在一个独立的任务里触发事件，例如：

export default Component({
  properties: {
    foo: String,
  },
  observers: {
    foo() {
      // 如果直接在数据监听器中触发事件，可能会导致递归更新问题
      // 此时，可使用 nextTick 来在独立任务中触发事件
      wx.nextTick(() => {
        this.triggerEvent('customevent', {})
      })
    },
  },
})

基础库 2.11.2 开始支持，低版本需做兼容处理。

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

<!-- 页面的 WXML -->
<view style="display: flex">
  <custom-component style="color: blue; flex: 1">蓝色、满宽的</custom-component>
</view>

启用组件节点虚拟化

有时，自定义组件并不希望这个节点本身响应 flex 布局，而是希望自定义组件内部的第一层节点能够响应 flex 布局。还有些时候，自定义组件不希望这个节点本身是一个“普通”可以设置样式的节点。

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

export default Component({
  options: { virtualHost: true },
})

这样，可以将 flex item 放入自定义组件内部：

<!-- 页面的 WXML -->
<view style="display: flex">
  <!-- 如果设置了 virtualHost ，节点上的样式将失效 -->
  <custom-component style="color: blue">不是蓝色的</custom-component>
</view>

<!-- custom-component.wxml -->
<view style="flex: 1"> 满宽的 </view>

保留 class 和 style 能力

对于虚拟的组件节点，它的 class style 和动画将不再生效，但仍然可以：

• 将 style 定义成属性来获取 style 上设置的值；
• 将 class 定义成 外部样式类 使得自定义组件 WXML 可以使用 class。

export default Component()
  .options({ virtualHost: true })
  .property('style', String)
  .externalClasses(['class'])
  .register()

在组件样式隔离的前提下，有些组件希望接受组件使用者传入的样式类。

外部样式类

自基础库版本 1.9.90 起，可以用 externalClasses 定义若干个外部样式类。

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

/* foo-component.js */
export default Component({
  externalClasses: ['my-class'],
})

<!-- foo-component.wxml -->
<foo-component class="my-class">这段文本的颜色受组件引用者的 class 影响</foo-component>

这样，组件的使用者可以指定这个样式类对应的 class ，就像使用普通属性一样。在基础库版本 2.7.1 之后，可以指定多个对应的 class 。

/* 页面的 WXSS */
.red-text {
  color: red;
}
.large-text {
  font-size: 1.5em;
}

<!-- 页面的 WXML -->
<foo-component my-class="red-text" />
<foo-component my-class="red-text large-text" />

注意：在同一个节点上使用普通样式类和外部样式类时，两个类的优先级是未定义的。可以借助选择器优先级机制来控制两个类的优先级。

多层嵌套传递外部样式类

外部样式类可以多层嵌套传递。例如，定义一个 bar-component 来引用上面的 foo-component：

/* bar-component.js */
export default Component()
  .externalClasses(['bar-class'])
  .register()

<!-- bar-component.wxml -->
<foo-component my-class="bar-class" />

页面在引用 bar-component 时：

<!-- 页面的 WXML -->
<bar-component bar-class="red-text" />

此时 .red-text 会从页面经过 bar-component 最终传递到 foo-component 中。

直接引用父组件的样式

即使启用了样式隔离 isolated，组件仍然可以通过一些特殊语法来使用组件所在页面的样式类或父组件的样式类。

需要注意的是，这会增加组件间的不良耦合，优先推荐使用 外部样式类 来代替。

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

.blue-text {
  color: blue;
}

在这个组件中可以使用 ~ 来引用页面中这个类的样式：

<view class="~blue-text"> 这段文本是蓝色的 </view>

其中的 ~ 表示引用页面中对应名称的样式类。

另外，可以使用 ^ 表示引用父组件中对应名称的样式类；也可以连续使用多个 ^ 来引用祖先组件中的。

考虑到组件间相互影响的问题，组件的样式表写法受到一定限制。

组件选择器限制

在编写组件样式表时，只推荐使用 class 选择器、伪类和伪元素选择器。这样比较利于代码维护，且它们具有更好的性能。

使用其他选择器需要注意：

• 属性选择器（[foo]）不受支持、不会生效；
• ID 选择器（#foo）不推荐使用，仅在使用 Page 构造器构造的页面根组件中生效；
• 子元素选择器（.foo > .bar）只能用于 view 组件与其子节点之间，用于其他组件可能导致非预期的情况；
• 标签名选择器（button）应尽量避免使用，它不受样式隔离限制，对所有组件都会生效；如需使用，应写在 app.wxss 中。

[foo] { } /* 不受支持 */
#foo { } /* 不推荐  */
.foo > .bar { } /* 除非 .foo 是 view 组件节点，否则不一定会生效 */
button { } /* 不推荐 */

组件样式隔离

默认情况下，自定义组件的样式只受到自定义组件 WXSS 样式的影响，即 样式隔离 。这样，可以在自定义组件中使用比较短的 class 名字，无需担心与其他组件的 class 名冲突。

<view class="title">标题</view>

.title {
  font-size: 2em;
}

从基础库版本 2.10.1 开始，可以通过设置 styleIsolation 选项来修改自定义组件样式隔离行为。它支持以下取值：

• isolated 表示启用样式隔离，在自定义组件内外，使用 class 指定的样式将不会相互影响；
• apply-shared 表示页面的样式将影响到自定义组件，但自定义组件的样式不会影响页面；
• shared 表示页面的样式将影响到自定义组件，自定义组件的样式也会影响页面和其他设置了 apply-shared 或 shared 的自定义组件（这个选项在插件的自定义组件中不可用）。

styleIsolation 选项需要在自定义组件 JSON 中设置：

{
  "usingComponents": {},
  "styleIsolation": "isolated"
}

对于 styleIsolation 的默认值：

• 如果组件是 Page 构造器构造的页面根组件，styleIsolation 的默认值为 shared；
• 如果组件路径在 app.json 的 pages 列表中，styleIsolation 的默认值为 shared；
• 在其他组件中，styleIsolation 的默认值为 isolated。

styleIsolation 也可以在 JS 脚本的 options 中配置，但目前已不推荐。

JS 脚本的 options 中也支持 addGlobalClass: true 配置，等价于设置 styleIsolation: apply-shared。目前已不推荐使用这个配置。

host 节点选择器

自基础库 1.7.2 起，通过 :host 选择器，组件可以指定它自身对应节点的默认样式。例如：

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

无论引用者为组件赋予的节点名是什么，:host 选择器都会对这个节点生效。例如：

{
  "usingComponents": {
    "custom": "/path/to/custom-component"
  }
}

<!-- 引用组件的 WXML -->
<custom>这段文本是黄色的</custom>

普通生命周期

当微信小程序组件发生一些关键状态变化的时候，比如被添加到页面中、从页面中移除等，会触发对应的生命周期回调函数。

其中，最重要的生命周期是 attached。它表示组件实例被添加到页面内；对于页面根组件，它表示整个页面创建完成并即将被展示。

Definition 形式的生命周期回调函数：

export default Component({
  lifetimes: {
    // attached 生命周期回调函数
    attached() {
      // 添加到页面时触发
    },
  },

  // 传统写法（不推荐）
  attached() {
    // 添加到页面时触发
  },
})

Chaining 形式的生命周期回调函数：

export default Component()
  .lifetimes('attached', function () {
    // ...
  })
  .register()

目前提供的生命周期回调函数如下表所示。

注意，ready 生命周期不推荐使用。因为它的回调触发可能会非常晚，并可能在组件被移除后才回调。绝大多数情况下，应使用 attached 代替。使用 ready 生命周期时，需要处理以下可能的情况：

• attached 触发后，ready 被触发；
• attached 未触发，仅 ready 被触发；
• attached 和 detached 依次触发后，ready 被触发。

除此以外，还有一些传统的页面生命周期回调函数，可以在页面根组件中使用。页面路由文档中详细说明了部分生命周期的触发时序。

组件所在页面的生命周期

页面生命周期是一类特殊的生命周期。它在某个页面上触发时，会自动广播给所有页面内的所有组件。

注意：自定义 tabBar 的 pageLifetime 不会触发。

Definition 形式的组件所在页面生命周期回调函数：

Component({
  pageLifetimes: {
    show: function () {
      // 页面被展示时触发
    },
  },
})

Chaining 形式的组件所在页面生命周期回调函数：

Component()
  .pageLifetime('show', function () {
    // 页面被展示时触发
  })
  .register()