behaviors

The behaviors feature is used to share code between components, similar to "mixins" or "traits" in certain programing languages.

A behavior can include a set of properties, data, lifecycle functions, and methods. When referenced by a component, the behavior's properties, data, and methods are merged into the component. Each lifecycle function is also called at the appropriate time. A component can reference more than one behavior and a behavior can reference another behavior.

For specific definitions and usage of the parameters, see the Behavior reference documentation.

Use in Components

When referenced by a component, behaviors are listed in the behaviors definition field.

Code example:

Preview with Developer Tool

// my-component.js
var myBehavior = require('my-behavior')
Component({
  behaviors: [myBehavior],
  properties: {
    myProperty: {
      type: String
    }
  },
  data: {
    myData: {}
  },
  attached: function(){},
  methods: {
    myMethod: function(){}
  }
})

In the above example, my-behavior is added in the my-component component definition, and my-behavior includes a myBehaviorProperty property, a myBehaviorData data field, a myBehaviorMethod method, and an attached lifecycle function. As a result, my-component contains two properties (myBehaviorProperty and myProperty), two data fields (myBehaviorData and myData), and two methods (myBehaviorMethod and myMethod). When the component triggers the attached lifecycle function, it triggers the attached lifecycle functions in both my-behavior and my-component, respectively.

Field Coverage and Combination Rules

Components and the behaviors they referenced can contain fields with the same name. Such fields are processed as follows:

  • If there are properties or methods with the same name, the component's property or method overwrites the property or method of the behavior. If more than one behavior is referenced, the properties and methods of the latter ones in the definition field overwrite those before them.
  • If there are data fields with the same name, fields with object data will be merged, and fields with non-object data will overwrite each other.
  • Lifecycle functions cannot overwrite each other. Instead, they are called in a certain time order. If a behavior is referenced multiple times by a component, the lifecycle function it defines is only executed once.

Built-in Behaviors

Custom components can reference built-in behaviors to get some behaviors of built-in components.

Code example:

Preview with Developer Tool

Component({
  behaviors: ['wx://form-field']
})

In the above example, wx://form-field represents a built-in behavior. It makes the custom component behave like a form control.

A built-in behavior generally adds properties to a component. Unless otherwise specified, components can overwrite these properties to change their type or add an observer.

wx://form-field

This allows custom components to behave as a form control. A form component can identify these custom components and return the field name and its field value of each component in the submit event. Two properties are added to the component.

Property Type Description Minimum Version
name String Field name in the form 1.6.7
value Any Field value in the form 1.6.7

wx://component-export

Preview with Developer Tool

Supported from base library 2.2.3 and later.

This allows custom components to support the export definition field. This definition field can be used to specify the return value when the component is called by selectComponent.

When this definition field is not used, selectComponent returns this for the custom component (null for the plug-in's custom component). When this definition field is used, the function return value of the definition field prevails.

Code sample:

// Customize the internals of the component my-component
Component({
  behaviors: ['wx://component-export'],
  export() {
    return { myField: 'myValue' }
  }
})
<!-- When custom component is used -->
<my-component id="the-id" />
this.selectComponent('#the-id') // Equal to { myField: 'myValue' }