收藏
回答

自定义组件公测说明及入门介绍

问题模块
API和组件

自小程序发布至今,我们接收到了很多反馈,希望小程序框架能加强对组件化编程的支持。现在,小程序基础库已经包含与自定义组件相关的支持,我们决定对这些特性开放公测。有了这些特性之后,你可以: * 将一些复用性强的代码抽象成“自定义组件”,它们的使用方法与基础库内置的 `view` 、 `button` 等组件非常相似。 * 或者将页面拆分成几个低耦合的部分,降低页面局部更新时的渲染开销。 * 还可以将你自己制作的“自定义组件”代码文件开源出来,与其他开发者共享你的成果! 为项目启用自定义组件的方法是: 1. 用开发者工具打开小程序项目设置,在项目设置中勾选“预览/上传时使用新特性”,并确认使用基础库版本是 1.6.6 或更高; 1. 如果需要在手机上预览,请确认手机上安装的微信是最新版本(6.5.16或更高)。 ## 如何编写一个自定义组件 每个自定义组件由四个代码文件组成: * `json` 文件:用于放置一些最基本的组件配置。 * `wxml` 文件:组件模版。 * `wxss` 文件:组件的样式,只在组件内部节点上生效(这个文件是可选的)。 * `js` 文件:组件的js代码,承载组件的主要逻辑。 这四个文件与编写一个页面时用到的四个文件非常类似,但也有区别。下面将介绍如何利用这四个文件编写一个简单的自定义组件。 ### 组件配置 编写一个自定义组件,首先应在小程序代码目录中合适的位置创建一个 `json` 文件。这里我们把文件放置在小程序的 `components` 目录下,名为 `custom-checkbox.json` 。 ![目录结构](https://mmbiz.qlogo.cn/mmbiz_png/MOicxgtDNAjDDvhcvbW1byaaiaOoBmicp9yueJIOKLmzZJOLMo7aB5Qzhk611dufiaGH6BgfJsAB6BdgIeic3IwjLBw/0?) 这个文件中包含以下内容: ```json { "component": true } ``` ### 组件模版 在同一目录下,创建一个模版文件 `custom-checkbox.wxml` 。这个文件的写法与页面模版很类似: ```html ``` 这个模版将在组件中渲染出一个 `checkbox` 和一个 `label` 。 ### 组件样式 同样类似于页面, `wxss` 文件中可以指定组件节点的样式。其中的样式仅在组件内部生效。需要注意的是,样式只能通过类选择器(如 `.the-class-name` )来指定: ```css /* components/custom-checkbox.wxss */ .label { color: blue; } ``` ### 组件定义 组件的js文件中必须包含组件定义。定义时使用 `Component` 构造器: ```js // components/custom-checkbox.js Component({ properties: { title: { type: String } }, data: {}, methods: { labeltap: function() { console.log("label被点击了一下!") } } }) ``` 简单的 `Component` 构造器调用包含3个定义段: `methods` 中的方法可以用来包含组件的事件回调函数; `data` 是组件的内部数据,可以用 `this.setData` 方法来改变; `properties` 中声明这个组件的属性,上例中声明了 `title` 属性,这样,组件外部在使用组件时就可以指定这个属性的值。 这样我们就编写好了 `custom-checkbox` 这个组件。 ## 如何使用自定义组件 使用上面这个自定义组件的方法很简单。首先,在需要使用这个组件的页面对应的 `json` 文件中,添加下面的自定义组件声明: ```json { "usingComponents": { "custom-checkbox": "/components/custom-checkbox" } } ``` 然后就可以在页面对应的 `wxml` 文件中使用了: ```html ``` 这样,在页面上最终呈现的效果如下: ![示例预览图](https://mmbiz.qlogo.cn/mmbiz_png/MOicxgtDNAjDDvhcvbW1byaaiaOoBmicp9yAgDibZibrFLwNtFlqmmgOqjibn5Cpdu0zCrPvlFGzH1USEkAJp4gga1PA/0?) 在自定义组件中引用其它自定义组件的方法也类似。 ## 详细文档 有关自定义组件的详细文档,请参见 [开发者文档 - 框架 - 自定义组件](https://mp.weixin.qq.com/debug/wxadoc/dev/framework/custom-component/index.html) 。自定义组件还包含了一些高级功能,请阅读文档相关章节,如: * [组件自定义事件](https://mp.weixin.qq.com/debug/wxadoc/dev/framework/custom-component/events.html); * [组件间代码共享](https://mp.weixin.qq.com/debug/wxadoc/dev/framework/custom-component/behaviors.html); * [组件间关系](https://mp.weixin.qq.com/debug/wxadoc/dev/framework/custom-component/relations.html); * [高级Component构造器应用](https://mp.weixin.qq.com/debug/wxadoc/dev/framework/custom-component/component.html) 等。 ## Q & A Q:哪些微信版本可以使用自定义组件? A:自定义组件对小程序基础库版本的最低要求为 1.5.7 或 1.6.3 ,对应微信版本是 6.5.13 或更高,目前已能覆盖近90%的微信用户。 Q:在自定义组件中,有哪些API在使用时有特殊之处? A:在使用从WXML中选取特定节点的API时,需要传入自定义组件实例对象 `this` ,这些API包括 `wx.createSelectorQuery` 、 `wx.createCanvasContext` 等,在使用前请查询它们的文档更新。 Q:自定义组件特性在公测期间还会有哪些变更? A:由于我们对小程序基础库进行了大量改写,公测期间自定义组件特性可能包含bug,我们会及时修复,请自定义组件开发者关注公测期间的更新。遇到相关bug时,欢迎及时反馈。 Q:为页面添加 `usingComponents` 之后页面的表现不一样了,怎么办? A:这类问题绝大多数情况下属于基础库的bug,请单独发帖反馈。 Q:如何反馈bug、提相关需求和建议? A:请在开发者社区内单独发帖反馈(尽量不要直接在下方评论区反馈,以免骚扰其他开发者)。**发帖时请包含“自定义组件”标签**,这样我们可以更有效地关注到,谢谢!

