# Inter-component relations

# Define and use relationships between components

Sometimes you need to implement components such as:

<custom-ul>
  <custom-li> item 1 </custom-li>
  <custom-li> item 2 </custom-li>
</custom-ul>

In this example,custom-ulandcustom liare custom components that are related to each other and often communicate with each other in complex ways.This problem can be solved by adding therelationsdefinition section to the component definition.Examples:

Preview with Developer Tool

// 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生命周期之后
      }
    }
  }
})

Note: Relations definitions must be added to both component definitions, otherwise they will not take effect.

# Linked a class of components

Preview with Developer Tool

Sometimes, what needs to be associated is a class of components, such as:

<custom-form>
  <view>
    input
    <custom-input></custom-input>
  </view>
  <custom-submit> submit </custom-submit>
</custom-form>

The custom-formcomponent wants to associate thecustom-inputand thecustom submitcomponents.At this point, if both components have the same 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', // 关联的目标节点应为祖先节点
    }
  }
})

Then in therelationsrelationship definition, use this behavior instead of the component path as the target node of the association:

// path/to/custom-form.js
var customFormControls = require('./custom-form-controls')
Component({
  relations: {
    'customFormControls': {
      type: 'descendant', // 关联的目标节点应为子孙节点
      target: customFormControls
    }
  }
})

# Relations Definition Segment

The relationsdefinition segment contains the target component path and its corresponding options. The options that can be included are shown in the table below.

to make a choice	type	Is it compulsory?	describe
type	String	yes	The relative relationship of the target components. The optional value is`parent`、`child`、`ancestor`、`descendant`
linked	Function	no	The relationship life periodic function, which is triggered when a relationship is established in the page node tree, after the component's attached life cycle
linkChanged	Function	no	The relationship life periodic function, which is triggered when the relationship changes in the page node tree after the component moved life cycle
unlinked	Function	no	The relationship life periodic function, which is triggered when the relationship leaves the page node tree after the component detached life cycle
target	String	no	If this entry is set, it represents the behavior that the associated target node should have, and all component nodes that have this behavior are associated