占位组件
收藏
我的收藏

基础库 2.61.0 及以上版本支持，2.61.0 以下和未配置的效果相同

为自定义组件配置占位组件，可以指定该组件不在小程序启动时立即注入，而是等到页面中其他元素渲染完成后才注入。基础库会用占位组件替代组件进行渲染，在该组件注入后再将占位组件替换。

一个自定义组件的占位组件可以是另一个自定义组件或一个内置组件。

配置

页面或自定义组件对应的 JSON 配置中的 componentPlaceholder 字段用于指定占位组件，如：

{
  "usingComponents": {
    "comp-a": "../comp/compA",
    "comp-b": "../comp/compB",
    "comp-c": "../comp/compC"
  },
  "componentPlaceholder": {
    "comp-a": "view",
    "comp-b": "comp-c"
  }
}

该配置表示：

•

组件 comp-a 的占位组件为内置组件 view

•

组件 comp-b 的占位组件为自定义组件 comp-c（其路径在 usingComponents 中配置）

如果配置对应模板如下：

<comp-a>
  <comp-b>text in slot</comp-b>
</comp-a>

在小程序启动时，页面将被渲染为：

<view>
  <comp-c>text in slot</comp-c>
</view>

等到 comp-a comp-b注入完成后才将占位组件替换。

注意事项

当一个组件被指定为占位组件时，为其指定占位组件是无效的。可以理解为如果一个组件需要作为其他组件的占位组件，则它必须在一开始就是可用的；

如果为一个组件指定的占位组件是自定义组件且该自定义组件不存在，占位组件将被降级渲染为 view 组件；

如果被指定了占位组件的组件在其他组件或者页面中使用时已经被注入，那么占位组件不会被渲染。

生命周期

为组件指定占位组件且生效的情况下，该组件会在其所在页面或者组件 onReady/ready 后才实例化并触发生命周期方法，并且该组件 pageLifetimes 中的 show 方法在首次渲染时不会触发。

扩展阅读

ref 获取配置了占位组件的自定义组件实例

// page.ttml
<view>
  <comp tt:ref="refHandler"></comp>
</view>

// page.json
{
  "usingComponents": {
    "comp": "path/to/comp",
    "comp-placeholder": "path/to/comp-placeholder"
  },
  "componentPlaceholder": {
    "comp": "comp-placeholder"
  }
}

// page.js
Page({
  refHandler(instance) {
    // 会调用两次，第一次传入 comp-placeholder 实例，第二次传入 comp 实例
    console.log(instance);
  },
});

关于 ref 能力的基本介绍参考：ref 获取组件实例

当我们为自定义组件comp配置占位组件为自定义组件comp-placeholder后，ref 回调函数会在渲染占位组件时调用refHandler并传入comp-placeholder的实例，等到自定义组件comp注入并实例化后再次调用refHandler 并传入comp的实例。

组件被提前注入，占位组件无效的常见情况

如果在页面中出现如上图中所示的组件使用方式：

页面 Page 中使用自定义组件 Parent，Parent 使用自定义组件 Child；

同时，页面 Page 中使用了自定义组件 Child。

那么：

仅在 Page 中为 Child 配置占位组件，占位组件不会生效，原因是 Parent 使用的 Child 由于没有配置占位组件会在一开始就注入；

同样的，仅在 Parent 中为 Child 配置占位组件也不会生效。

因此，在这种情况下如果需要 Child 组件能够实现懒加载的效果，需要同时在 Page 以及 Parent 组件中为 Child 组件配置占位组件。

占位组件收藏我的收藏

​配置​

​注意事项​

​生命周期​

​扩展阅读​

​ref 获取配置了占位组件的自定义组件实例​

​组件被提前注入，占位组件无效的常见情况​