抖音开放平台Logo
开发者文档
小程序
“/”唤起搜索
控制台
  • 开发教程与代码示例
  • 入门
  • 小程序框架
  • 小程序运行时
  • 自定义组件
  • 基础教程
  • 能力教程
  • 流量入口
  • 通用能力
  • 推广变现
  • 经营能力
  • 行业能力
  • 配置行业 SDK 的权限
  • 本地团购类小程序（步骤一：前端开发）
  • 本地团购类小程序（步骤二：商品库接入）
  • 电商
  • 插件扩展能力
  • 插件扩展能力
  • 营销扩展使用指南
  • AI/AR 能力
  • 性能优化
  • 安全
    • 基础库 2.69.0 及以上版本支持本能力。
    抖音开放平台设计一套交易系统并提供了一系列模板页面，例如：订单确认页、退款申请页、退款详情页，为了更好地帮助开发者对模板进行自定义，开放平台设计了一套模板扩展能力，通过这些扩展能力，小程序开发者可以对模板页面或组件进行定制化修改。
    注意
    在基础库 2.74.0 版本之前（不包括 2.74.0 版本），部分原生组件事件无法触发，包括：<input> 组件的 input 事件、<camera> 组件、<map> 组件、<video> 组件。

    背景信息

    在开始之前，先来了解本文涉及到的几个概念：
    名称
    说明
    扩展能力
    扩展能力是指一系列语法范式和功能，通过使用扩展能力，小程序开发者可以对插件导出的页面或组件进行定制化修改。
    插件
    一系列页面和组件的集合，由抖音开放平台提供，插件会导出页面、组件和 js 模块。
    模板
    插件导出的页面和组件称为模板，开发者可以直接使用模板，也可以使用扩展能力对模板进行定制化修改。
    扩展
    当使用扩展能力对模板进行定制化修改时，会产生一个扩展，扩展本身也是一个页面或组件，包含对应模板的逻辑和开发者定制逻辑。
    ​

    安装 IDE

    请使用最新版本的 IDE 进行插件扩展能力的接入调试。

    安装 App

    请使用 22.2.0 及以上版本的抖音或者抖音极速版进行插件扩展能力的接入调试。

    引入插件

    在自定义模板前，需要先在小程序 package.json 的 ttPlugins中引入插件。
    {
  "ttPlugins": {
    "dependencies": {
      "microapp-demo-plugin": {
        "version": "0.0.1",
        "isDynamic": true 
      }, 
      "microapp-ability-plugin": {
        "version": "0.0.1", 
        "isDynamic": true 
      }
    }
  }
}
    这里需要引入两个插件，它们的作用如下：
    插件名
    说明
    microapp-demo-plugin
    demo 插件，会导出一些组件和页面给小程序使用。
    microapp-ability-plugin
    包含扩展能力的插件，使用该插件导出的 Extension 构造器，可以创建一个扩展。
    同时，还需要在 app.json 中配置插件导出的模板页面：
    {
  "pages":[ 
    "ext://microapp-demo-plugin/order-confirm",
    "ext://microapp-demo-plugin/refund-apply",
    "ext://microapp-demo-plugin/refund-detail"
  ]
}

    创建扩展

    类似于自定义组件，一个扩展由 json、 ttml、ttss、js 4 个文件组成。要编写一个扩展，需要以下一些步骤：
      1.在 json 文件中配置 extends 字段，表示对指定模板进行定制。
    {
  "extends": "ext://microapp-demo-plugin/order-confirm" 
}
      2.在 ttml 中编写扩展中的节点，同时在 ttss 中加入扩展的样式。
    <view slot="footer"> 
  <input
    class="id-input"
    value="{{idNo}}"
    type="number"
    placeholder="输入身份证"
    bind:blur="onInputBlur"
  />
</view>
      ◦ttml 中需使用 slot 属性，来将节点插入到模板的不同 slot 上。
      ◦ttss 中的样式只应用于扩展中的节点：
    .id-input { 
  color: blue;
}
      3.在 js 文件中，通过 Extension 构造器来注册扩展，并提供扩展的属性定义、内部数据和自定义方法。
    const { Extension } = require('ext://microapp-ability-plugin/index');
 
