代码组件
基于 Zion 平台能力,通过编写 React 组件代码可扩展自定义组件,实现动态表单、数据驱动图表、复杂动画、交互式地图等多种业务场景。
前置条件
- 了解 FunctorZ 平台及实践经验
- 具备前端基础,熟悉 TypeScript
- 能独立编写 React 组件代码
如需 React 入门,可参考:
快速开始
如有使用初期版本的代码组件项目,请参考本指南升级为最新代码组件。
推荐使用 Node 18 或 20 版本,暂勿使用 Node 22。
安装全局命令行工具:
npm i -g functorz
# 如遇网络缓慢可切换源并强制重装:
# npm i -g functorz --registry=https://registry.npmmirror.com --force
操作概览
安装后运行 functorz --help
查看全部命令及说明。
functorz --help
zvm cli 0.4.7
Usage: functorz [options] [command]
Options:
-h, --help display help for command
Commands:
create [options] <项目名> 初始化项目。会在登录的账户下创建关联的自定义组件项目,并且在本地初始化一个模板项目。
publish [options] 发布项目。
reinit [options] 重新注册项目ID,将本地项目重新发布为自己账号下的一个新项目。
reset [options] 创建模板项目。在当前目录下重置一个模板项目。
signin [options] <用户名/邮箱> <密码> 登录到Zion平台,目前仅支持用户名密码/邮箱密码方式登录。
signout [options] 退出,删除目前登录信息。
help [command] display help for command
常用命令
create <项目名>
:初始化项目publish
:发布项目reinit
:重新注册项目 IDreset
:重置模板项目signin <用户名/邮箱> <密码>
:登录 Zion 平台
登录平台
在自己的工作目录下运行如下命令。
> functorz signin 你的邮箱账号 你的密码
等待命令执行完成。
> functorz signin 你的邮箱账号 你的密码
zvm cli 0.4.7
ℹ 登录
✔ 登录成功
创建项目
- 在任意目录运行以下命令:
# create 项目名
> functorz create test
- 等待命令执行完成。该步命令会创建一个新的文件夹
test
,它包含所有工程文件和模板组件。后续开发只需在该文件夹下进行。 - 该命令同时会在平台上注册一个代码组件项目。 一个代码组件项目中可以包含多个代码组件。
注意此时还没有发布任何版本。
> functorz create test
zvm cli 0.4.7
ℹ 项目初始化
✔ 准备工作目录完成
✔ 获取最新模板完成
✔ 生成项目完成
✔ 在Zion平台注册项目完成
✔ 关联远程项目完成
✔ 项目初始化完成
编辑代码
到代码组件项目目录中,安装依赖。
> cd test
> npm install
项目结构
一个典型的代码组件库项目的基本结构如下所示。
- codegen.ts
- index.html
- package-lock.json
- package.json
- App.scss
- App.tsx
- index.ts
- index.css
- main.tsx
- vite-env.d.ts
- tree.txt
- tsconfig.json
- tsconfig.node.json
- vite.config.ts
其中 src/components
是声明和编辑代码组件主要目录。
强制约定
每个自定义组件必须符合下述规则,请严格遵循。可以参考模板项目中的示例代码进行开发。
-
组件必须有一个目录在
src/components
下,该目录名称必须为组件名,该目录下必须至少包含index.ts
和组件名.tsx
。其中index.ts
用于导出组件,组件名.tsx
用于编写业务逻辑。 -
src/components/组件名/组件名.tsx
下声明的组件的属性类型声明必须 export 4 个 interface,分别是[${组件名}PropData]
,[${组件名}StateData]
,[${组件名}Event]
,以及[${组件名}Prop]
。且该 4 个 interface 符合如下约定。${组件名}PropData
用于声明从外部宿主项目需要传入的数据,目前支持的类型包括 string, number, boolean。${组件名}StateData
用于声明从代码组件内部暴露给外部宿主项目的状态,其类型必须为State<string | number | boolean>
,其中State
需要从zvm-code-context
包中引入。${组件名}Event
用于声明代码组件内部除外外部的事件,其属性的类型必须为EventHandler
。EventHandler
需要从zvm-code-context
包中引入。${组件名}Prop
固定包含上述 3 个类型的属性,且名称分别propData
,propState
和event
。
代码示例:
import { ExclamationCircleFilled } from '@ant-design/icons'
import { Button, Modal } from 'antd'
import { EventHandler } from 'zvm-code-context' // 暴露宿主项目上下文的包,里面还暴露了一个很重要的 API,useAppContext,具体可参考模板项目和下文。
// 组件的属性数据,右边栏配置,由外向内传递。这里暴露了三个右边栏的数据配置项,分别是 buttonTitle、modalTitle、modalContent。
export interface ConfirmModalPropData {
buttonTitle: string
modalTitle: string
modalContent?: string
}
// 组件的状态,右边栏配置,由内向外传递,可供宿主项目的其他组件绑定。
export interface ConfirmModalStateData {}
// 组件可供绑定的事件,类型目前是固定的,只能是 EventHandler。
export interface ConfirmModalEvent {
onConfirm?: EventHandler
onCancel?: EventHandler
}
// 固定写法。运行时,宿主项目将通过以下三个属性传递进来。
export interface ConfirmModalProps {
propData: ConfirmModalPropData
propState: ConfirmModalStateData
event: ConfirmModalEvent
}
// 组件逻辑。
export function ConfirmModal({ propData, event }: ConfirmModalProps) {
// 确认的事件逻辑。
const showConfirm = () => {
Modal.confirm({
title: propData.modalTitle || '', // 绑定宿主项目传进来的弹窗标题内容。
icon: <ExclamationCircleFilled />,
content: propData.modalContent || '', // 绑定宿主项目传进来的弹窗主内容。
onOk() {
event.onConfirm?.call(null) // 调用宿主项目绑定的确认事件处理逻辑。
},
onCancel() {
event.onCancel?.call(null) // 调用宿主项目绑定的取消事件处理逻辑。
},
})
}
return (
<Button type="primary" onClick={showConfirm}>
{propData.buttonTitle || ''} {/* 绑定宿主项目的按钮文本内容。*/}
</Button>
)
}
注意事项:
- 组件名必须符合 JavaScript 的命名规范,且不能包含特殊字符。
- 组件名必须以大写字母开头。
- 组件名必须与目录名一致,且目录名必须与组件文件名一致。
- 类型命名必须严格为 SpherePropData、SphereStateData、SphereEvent、SphereProps,且全部 export。
- Props 类型必须为 SphereProps,且组件函数参数类型也必须为 SphereProps。
- 不能用
import('zvm-code-context').EventHandler
这种写法,应直接import { EventHandler } from 'zvm-code-context'
。 - 必须有
export function Sphere(props: SphereProps) {}
,不能省略 props 类型。
- 在
src/components/index.ts
中暴露新编辑的组件。

