导航|地址|刷新
自定义组件 | “人民网+”小程序 | 开放平台










“人民网+”小程序|文档中心






指引

开发

数据

设计

运营











# 自定义组件

# 1. 组件模板和样式

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

# 1.1 组件模板

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

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

代码示例

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


注意

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


# 1.2 模板数据绑定

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

代码示例

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

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


注意

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


# 1.3 组件 FXML 的 slot

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

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

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

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

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

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

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

# 1.4 组件样式


组件对应 FTSS 文件的样式，只对组件FXML内的节点生效。编写组件样式时，需要注意以下几点：

组件和引用组件的页面不能使用id选择器（#a）、属性选择器（[a]）和标签名选择器，请改用class选择器。

组件和引用组件的页面中使用后代选择器（.a .b）在一些极端情况下会有非预期的表现，如遇，请避免使用。

子元素选择器（.a>.b）只能用于 view 组件与其子节点之间，用于其他组件可能导致非预期的情况。

继承样式，如 font 、 color ，会从组件外继承到组件内。

除继承样式外， app.ftss 中的样式、组件所在页面的的样式对自定义组件无效（除非更改组件样式隔离选项）。

#a { } /* 在组件中不能使用 */

[a] { } /* 在组件中不能使用 */

button { } /* 在组件中不能使用 */

.a > .b { } /* 除非 .a 是 view 组件节点，否则不一定会生效 */ 除此以外，组件可以指定它所在节点的默认样式，使用 :host 选择器。


代码示例

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

<!-- 页面的 fxml --><custom-component>这段文本是黄色的</custom-component>

# 1.5 组件样式隔离

默认情况下，自定义组件的样式只受到自定义组件 FTSS 的影响。除非以下两种情况：

app.ftss 或页面的 FTSS 中使用了标签名选择器（或一些其他特殊选择器）来直接指定样式，这些选择器会影响到页面和全部组件。通常情况下这是不推荐的做法。

指定特殊的样式隔离选项 styleIsolation 。

Component({options:{styleIsolation:'isolated'}})

styleIsolation 选项从基础库版本 1.1.7 开始支持。它支持以下取值：

isolated 表示启用样式隔离，在自定义组件内外，使用 class 指定的样式将不会相互影响（一般情况下的默认值）；

apply-shared 表示页面 FTSS 样式将影响到自定义组件，但自定义组件 FTSS 中指定的样式不会影响页面；

shared 表示页面 FTSS 样式将影响到自定义组件，自定义组件 FTSS 中指定的样式也会影响页面和其他设置了 apply-shared 或 shared 的自定义组件。 使用后两者时，请务必注意组件间样式的相互影响。​

如果这个 Component 构造器用于构造页面 ，则默认值为 shared。此外，小程序基础库版本 1.1.7 以上支持 addGlobalClass 选项，即在 Component 的 options 中设置 addGlobalClass: true 。

这个选项等价于设置 styleIsolation: apply-shared ，但设置了 styleIsolation 选项后这个选项会失效。

代码示例

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

<!-- 组件 custom-component.fxml --><textclass="red-text">这段文本的颜色由 `app.ftss` 和页面 `ftss` 中的样式定义来决定</text>

/* app.ftss */.red-text{color: red;}

# 1.6 外部样式类

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


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

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


注意

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


代码示例

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

<!-- 组件 custom-component.fxml --><custom-componentclass="my-class">这段文本的颜色由组件外的 class 决定</custom-component>

这样，组件的使用者可以指定这个样式类对应的 class ，就像使用普通属性一样，可以指定多个对应的 class 。

代码示例

<!-- 页面的 fxml --><custom-componentmy-class="red-text large-text"/>

.red-text{color: red;}.large-text{font-size: 1.5em;}

# 2. Component 构造器

Component 构造器可用于定义组件，调用 Component 构造器时可以指定组件的属性、数据、方法等。

详细的参数含义和使用请参考 Component 参考文档。