Extension({
  data: {
    idNo: '',
  },
  created() {},
  methods: {
    onInputBlur() {},
  },
});
        Extension 构造器由 microapp-ability-plugin 插件导出，使用时需要 require 进来。

    使用扩展

    和使用页面一样，在 app.json 的 pages字段下添加扩展的路径。
    例如：扩展的路径为 pages/order-confirm/index ，在 pages 字段下添加该路径。
    { 
  "pages":[
    "ext://microapp-demo-plugin/order-confirm",
    "pages/order-confirm/index"
  ],
}
    之后和跳转页面一样，使用路由 API 或者 navigator 标签跳转到扩展页面。
    注意事项：
      •扩展页不能配置为首页和 tabbar 页面。
      •当在 app.json 中开启 component2: true 时，扩展页内不会启用新的自定义组件流程。

    代码示例

    在开发者工具预览

    扩展的特性

    在创建扩展时，需要使用 Extension 构造器来定义扩展的数据、方法、生命周期等。在运行时，扩展和模板的 options会进行合并，注册为一个新的页面。
    这类似于 behaviors ，但与 behaviors 不同的是：
      •扩展和模板的同名属性和方法不会互相覆盖；
      •Extension 会产生一个独立的实例，里面只包含 Extension 构造器定义的数据、方法，以及一部分通用实例方法，例如：setData；
      •Extension 定义的数据和方法只会作用于扩展内的节点，同样，模板中的数据和方法也只会作用于模板内的节点；
      •每次使用 Extension 都将产生一个新的页面，对于模板和扩展共有的生命周期，将会按照先模板后扩展的顺序执行。

    配置扩展

    每一个扩展可以通过对应目录下的 json 文件进行配置：
    { 
  "extends": "ext://microapp-demo-plugin/order-confirm",
  "usingComponents": {
    "my-component": "./components/my-component/index"
  },
  "navigationBarBackgroundColor": "#ffffff",
  "navigationBarTextStyle": "black"
}
    与页面的 json 相比，扩展的 json 只支持部分字段。具体的字段如下：
    属性
    类型
    默认值
    描述
    extends
    string
    ​
    模板 path，如：ext://microapp-demo-plugin/order-confirm。
    usingComponents
    object
    ​
    扩展使用的自定义组件
    navigationBarBackgroundColor
    HexColor
    ​
    导航栏背景颜色，如"#000000"
    navigationBarTextStyle
    string
    ​
    导航栏标题颜色，仅支持 black/white
    navigationBarTitleText
    string
    ​
    导航栏标题文字内容
    backgroundColor
    HexColor
    ​
    窗口的背景色
    注意事项：不支持为扩展中的自定义子组件配置占位组件。

    扩展内节点和样式

    嵌入模板插槽

    ttml 中的节点需使用 slot 属性，表示将节点插入到模板页面的对应 slot 上。
    <!-- 将自定义组件嵌入到模板的 main 插槽 --> 
<my-component
  ref="refHandler"
  slot="main"
  bind:func="func"
>
</my-component>
<!-- 将内置组件嵌入到模板的 footer 插槽 -->
<view slot="footer">
  <input
    value="{{idNo}}"
    type="number"
    placeholder="输入身份证"
    bind:blur="onInputBlur"
  />
</view>
    其他数据和事件绑定和正常自定义组件 ttml 文件一致。
    注意事项：
      •不支持动态设置 slot 属性。
    <!-- 不支持动态设置-->
<view slot="{{main}}" />
      •扩展中自定义子组件的 selectOwnerComponent 将访问到扩展实例。

    扩展样式

    扩展对应 ttss 文件的样式，只对扩展 ttml 内的节点生效。
    其他样式特性和 自定义组件样式 一致。
    注意事项：
      •扩展的渲染是基于模板，当渲染一个扩展时，小程序 app.ttss 中的全局样式，也会应用到模板中的节点。
      •扩展的 ttss 文件中暂不支持使用 @import 引入公共 css 。

    Extension 构造器

    Extension 构造器可用于定义扩展，调用 Extension 构造器时可以指定扩展的属性、数据、方法等。
    从 microapp-ability-plugin 插件引入 Extension 构造器，通过该构造器，可以基于模板创建一个扩展。
    代码示例：
    const { Extension } = require('ext://microapp-ability-plugin/index');
 
