小程序开发框架 —— 框架接口汇总（三）

Component(config: Object)

注册自定义组件，接受一个 Object 参数，用于描述组件的逻辑交互行为。

// 文件 /components/foo/index.js
Component({
  options: Object,
  properties: Object,
  observers: Object,
  data: Object,
  methods: Object,
  behaviors: Array,
  lifetimes: Object,
  pageLifetimes: Object,
  relations: Array,
});

完整的配置项如上所示，在自定义组件内部可通过 this 关键字访问实例对象。

组件 this 实例

属性

属性	类型	描述
is	String	组件的文件路径
id	String	节点 id
dataset	String	节点 dataset
data	Object	组件数据，包括内部数据和属性值
properties	Object	组件数据，包括内部数据和属性值（与 data 一致）

方法

方法名	参数	描述
setData	Object newData	设置 data 并执行视图层渲染
triggerEvent	String name, Object detail, Object options	触发事件，参见 组件间通信与事件
createSelectorQuery		创建一个 SelectorQuery 对象，选择器选取范围为这个组件实例内
createIntersectionObserver		创建一个 IntersectionObserver 对象，选择器选取范围为这个组件实例内
selectComponent	String selector	使用选择器选择组件实例节点，返回匹配到的第一个组件实例对象
selectAllComponents	String selector	使用选择器选择组件实例节点，返回匹配到的全部组件实例对象组成的数组
selectOwnerComponent		选取当前组件节点所在的组件实例（即组件的引用者），返回它的组件实例对象
getRelationNodes	String relationKey	获取这个关系所对应的所有关联节点，参见组件间关系

options

可声明自定义组件的渲染行为及数据交互等。

属性	类型	必填	描述
pureDataPattern	regexp	否	纯数据字段是一些不用于界面渲染的data 字段，可以用于提升页面更新性能。
styleIsolation	string	否	组件样式隔离配置，可声明当前组件样式的渲染方式。
multipleSlots	boolean	否	启动组件定义多 slot 特性。
addGlobalClass	boolean	否	添加全局样式，等同于 styleIsolation=apply-shared 优先级低于 styleIsolation 配置

styleIsolation 组件样式隔离

从基础库版本 2.0.0 开始支持。它支持以下取值：

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

👉 立即免费领取开发资源，体验涂鸦 MiniApp 小程序开发。  

properties

声明自定义组件的属性配置及数据处理，每一个键值代表一个属性名，使用驼峰写法，通过 type 定义属性值的类型：String Number Boolean Object Array 其一，也可以为 null 表示不限制类型。value 可声明默认值，不设置则值为 null，并可通过 observer() 监听属性值的变化。

Component({
  properties: {
    myName: {
      type: String,
      value: 'smart',
      observer(newValue, oldValue) {
        // do something
      },
    },
  },
});

注意：在 properties 定义段中，属性名采用驼峰写法（myName）；在 tyml 中，指定属性值时则对应使用连字符写法（<tag-name my-name="smart" />）。

tips

多数情况下，属性最好指定一个确切的类型。这样，在 tyml 中以字面量指定属性值时，值可以获得一个确切的类型，如：

<custom-comp min="1" max="5" />

此时，由于自定义组件的对应属性被规定为 Number 类型， min 和 max 会被赋值为 1 和 5 ，而非 "1" 和 "5" ，即：

this.data.min === 1; // true
this.data.max === 5; // true

observers

数据监听器可以用于监听和响应任何属性（properties）和数据 （data）字段的变化。通过定义以属性名、数据名、通配符 * 的函数处理响应。

Component({
  observers: {
    'value1, value2': function (value1, value2) {
      // this.setData 对应数据时触发
    },
    '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];
    },
    'some.field.**': function (field) {
      // 使用 setData 设置 this.data.some.field 本身或其下任何子数据字段时触发
      // （除此以外，使用 setData 设置 this.data.some 也会触发）
      field === this.data.some.field;
    },
    '**': function () {
      // 每次 setData 都触发
    },
  },
});

注意事项

• 数据监听器监听的是 setData 涉及到的数据字段，即使这些数据字段的值没有发生变化，数据监听器依然会被触发。
• 如果在数据监听器函数中使用 setData 设置本身监听的数据字段，可能会导致死循环，需要特别留意。
• 数据监听器和属性的 properties.field.observer 相比，数据监听器更强大且通常具有更好的性能。

data

自定义组件的数据对象和 properties 一同用于组件模板的渲染。

Component({
  properties: {
    name: {
      type: String,
      value: 'smart',
    },
  },
  data: { age: 18 },
});

<view>{{name}}: {{age}}</view>

methods

自定义组件的逻辑交互行为，结合组件实例方法实现响应用户操作、数据变更、事件通信等，在函数内通过 this 可访问组件实例。

Component({
  methods: {
    say() {
      this.setData({ name: 'hello world' });
    },
  },
});

lifetimes

自定义组件的生命周期，可用于响应事件处理。

生命周期	参数	描述
created	无	在组件实例刚刚被创建时执行
attached	无	在组件实例进入页面节点树时执行
ready	无	在组件在视图层布局完成后执行, 节点的查找应在此阶段执行
moved	无	在组件实例被移动到节点树另一个位置时执行
detached	无	在组件实例被从页面节点树移除时执行
error	Object Error	每当组件方法抛出错误时执行

Component({
  lifetimes: {
    attached() {
      // Do something when attached
    },
    ready() {
      // Do something when ready
    },
  },
});

pageLifetimes

自定义组件所在页面的生命周期声明对象，可用于响应事件处理。

生命周期	参数	描述
show	无	组件所在的页面被展示时执行
hide	无	组件所在的页面被隐藏时执行
resize	无	组件所在的页面尺寸变化时执行	2.6.2

externalClasses

组件接受的外部样式类，参见 外部样式类。

👉 立即免费领取开发资源，体验涂鸦 MiniApp 小程序开发。