Component({behaviors:[],properties:{myProperty:{// 属性名type: String,value:''},myProperty2: String // 简化的定义方式},data:{},// 私有数据，可用于模板渲染lifetimes:{// 生命周期函数，可以为函数，或一个在methods段中定义的方法名attached:function(){},detached:function(){},},// 生命周期函数，可以为函数，或一个在methods段中定义的方法名attached:function(){},// 此处attached的声明会被lifetimes字段中的声明覆盖ready:function(){},methods:{onMyButtonTap:function(){this.setData({// 更新属性和数据的方法与更新页面数据的方法类似})},// 内部方法建议以下划线开头_myPrivateMethod:function(){// 这里将 data.A[0].B 设为 'myPrivateData'this.setData({'A[0].B':'myPrivateData'})},_propertyChange:function(newVal, oldVal){}}})

# 2.1 使用 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!')}})// 页面 Avar pageCommonBehavior =require('./page-common-behavior')Component({behaviors:[pageCommonBehavior],data:{/* ... */},methods:{/* ... */},})// 页面 Bvar pageCommonBehavior =require('./page-common-behavior')Component({behaviors:[pageCommonBehavior],data:{/* ... */},methods:{/* ... */},})

# 2.2 组件间通信与事件

# 2.2.1 组件间通信

组件间的基本通信方式有以下几种。

FXML 数据绑定：用于父组件向子组件的指定属性设置数据，仅能设置 JSON 兼容数据（自基础库版本 1.0.0 开始，还可以在数据中包含函数）。

事件：用于子组件向父组件传递数据，可以传递任意数据。

如果以上两种方式不足以满足需要，父组件还可以通过 this.selectComponent 方法获取子组件实例对象，这样就可以直接访问组件的任意数据和方法。

# 2.2.2 监听事件

事件系统是组件间通信的主要方式之一。自定义组件可以触发任意的事件，引用组件的页面可以监听这些事件。

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

代码示例

<!-- 当自定义组件触发“myevent”事件时，调用“onMyEvent”方法 --><component-tag-namebindmyevent="onMyEvent"/><!-- 或者可以写成 --><component-tag-namebind:myevent="onMyEvent"/>

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

# 2.2.3 触发事件

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

<!-- 在自定义组件中 --><buttonbindtap="onTap">点击这个按钮将触发“myevent”事件</button>

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.FXML <another-componentbindcustomevent="pageEventListener1"><my-componentbindcustomevent="pageEventListener2"></my-component></another-component> // 组件 another-component.FXML <viewbindcustomevent="anotherEventListener"><slot/></view> // 组件 my-component.FXML <viewbindcustomevent="myEventListener"><slot/></view>

// 组件 my-component.jsComponent({methods:{onTap:function(){this.triggerEvent('customevent',{})// 只会触发 pageEventListener2this.triggerEvent('customevent',{},{bubbles:true})// 会依次触发 pageEventListener2 、 pageEventListener1this.triggerEvent('customevent',{},{bubbles:true,composed:true})// 会依次触发 pageEventListener2 、 anotherEventListener 、 pageEventListener1}}})

# 2.2.4 获取组件实例

可在父组件里调用 this.selectComponent ，获取子组件的实例对象（插件的自定义组件将返回 null）。

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

// 父组件Page({data:{},getChildComponent:function(){const child =this.selectComponent('.my-component'); console.log(child)}})

在上例中，父组件将会获取 class 为 my-component 的子组件实例对象，即子组件的 this 。

使自定义组件中支持 export 定义段，这个定义段可以用于指定组件被 selectComponent 调用时的返回值。​

代码示例

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

<!-- 使用自定义组件时 --><my-componentid="the-id"/>

// 父组件调用const child =this.selectComponent('#the-id')// 等于 { myField: 'myValue' }

在上例中，父组件获取 id 为 the-id 的子组件实例的时候，得到的是对象 { myField: 'myValue' } 。

# 2.3 组件生命周期

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

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

组件实例刚刚被创建好时， created 生命周期被触发。此时，组件数据 this.data 就是在 Component 构造器中定义的数据 data 。 **此时还不能调用 setData **。 通常情况下，这个生命周期只应该用于给组件 this 添加一些自定义属性字段。

在组件完全初始化完毕、进入页面节点树后， attached 生命周期被触发。此时， this.data 已被初始化为组件的当前值。这个生命周期很有用，绝大多数初始化工作可以在这个时机进行。

在组件离开页面节点树后， detached 生命周期被触发。退出一个页面时，如果组件还在页面节点树中，则 detached 会被触发。

# 2.3.1 定义生命周期方法

生命周期方法可以直接定义在 Component 构造器的第一级参数中。

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

代码示例

Component({lifetimes:{attached:function(){// 在组件实例进入页面节点树时执行},detached:function(){// 在组件实例被从页面节点树移除时执行},},// 以下是旧式的定义方式，可以保持对 <1.0.2 版本基础库的兼容attached:function(){// 在组件实例进入页面节点树时执行},detached:function(){// 在组件实例被从页面节点树移除时执行},// ...})

在 behaviors 中也可以编写生命周期方法，同时不会与其他 behaviors 中的同名生命周期相互覆盖。但要注意，如果一个组件多次直接或间接引用同一个 behavior ，这个 behavior 中的生命周期函数在一个执行时机内只会执行一次。​

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

生命周期	参数	描述	最低版本
created	无	在组件实例刚刚被创建时执行	1.0.0
attached	无	在组件实例进入页面节点树时执行	1.0.0
ready	无	在组件在视图层布局完成后执行	1.0.0
detached	无	在组件实例被从页面节点树移除时执行	1.0.0
error	Object Error	每当组件方法抛出错误时执行	2.1.7

# 2.4 behaviors

behaviors 是用于组件间代码共享的特性，类似于一些编程语言中的 “mixins” 或 “traits”。

每个 behavior 可以包含一组属性、数据、生命周期函数和方法。组件引用它时，它的属性、数据和方法会被合并到组件中，生命周期函数也会在对应时机被调用。 每个组件可以引用多个 behavior ，behavior 也可以引用其它 behavior 。

# 2.4.1 组件中使用

组件引用时，在 behaviors 定义段中将它们逐个列出即可。​

代码示例

// my-behavior.js module.exports =Behavior({behaviors:[],properties:{myBehaviorProperty:{type: String }},data:{myBehaviorData:'my-behavior-data'},created:function(){ console.log('[my-behavior] created')},attached:function(){ console.log('[my-behavior] attached')},ready:function(){ console.log('[my-behavior] ready')},methods:{myBehaviorMethod:function(){ console.log('[my-behavior] log by myBehaviorMehtod')},}})

// my-component.jsvar myBehavior =require('my-behavior')Component({behaviors:[myBehavior],properties:{myProperty:{type: String }},data:{myData:'my-component-data'},created:function(){ console.log('[my-component] created')},attached:function(){ console.log('[my-component] attached')},ready:function(){ console.log('[my-component] ready')},methods:{myMethod:function(){ console.log('[my-component] log by myMethod')},}})

在上例中， my-component 组件定义中加入了 my-behavior，而 my-behavior 结构为：

属性：myBehaviorProperty

数据字段：myBehaviorData

方法：myBehaviorMethod

生命周期函数：attached、created、ready

这将使 my-component 最终结构为：

属性：myBehaviorProperty、myProperty

数据字段：myBehaviorData、myData

方法：myBehaviorMethod、myMethod

生命周期函数：attached、created、ready

当组件触发生命周期时，上例生命周期函数执行顺序为：

[my-behavior] created

[my-component] created

[my-behavior] attached

[my-component] attached

[my-behavior] ready

[my-component] ready

详细规则参考 同名字段的覆盖和组合规则。

# 2.4.2 同名字段的覆盖和组合规则

组件和它引用的 behavior 中可以包含同名的字段，对这些字段的处理方法如下：

如果有同名的属性 (properties) 或方法 (methods)：
若组件本身有这个属性或方法，则组件的属性或方法会覆盖 behavior 中的同名属性或方法；

若组件本身无这个属性或方法，则在组件的 behaviors 字段中定义靠后的 behavior 的属性或方法会覆盖靠前的同名属性或方法；

在 2 的基础上，若存在嵌套引用 behavior 的情况，则规则为：父 behavior 覆盖 子 behavior 中的同名属性或方法。


如果有同名的数据字段 (data)：
若同名的数据字段都是对象类型，会进行对象合并；

其余情况会进行数据覆盖，覆盖规则为：组件 > 父 behavior > 子 behavior 、 靠后的 behavior > 靠前的 behavior。（优先级高的覆盖优先级低的，最大的为优先级最高）


生命周期函数不会相互覆盖，而是在对应触发时机被逐个调用：
对于不同的生命周期函数之间，遵循组件生命周期函数的执行顺序；

对于同种生命周期函数，遵循如下规则：
behavior 优先于组件执行；

子 behavior 优先于 父 behavior 执行；

靠前的 behavior 优先于 靠后的 behavior 执行；


如果同一个 behavior 被一个组件多次引用，它定义的生命周期函数只会被执行一次。


# 2.4.3 内置 behaviors

自定义组件可以通过引用内置的 behavior 来获得内置组件的一些行为。

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

在上例中， wx://form-field 代表一个内置 behavior ，它使得这个自定义组件有类似于表单控件的行为。

内置 behavior 往往会为组件添加一些属性。在没有特殊说明时，组件可以覆盖这些属性来改变它的 type 或添加 observer 。

# wx://form-field

使自定义组件有类似于表单控件的行为。 form 组件可以识别这些自定义组件，并在 submit 事件中返回组件的字段名及其对应字段值。

# wx://form-field-group

使 form 组件可以识别到这个自定义组件内部的所有表单控件。

# wx://form-field-button

使 form 组件可以识别到这个自定义组件内部的 button 。如果自定义组件内部有设置了 form-type 的 button ，它将被组件外的 form 接受。

# wx://component-export

使自定义组件支持 export 定义段。这个定义段可以用于指定组件被 selectComponent 调用时的返回值。

# 2.5 组件间关系

# 2.5.1 定义和使用组件间关系

有时需要实现这样的组件：

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

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

示例代码

// path/to/custom-ul.jsComponent({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.jsComponent({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定义，否则不会生效。


# 2.5.2 关联一类组件

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

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

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

// path/to/custom-form-controls.js module.exports =Behavior({// ...})

// path/to/custom-input.jsvar customFormControls =require('./custom-form-controls')Component({behaviors:[customFormControls],relations:{'./custom-form':{type:'ancestor',// 关联的目标节点应为祖先节点}}})

// path/to/custom-submit.jsvar customFormControls =require('./custom-form-controls')Component({behaviors:[customFormControls],relations:{'./custom-form':{type:'ancestor',// 关联的目标节点应为祖先节点}}})

则在 relations 关系定义中，可使用这个behavior来代替组件路径作为关联的目标节点：

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

# 2.5.3 relations 定义段

relations 定义段包含目标组件路径及其对应选项，可包含的选项见下表。

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

# 2.6 数据监听器

数据监听器可以用于监听和响应任何属性和数据字段的变化。从小程序基础库版本 2.0.11 开始支持。

# 2.6.1 使用数据监听器

有时，在一些数据字段被 setData 设置时，需要执行一些操作。

例如， this.data.sum 永远是 this.data.numberA 与 this.data.numberB 的和。此时，可以使用数据监听器进行如下实现。

Component({attached:function(){this.setData({numberA:1,numberB:2,})},observers:{'numberA, numberB':function(numberA, numberB){// 在 numberA 或者 numberB 被设置时，执行这个函数this.setData({sum: numberA + numberB })}}})

# 2.6.2 监听字段语法

数据监听器支持监听属性或内部数据的变化，可以同时监听多个。一次 setData 最多触发每个监听器一次。

同时，监听器可以监听子数据字段，如下例所示。

Component({observers:{'some.subfield':function(subfield){// 使用 setData 设置 this.data.some.subfield 时触发// （除此以外，使用 setData 设置 this.data.some 也会触发） subfield ===this.data.some.subfield },'arr[12]':function(arr12){// 使用 setData 设置 this.data.arr[12] 时触发// （除此以外，使用 setData 设置 this.data.arr 也会触发） arr12 ===this.data.arr[12]},}})

如果需要监听所有子数据字段的变化，可以使用通配符 ** 。

Component({observers:{'some.field.**':function(field){// 使用 setData 设置 this.data.some.field 本身或其下任何子数据字段时触发// （除此以外，使用 setData 设置 this.data.some 也会触发） field ===this.data.some.field },},attached:function(){// 这样会触发上面的 observerthis.setData({'some.field':{/* ... */}})// 这样也会触发上面的 observerthis.setData({'some.field.xxx':{/* ... */}})// 这样还是会触发上面的 observerthis.setData({'some':{/* ... */}})}})

特别地，仅使用通配符 ** 可以监听全部 setData 。

Component({observers:{'**':function(){// 每次 setData 都触发},},})


提示

数据监听器监听的是 setData 涉及到的数据字段，即使这些数据字段的值没有发生变化，数据监听器依然会被触发。

如果在数据监听器函数中使用 setData 设置本身监听的数据字段，可能会导致死循环，需要特别留意。


# 2.7 纯数据字段

纯数据字段是一些不用于界面渲染的 data 字段，可以用于提升页面更新性能。

# 组件数据中的纯数据字段

有些情况下，某些 data 中的字段（包括 setData 设置的字段）既不会展示在界面上，也不会传递给其他组件，仅仅在当前组件内部使用。

此时，可以指定这样的数据字段为“纯数据字段”，它们将仅仅被记录在 this.data 中，而不参与任何界面渲染过程，这样有助于提升页面更新性能。

指定“纯数据字段”的方法是在 Component 构造器的 options 定义段中指定 pureDataPattern 为一个正则表达式，字段名符合这个正则表达式的字段将成为纯数据字段。

代码示例：

Component({options:{pureDataPattern:/^_/// 指定所有 _ 开头的数据字段为纯数据字段},data:{a:true,// 普通数据字段_b:true,// 纯数据字段},methods:{myMethod(){this.data._b // 纯数据字段可以在 this.data 中获取this.setData({c:true,// 普通数据字段_d:true,// 纯数据字段})}}})

上述组件中的纯数据字段不会被应用到 FXML 上：

<viewwx:if="{{a}}"> 这行会被展示 </view><viewwx:if="{{_b}}"> 这行不会被展示 </view>

# 组件属性中的纯数据字段

属性也可以被指定为纯数据字段（遵循 pureDataPattern 的正则表达式）。

属性中的纯数据字段可以像普通属性一样接收外部传入的属性值，但不能将它直接用于组件自身的 FXML 中。

代码示例：

Component({options:{pureDataPattern:/^_/},properties:{a: Boolean,_b:{type: Boolean,observer(){// 不要这样做！这个 observer 永远不会被触发}},}})

注意：属性中的纯数据字段的属性 observer 永远不会触发！如果想要监听属性值变化，使用 数据监听器 代替。

也可以在页面或自定义组件的 json 文件中配置 pureDataPattern （这样就不需在 js 文件的 options 中再配置）。此时，其值应当写成字符串形式：

{"pureDataPattern":"^_"}

# 使用数据监听器监听纯数据字段

数据监听器 可以用于监听纯数据字段（与普通数据字段一样）。这样，可以通过监听、响应纯数据字段的变化来改变界面。

下面的示例是一个将 JavaScript 时间戳转换为可读时间的自定义组件。

在开发者工具中预览效果

代码示例：

Component({options:{pureDataPattern:/^timestamp$/// 将 timestamp 属性指定为纯数据字段},properties:{timestamp: Number,},observers:{timestamp:function(){// timestamp 被设置时，将它展示为可读时间字符串var timeString =newDate(this.data.timestamp).toLocaleString()this.setData({timeString: timeString })}}})

<view>{{timeString}}</view>

# 2.8 抽象节点

# 在组件中使用抽象节点

有时，自定义组件模板中的一些节点，其对应的自定义组件不是由自定义组件本身确定的，而是自定义组件的调用者确定的。这时可以把这个节点声明为“抽象节点”。

例如，我们现在来实现一个“选框组”（selectable-group）组件，它其中可以放置单选框（custom-radio）或者复选框（custom-checkbox）。这个组件的 fxml 可以这样编写：

代码示例：

<!-- selectable-group.fxml --><viewwx:for="{{labels}}"><label><selectabledisabled="{{false}}"></selectable> {{item}} </label></view>

其中，“selectable”不是任何在 json 文件的 usingComponents 字段中声明的组件，而是一个抽象节点。它需要在 componentGenerics 字段中声明：

{"componentGenerics":{"selectable":true}}

# 使用包含抽象节点的组件

在使用 selectable-group 组件时，必须指定“selectable”具体是哪个组件：

<selectable-groupgeneric:selectable="custom-radio"/>

这样，在生成这个 selectable-group 组件的实例时，“selectable”节点会生成“custom-radio”组件实例。类似地，如果这样使用：

<selectable-groupgeneric:selectable="custom-checkbox"/>

“selectable”节点则会生成“custom-checkbox”组件实例。

注意：上述的 custom-radio 和 custom-checkbox 需要包含在这个 fxml 对应 json 文件的 usingComponents 定义段中。

{"usingComponents":{"custom-radio":"path/to/custom/radio","custom-checkbox":"path/to/custom/checkbox"}}

# 抽象节点的默认组件

抽象节点可以指定一个默认组件，当具体组件未被指定时，将创建默认组件的实例。默认组件可以在 componentGenerics 字段中指定：

{"componentGenerics":{"selectable":{"default":"path/to/default/component"}}}

# 注意事项

节点的 generic 引用 generic:xxx="yyy" 中，值 yyy 只能是静态值，不能包含数据绑定。因而抽象节点特性并不适用于动态决定节点名的场景。

# 2.9 自定义组件扩展

为了更好定制自定义组件的功能，可以使用自定义组件扩展机制

# 扩展后的效果

为了更好的理解扩展后的效果，先举一个例子：

// behavior.js module.exports =Behavior({definitionFilter(defFields){ defFields.data.from ='behavior'},})// component.jsComponent({data:{from:'component'},behaviors:[require('behavior.js')],ready(){ console.log(this.data.from)// 此处会发现输出 behavior 而不是 component}})

通过例子可以发现，自定义组件的扩展其实就是提供了修改自定义组件定义段的能力，上述例子就是修改了自定义组件中的 data 定义段里的内容。

# 使用扩展

Behavior() 构造器提供了新的定义段 definitionFilter ，用于支持自定义组件扩展。 definitionFilter 是一个函数，在被调用时会注入两个参数，第一个参数是使用该 behavior 的 component/behavior 的定义对象，第二个参数是该 behavior 所使用的 behavior 的 definitionFilter 函数列表。

以下举个例子来说明：

// behavior3.js module.exports =Behavior({definitionFilter(defFields, definitionFilterArr){},})// behavior2.js module.exports =Behavior({behaviors:[require('behavior3.js')],definitionFilter(defFields, definitionFilterArr){// definitionFilterArr[0](defFields)},})// behavior1.js module.exports =Behavior({behaviors:[require('behavior2.js')],definitionFilter(defFields, definitionFilterArr){},})// component.jsComponent({behaviors:[require('behavior1.js')],})

上述代码中声明了1个自定义组件和3个 behavior，每个 behavior 都使用了 definitionFilter 定义段。那么按照声明的顺序会有如下事情发生：

简单概括，definitionFilter 函数可以理解为当 A 使用了 B 时，A 声明就会调用 B 的 definitionFilter 函数并传入 A 的定义对象让 B 去过滤。此时如果 B 还使用了 C 和 D ，那么 B 可以自行决定要不要调用 C 和 D 的 definitionFilter 函数去过滤 A 的定义对象。

# 代码示例

下面利用扩展简单实现自定义组件的计算属性功能:

// behavior.js module.exports =Behavior({lifetimes:{created(){this._originalSetData =this.setData // 原始 setDatathis.setData =this._setData // 封装后的 setData}},definitionFilter(defFields){const computed = defFields.computed ||{}const computedKeys = Object.keys(computed)const computedCache ={}// 计算 computedconstcalcComputed=(scope, insertToData)=>{const needUpdate ={}const data = defFields.data = defFields.data ||{}for(let key of computedKeys){const value = computed[key].call(scope)// 计算新值if(computedCache[key]!== value) needUpdate[key]= computedCache[key]= value if(insertToData) data[key]= needUpdate[key]// 直接插入到 data 中，初始化时才需要的操作}return needUpdate }// 重写 setData 方法 defFields.methods = defFields.methods ||{} defFields.methods._setData=function(data, callback){const originalSetData =this._originalSetData // 原始 setDataoriginalSetData.call(this, data, callback)// 做 data 的 setDataconst needUpdate =calcComputed(this)// 计算 computedoriginalSetData.call(this, needUpdate)// 做 computed 的 setData}// 初始化 computedcalcComputed(defFields,true)// 计算 computed}})

在组件中使用：

const beh =require('./behavior.js')Component({behaviors:[beh],data:{a:0,},computed:{b(){returnthis.data.a +100},},methods:{onTap(){this.setData({a:++this.data.a,})}}})

<view>data: {{a}}</view><view>computed: {{b}}</view><buttonbindtap="onTap">click</button>

实现原理很简单，对已有的 setData 进行二次封装，在每次 setData 的时候计算出 computed 里各字段的值，然后设到 data 中，以达到计算属性的效果。

# 2.10 获取更新性能统计信息

如果想要知道 setData 引发界面更新的开销，可以使用更新性能统计信息接口。它将返回每次更新中主要更新步骤发生的时间戳，可以用来大体上估计自定义组件（或页面）更新性能。例如：

Component({attached(){// 调用时机不能早于 attachedthis.setUpdatePerformanceListener({withDataPaths:true},(res)=>{ console.log(res)})}})

setUpdatePerformanceListener 方法接受一个 options 对象和回调函数 listener 作为参数。

其中， options 对象包含以下字段：

字段	类型	说明
withDataPaths	Boolean	是否返回变更的 data 字段信息

listeners 返回携带一个 res 对象，表示一次由 setData 引发的 更新过程 。根据 setData 调用时机的不同，更新过程大体可以分为三类：
…(内容过长已截断)

------
导航页 打开网址