Inter-component Communication and Events

Inter-component Communication

The following methods are used for communication between components.

  • WXML data binding: This is used by a parent component to set data for the specified property of a child component. Only JSON-compatible data is supported (from base library version 2.0.9 and later, functions can also be included in the data). For more information, see Component Template and Style.
  • Event: This is used by a child component to send any type of data to a parent component.
  • If the two methods above cannot meet your needs, the parent component can also get the instance objects of the child component via the this.selectComponent method. This allows you to directly access any component data or method.

Monitoring Events

The event system is one of the methods of communication between components. Custom components can trigger any events, and pages that references the components can monitor these events. For the basic concept and usage of events, see Events.

Customer component events are monitored in the same way as with basic component events:

Code example:

<!-- The "onMyEvent" method is called when the custom component triggers "myevent" -->
<component-tag-name bindmyevent="onMyEvent" />
<!-- Or write it like this -->
<component-tag-name bind:myevent="onMyEvent" />
Page({
  onMyEvent: function(e){
    e.detail // The detail object provided when the custom component triggers an event
  }
})

Triggering Events

When a custom component triggers an event, the triggerEvent method should be used to specify the event name, detail object, and event options:

Code example:

Preview with Developer Tool

<!-- In the custom component -->
<button bindtap="onTap">Click this button to trigger the "myevent" event</button>
Component({
  properties: {},
  methods: {
    onTap: function(){
      var myEventDetail = {} // detail object, provided to the event monitoring function
      var myEventOption = {} // Event triggering options
      this.triggerEvent('myevent', myEventDetail, myEventOption)
    }
  }
})

Event triggering options include:

Option Type Required Default Description
bubbles Boolean No false Indicates whether the event is a bubbling event
composed Boolean No false Indicates whether the event can cross component boundaries. If it is false, the event is only triggered in the node tree of the referenced component and will not enter other components.
capturePhase Boolean No false Indicates whether the event has a capture phase

For more information on bubbling and capture phase, see Events.

Code example:

Preview with Developer Tool

// Page page.wxml
<another-component bindcustomevent="pageEventListener1">
  <my-component bindcustomevent="pageEventListener2"></my-component>
</another-component>
// Component another-component.wxml
<view bindcustomevent="anotherEventListener">
  <slot />
</view>
// Component my-component.wxml
<view bindcustomevent="myEventListener">
  <slot />
</view>
// Component my-component.js
Component({
  methods: {
    onTap: function(){
      this.triggerEvent('customevent', {}) // Only pageEventListener2 is triggered
      this.triggerEvent('customevent', {}, { bubbles: true }) // pageEventListener2 and pageEventListener1 are triggered in sequence
      this.triggerEvent('customevent', {}, { bubbles: true, composed: true }) // pageEventListener2, anotherEventListener, and pageEventListener1 are triggered in sequence
    }
  }
})