代码组件开发

登录平台

在自己的工作目录下运行如下命令。

> functorz signin 你的邮箱账号 你的密码

创建项目

在任意目录运行以下命令：

# create 项目名
> functorz create test

该命令会创建一个新的文件夹 test，它包含所有工程文件和模板组件。同时会在平台上注册一个代码组件项目。

编辑代码

进入项目目录并安装依赖：

> cd test
> npm install

如需使用 AI 协同开发，请阅读：使用 Cursor 辅助开发 Zion 代码组件 

阅读项目模板结构

一个典型的代码组件库项目的基本结构如下所示。

• public
• resources
• src
  • components
    • Main
    • index.ts
  • graphql
  • typings
  • App.scss
  • App.tsx
  • index.css
  • main.tsx
  • vite-env.d.ts
• .eslintrc.cjs
• .gitignore
• codegen.ts
• HELPER.md
• index.html
• package.json
• README.md
• tsconfig.json
• tsconfig.node.json
• vite.config.ts

其中：

• src/components 是声明和编辑代码组件的主要目录。
• resources 是资源文件目录，用于存放图标和预览图。
• README.md 是项目说明文件，用于存放项目说明。

遵守强制规范

每个自定义组件必须符合下述规则：

1. 目录结构规范

   • 组件必须有一个目录在 src/components 下
   • 目录名称必须为组件名（大写字母开头）
   • 目录下必须至少包含 index.ts 和 组件名.tsx

2. 类型声明规范 src/components/组件名/组件名.tsx 下必须 export 以下 4 个 interface：

   接口名称	用途	类型要求
   ${组件名}PropData	外部传入数据	string, number, boolean 及其数组
   ${组件名}StateData	暴露给外部的状态	State<string | number | boolean> 或其数组
   ${组件名}Event	触发外部事件	EventHandler
   ${组件名}Props	组件 Props	包含 propData, propState, event

   代码示例：

   import { EventHandler } from 'zvm-code-context';
    
   export interface ConfirmModalPropData {
     buttonTitle: string;
   }
    
   export interface ConfirmModalStateData {}
    
   export interface ConfirmModalEvent {
     onConfirm?: EventHandler;
   }
    
   export interface ConfirmModalProps {
     propData: ConfirmModalPropData;
     propState: ConfirmModalStateData;
     event: ConfirmModalEvent;
   }
    
   export function ConfirmModal({ propData, event }: ConfirmModalProps) {
     // ... 业务逻辑
   }

与宿主项目交互（可选）

请阅读：代码组件 API 参考 

导出组件

在 src/components/index.ts 中暴露新编辑的组件。

修改项目基础信息（项目和组件元数据）

1. package.json：修改 name, description, version (遵循 npm 规范)。
2. resources 目录：添加图标和预览图 (webp/svg)。
   • /resources/icon.webp (24x24)
   • /resources/组件名/icon.webp (72x54)
   • /resources/组件名/canvas.webp (300x200)
3. README.md：修改项目和组件说明。
   • /README.md：项目说明。
   • /src/components/组件名/README.md：组件说明。

本地调试

方式一：直接 Preview

npm run preview # 本地启动一个静态资源服务器，可以为构建产物支持 http 访问。默认启动 6326 端口。

方式二：结合 Zion 实时预览

1. 确保项目历史已发布过。
2. 运行以下命令：

npm run preview # 本地启动一个静态资源服务器，可以为构建产物支持 http 访问。默认启动 6326 端口。
npm run watch:build # 监听本地源代码变化，当编辑保存后，自动运行 npm run build 命令。

3. 在 Zion 编辑器中打开实时预览，点击“调试”图标，选择端口 6326。
4. 代码变更后，刷新实时预览即可看到最新效果。

发布项目

在根目录运行以下命令：

functorz publish

如果发布失败，可以运行 functorz publish --verbose，以获得更详细的信息，问 AI 或者在社区或者用户群提报错误。

在 Zion 中使用

1. 导入：点击添加组件，选择“导入”，点击“导入组件库”即可。
2. 同步：代码变更后需同步或重新发布。
3. 使用：拖拽组件到画布，配置右侧属性面板（数据绑定、事件）。