插件编码

可以使用文本编辑器(比如Sublime Text)打开代码文件直接编辑,也可以导入到集成开发环境(比如VS Code)编辑。

插件注册函数

$plugin({
    id: "zp***",
    props: [],
    render,
    onInit,
    onDestroy,
    noContainer,
    css
})

是插件的主体。除了id是必填的其他都是选填项,把不需要的注释或删除掉即可。
通常我们会把此函数放到代码末尾,而把render、onInit等函数放在前头。

id

插件id,用来唯一识别本插件,会被用作本插件容器的类名,因此同一页面中多次使用的插件实例具有相同的类名,通常我们写插件css时使用此id作为类名前缀以限制css不会作用到页面上的其他组件。我们打包插件源码时生成的压缩包也是用此id来命名。

render()

ReactJS的渲染函数,需返回jsx以渲染插件视图,因此需要在代码顶部先用
import React from "react"
引入react。

页面每次渲染的时候都会调用此函数,会频繁执行,因此不应该把复杂耗时的计算任务放在此函数里(建议放onInit里)。

它只是ReactJS的渲染函数,并不是react组件,因此没有react完整的生命周期,不可以使用useState,useEffect,useRef等hook。插件的生命周期是由平台管理的(有onInit和onDestroy)

onInit()

插件初始化时将调用此函数(仅一次),因此特别适合初始化插件、从数据库加载数据、加载第三方插件等工作。

onDestroy()

插件被页面卸载时将调用此函数(仅一次),用来做任务清理/内存回收的工作。

noContainer

通常每个插件都有一个div作为容器,当noContainer为真时就不再有此容器。这时ref下就会多一个rest对象,需要把它传给render()函数最外层的元素:{...ref.rest}。如果想给此元素添加类名,不能直接传入className,而应该用ref.rest.className += " yourClassName"

css

少量的css可直接放反引号里,量多了推荐写到外部文件中(如css文件夹里),再通过import css from “../***”引入。

参数对象ref

平台都会给这四个函数传递一个对象类型的参数,这个参数其实是插件这个react组件里const ref = useRef({…})ref.current,我们就把这个参数称为ref吧。

它里面包含有平台提供的{ id, container, props, exc, render, getForm, setForm}变量/函数。
如果我们让插件里的各个函数都带上此参数对象,那么各个函数之间就可以方便的共享信息了。

id

组件实例id,即在组件树显示的id,是本插件实例在页面中的唯一id,在同一页面上的多个同一插件的实例具有不同的id,所以这个id可以作为选择器选中本插件实例元素

container

是本插件实例的容器元素,所以只有在插件挂载成功以后才存在。通过此容器可以遍历/操作插件内部元素,有时也用它作为跟其他组件交流信息的桥梁。

children

开发者放入本插件的子组件(如有)

props

插件开发者通过注册函数里的props数组给应用开发者提供了属性面板,此props就是应用开发者在此属性面板中配置的一系列值,所以它是与插件用户交流的桥梁,是赋予用户自定义插件的能力。

ctx

即插件所处的上下文环境,数据组件提供给插件的运行时数据。如果插件提供一个事件钩子给用户,就应把插件提供的数据与ctx合并后作为用户事件表达式上下文运行时数据$ctx提供给用户。

ref.exc(ref.props.onSelect, { ...ref.ctx, $x: item, $index: index }, () => ref.exc("render()"))

exc()

用来执行众触表达式,可以便利高效的与平台进行互动。
第一个参数是必填的表达式字符串。
第二个参数是表达式的执行环境,即$ctx。
第三个参数是表达式执行完成后的回调函数。表达式执行结果将传给回调函数,即$r

render(tree, id)

无参数时用来重新渲染本插件(而非整个页面),意味着会再次调用插件的render()函数。一般用户在页面中交互以后或从数据库取回数据后调用。
传入参数是为了返回元数据对象树tree的渲染片段,是为了重用众触组件,当依赖另一个插件时也常用到。可传入起点id

getForm(path)

获取表单特定路径path的值。插件必须是表单form的子组件。

setForm(path, value)

设置表单特定路径path的值value。插件必须是表单form的子组件。

属性面板

插件开发者可以通过属性面板收集应用开发者配置的属性,用以改变插件的行为或视图。每个属性对象有如下key:

  • prop: 属性名。必填

  • type: 属性类型,用来渲染属性面板表单。有text、number、switch、select、radio、check、exp、json类型。必填

  • label:表单标签

  • ph:表单占位符placeholder

  • items:select/radio/check类型的选项数组。如果提供的是二维数组的话那么第一个数组是value,第二个数组是label

其他

代码里面可以直接使用log、warn、error、debug而不用带上console。

官方源码

官方开源插件源码及讲解视频是非常好的学习素材。

Make in ZC APP Platform