与 AI 协同开发代码组件
- 按照上文新建代码组件项目。
- 打开代码编辑器内置ai功能,如 VS code 的 AI Copilot 或 Cursor。
- 输入提示词,生成代码组件。注意让ai在
test/src/components
目录下生成代码组件。
推荐提示词:
阅读“https://docs.functorz.com/community/code_component/”,然后完全按照Zion平台的规范编写一个 React 组件。
组件名为 ConfirmModal,功能是弹出确认对话框。组件需要支持以下功能:
1. 组件属性包括:
- 按钮文本
- 弹窗标题
- 弹窗内容
2. 组件状态包括:
- 确认事件处理函数
- 取消事件处理函数
3. 组件需要使用 Ant Design 的 Modal 和 Button 组件
4. 组件需要导出以下类型:
- ConfirmModalPropData
- ConfirmModalStateData
- ConfirmModalEvent
- ConfirmModalProps
请使用 TypeScript 编写,并确保组件符合 Zion 平台的代码组件规范。
- 按照上文的规范,与Ai对话确保代码符合要求。
本地调试
本地调试前需在 App.tsx 中引入组件。
直接查看本地 preview 的结果
输入以下命令:
npm run dev # 启动本地开发服务,可以为构建产物支持 http 访问。默认启动 5819 端口。
结合 Zion 实时预览
结合 Zion 实时预览,与宿主项目进行数据和交互的联动,继而进行本地调试。本方式需要依赖项目曾经发布过并在 Zion 项目里使用。
操作步骤:
- 按照下文发布流程发布代码组件 —— 项目历史上已发布过,可以忽略这一步
- 运行以下命令:
> npm run preview # 本地启动一个静态资源服务器,可以为构建产物支持 http 访问。默认启动 6326 端口。
> npm run watch:build # 监听本地源代码发生的变化,当编辑保存后,自动运行 npm run build。
# 注意如果不启动 watch:build 命令,可以在编辑后手动运行 npm run build。效果一致。
- 配置入参、行为
- 打开实时预览,点击“调试”(扳手图标),选择端口
- 在代码编辑器内修改后,刷新实时预览查看最新效果。
相关 API
zvm-code-context 为代码组件提供了一些对宿主项目上下文绑定过的 API。开发者可以通过相关 API 更便捷地实现所需功能。
// 某组件内
import { useAppContext } from 'zvm-code-context'
const { component, discover, query, navigate, globalData, pageData } =
useAppContext()
// ...
- component,内包含了宿主项目用于描述当前组件实例的所有数据信息。
- discover(id: string): Component,用于根据一个组件 ID 获取宿主项目中的特定组件实例。
- query 用于向宿主项目的后端发起一个请求。具体可参考模板项目中的 DataTable 组件。
- navigate 用户跳转到宿主项目的制定页面。我们推荐用这种方式跳转,以执行一些特定的跳转逻辑。
- globalData 中拥有当前宿主项目的全局变量。
- pageData 中拥有当前宿主项目的当前运行页面的页面变量。
发布项目
- 编辑 package.json 中的 version。代码组件的 version 严格遵循 npm 包的规范。
- 运行如下命令发布项目。
# 必须在项目的目录下运行
> functorz publish
zvm cli 0.4.7
ℹ 发布项目
✔ 扫描组件信息完成
✔ 组件解析完成
✔ 项目构建完成
✔ 注册版本信息中0.0.2
ℹ 产物上传开始
ℹ ConfirmModal-DkZp9JXU.js
ℹ __federation_expose_Main-DxfqaaDF.js
ℹ __federation_fn_import-lyDSGtOx.js
ℹ __federation_shared_classnames-DNBU_3PZ.js
ℹ __federation_shared_constate-BXZUjDp9.js
ℹ __federation_shared_lodash-CMjxsLue.js
ℹ __federation_shared_moment-CEY8C7XE.js
ℹ __federation_shared_react-DO25RkNm.js
ℹ __federation_shared_react-dom-ChyTJqHm.js
ℹ __federation_shared_react-router-dom-BwChNopu.js
ℹ __federation_shared_zvm-code-context-DJ2L4k_6.js
ℹ _commonjsHelpers-BFTU3MAI.js
ℹ index-BBIatVb0.js
ℹ remoteEntry.js
ℹ style-CLbg9otl.css
✔ 产物上传完成
✔ 发布项目成功
发布成功,此时可以前往平台的任意无代码项目中的左边栏配置新发布的代码组件库。
如果发布失败,可以运行 functorz publish --verbose
,以获得更详细的信息,在社区或者用户群提报错误。
在 Zion 中使用代码组件
导入代码组件
在任意 Zion 项目中,左边栏点击对应图标,在弹窗中找到刚发布的代码组件项目,并勾选。

此时左边栏最下方新增新发布的代码组件。
右边栏的数据配置和事件配置,是完全根据自己编写的代码而生成。必须注意,代码中的声明一定要按照规范编写,否则无法生成右边栏配置。

更新后端
新配置或更改代码组件项目后,必须更新后端或者发布后才能在运行时正常使用。

配置代码组件属性(配置数据和行为)
在组件右边栏配置定义好的数据和行为。配置的属性根据编辑代码时声明的属性类型解析而成,所以一定要严格遵守约定。
实时预览或发布项目