最后一次编辑于  2017-11-03  (未经腾讯允许,不得转载)
回答关注问题邀请回答
收藏

9 个回答

  • 棉花糖
    棉花糖
    2018-02-06

    我想问下,你官网提供的组件间的关联到底如何实现关联?我根据提供的示例,压根获取不到custom-li的nodes节点

    2018-02-06
    赞同 1
    回复
  • holyrong
    holyrong
    2018-05-02

     @LastLeaf 你可能理解错了我的意图了,我是希望做一个组件,比如dialog,这个dialog组件中包含了一下部分代码:

    <form bindsubmit='submit'>
      <slot/>
      <button type='submit' />
    </form>

    然后在page中使用这个dialog:

    <dialog bind:submit="onsubmit">
         <input name="testInput" value="Test Value" />
    </dialog>

     结果发现submit事件中不能获取到testInput控件的值。

    2018-05-02
    赞同
    回复
  • 小程序技术专员-LastLeaf
    小程序技术专员-LastLeaf
    2018-04-03

    ready 生命周期是在页面初始渲染完成时的回调,这个时机是很晚的,可以保证页面信息已经完全就绪。


    但从逻辑上说,它们之间并没有太大的联系。

    2018-04-03
    赞同
    回复
  • EAGzzyCSL
    EAGzzyCSL
    2018-04-03

    谢谢~。那在组件的ready周期中取到的this.options是正式可用的嘛还是可能随时会被修改?

    2018-04-03
    赞同
    回复
  • 小程序技术专员-LastLeaf
    小程序技术专员-LastLeaf
    2018-04-02

    会一直可用。onLoad 等页面生命周期写在 methods 定义段中即可,与组件生命周期相互独立。

    2018-04-02
    赞同
    回复
  • EAGzzyCSL
    EAGzzyCSL
    2018-04-02

    冒昧挖坟,有问题求教,已知文档中说可以使用Component来替代Page(见文档链接最底部tips),那么:

    1. 这个后期是否会一直可用,会不会只是内测。(相关问题中有了一部分解答,但文档上一直只是模糊的提了一句)

    2. 使用Component替代Page时希望获取到类似Page的生命周期函数onLoad(options)中的options该在Component的哪个生命周期中获得?(实践可以在Compoent的ready中获得this.options,但缺乏文档支持不敢使用)。

    希望官方对使用Component构造page有更多的说明。

    感谢阅读。


    2018-04-02
    赞同
    回复
  • 小程序技术专员-LastLeaf
    小程序技术专员-LastLeaf
    2018-03-14

    @holyrong 请参考 wx://form-field

    https://mp.weixin.qq.com/debug/wxadoc/dev/framework/custom-component/behaviors.html

    2018-03-14
    赞同
    回复
  • holyrong
    holyrong
    2018-03-13

    自定义组件目前不能获取组件内部数据,不能做form提交,这个交互性太差了。比如:<form><slot/></form>,希望这个功能能实现。

    2018-03-13
    赞同
    回复
  • 棉花糖
    棉花糖
    2018-02-06

    @Jobin 通过triggerEvent传递,官网提及,第二个myEventDetail就是将组件的数据传递到父容器的方法的

    this.triggerEvent('myevent', myEventDetail, myEventOption)


    2018-02-06
    赞同
    回复