Extension({
  data: {
    idNo: '',
  },
  observers: {
    template: {
      // this.template 上的数据监听
      goodsInfo(value) {
        // do something
      },
    },
  },
  // created 生命周期
  created() {
    // 通过 this.template 访问模板给到扩展的数据和方法
    console.log(this.template);
  },
  methods: {
    // ref 能力的回调
    refHandler(ref) {
      this.current = ref;
    },
    // 输入框绑定的事件回调
    onInputBlur(e) {
      const value = e.detail.value;
      this.setData({
        idNo: value,
      });
    },
  },
});

    Options

    Extension 的 options 和 Componet 对齐，但只支持部分字段。属性如下：
    属性名
    类型
    必填
    说明
    data
    object
    否
    扩展的内部数据
    observers
    object
    否
    数据监听器
    methods
    object
    否
    扩展的方法，包括事件响应函数和任意的自定义方法
    pageLifetimes
    object
    否
    所在页面的生命周期声明对象。支持 pageLifetimes.show，pageLifetimes.hide，pageLifetimes.resize
    lifetimes
    object
    否
    生命周期声明对象，优先级比同级的 attached、detached 等生命周期优先级高
    created
    function
    否
    created 生命周期
    attached
    function
    否
    attached 生命周期
    ready
    function
    否
    ready 生命周期
    detached
    function
    否
    detached 生命周期

    生命周期

    不同于 Component 构造器，Extension 只支持部分生命周期：
    生命周期
    参数
    说明
    show
    {showFrom: 10/0/undefined}
    所在页面被展示时执行。
    hide
    无
    所在页面被隐藏时执行。
    resize
    Object Size
    所在的页面尺寸变化时执行。
    created
    无
    扩展实例进入页面节点树时执行。
    attached
    options
    ​
    扩展实例进入页面节点树时执行。当扩展模板页面时，可以接收到模板页面 onLoad 生命周期的 query。
    ready
    无
    扩展布局完成后执行。
    detached
    无
    扩展实例被从页面节点树移除时执行。
    同样的生命周期回调，扩展会在模板之后执行。
    模板和扩展间生命周期关系图示：
    ​

    使用模板的数据和方法

    扩展可以通过 this.template 访问到模板提供的数据和方法，数据最早能在 created 生命周期中取到。
    Extension({ 
  data: {
      idNo: ''
  },
  created() {
    // 访问模板提供的数据
    console.log(this.template.goodsInfo);
    // 访问模板提供的方法
    this.template.setConfig();
  },
});
    注意事项：不支持直接将 template 上的属性用于在 ttml中绑定。

    数据监听器 observers

    数据监听器可以用于监听和响应扩展 data 和 this.template 上数据的的变化，触发监听回调。
    const { Extension } = require('ext://microapp-ability-plugin/index');
 
Extension({
  data: {
    idNo: '',
  },
  observers: {
    template: {
      // this.template.goodsInfo 变化时，执行这个函数
      goodsInfo(value) {
        // do something
      },
    },
    // this.data.idNo 变化时，执行这个函数
    idNo(value) {
      // do something
    },
  },
});
    扩展的 observers 的特性和 自定义组件 observers 一致。

    扩展实例

    Extension 构造器会产生一个扩展实例，可以在扩展的方法、生命周期函数和数据监听 observers 中通过 this 访问。
    和自定义组件不同，扩展实例只包含部分通用属性和方法。
    扩展实例方法：
    实例方法
    参数类型
    说明
    setData
    data: object, callback: function
    设置 Extension 中的 data，触发无参回调 callback 。
    此方法只会影响到 Extension 中的 data。
    扩展实例属性：
    实例方法
    参数类型
    说明
    route
    string
    路由路径
    is
    string
    扩展的文件路径
    data
    object
    扩展中的数据

    ref 获取组件实例

    扩展中支持使用 ref 获取到自定义组件的实例。使用方式参见 自定义组件 ref 。
    <my-component ref="refHandler" slot="main"></my-component>
    Extension({ 
  data: {
    idNo: '',
  },
  methods: {
    refHandler(ref) {
      this.current = ref;
    },
  },
});

    注意事项

      •不支持在 methods 中定义 onLoad, onReady 等方法表示生命周期，请使用 attached, ready 生命周期代替；
      •当使用 onShareAppMessage 时，小程序从被分享的入口进入时，此时是扩展页作首页的情况，需要处理低版本兼容问题。
      •使用 getCurrentPages 方法将获取到扩展实例。
    ​