FlowGram 文档的组织结构

• 英文文档: apps/docs/src/en

• 中文文档: apps/docs/src/zh

• Story 组件: apps/docs/components/form-materials/components

• 物料源码: packages/materials/form-materials/src/components

• 文档模板: ./templates/material.mdx

组件物料文档撰写流程

1. 源码定位

在 packages/materials/form-materials/src/components 目录下确认物料源代码地址。

操作：

• 使用 Glob 工具搜索物料文件

• 确认目录结构（是否有 hooks.ts, context.tsx 等）

• 记录导出名称和文件路径

2. 需求收集

向用户询问物料使用实例和具体需求。

收集信息：

• 主要使用场景

• 典型代码示例（1-2 个）

• 特殊配置或高级用法

• 是否需要配图

3. 功能分析

深入阅读源代码，理解物料功能。

分析要点：

• Props 接口（类型、默认值、描述）

• 核心功能和实现方式

• 依赖关系（FlowGram API、其他物料、第三方库）

• Hooks 和 Context

• 特殊逻辑（条件渲染、副作用等）

4. Story 创建

在 apps/docs/components/form-materials/components 下创建 Story 组件（详见下方 Story 规范）。

5. 文档撰写

基于模板 ./templates/material.mdx 撰写完整文档。

文档位置：

• 中文：apps/docs/src/zh/materials/components/{物料名称}.mdx

• 英文：apps/docs/src/en/materials/components/{物料名称}.mdx （翻译后）

6. 质量检查

检查清单：

• Story 组件能正常运行

• 代码示例准确无误

• API 表格完整

• 依赖链接正确可访问

• 图片路径正确

• Mermaid 流程图语法正确

• CLI 命令路径准确

用户确认中文文档的撰写后，再执行翻译。 用户确认中文文档的撰写后，再执行翻译。 用户确认中文文档的撰写后，再执行翻译。

Story 组件规范

参考示例: apps/docs/components/form-materials/components/variable-selector.tsx

命名规范

文件命名: kebab-case，与物料名称一致

• ✅ variable-selector.tsx

• ✅ dynamic-value-input.tsx

• ❌ VariableSelector.tsx

Story 导出命名: PascalCase + "Story" 后缀

• BasicStory

• 基础使用（必需）

• WithSchemaStory

• 带 Schema 约束

• DisabledStory

• 禁用状态

• CustomFilterStory

• 自定义过滤

• 根据物料特性命名，见名知意

代码要求

1. 懒加载导入

// ✅ 正确 const VariableSelector = React.lazy(() => import('@flowgram.ai/form-materials').then((module) => ({ default: module.VariableSelector, })) );

// ❌ 错误 import { VariableSelector } from '@flowgram.ai/form-materials';

2. 包装组件

// ✅ 正确 export const BasicStory = () => ( <FreeFormMetaStoryBuilder filterEndNode formMeta={{ render: () => ( <> <FormHeader /> <Field<string[]> name="variable_selector"> {({ field }) => ( <VariableSelector value={field.value} onChange={(value) => field.onChange(value)} /> )} </Field> </> ), }} /> );

// ❌ 错误：缺少包装 export const BasicStory = () => ( <VariableSelector value={[]} onChange={() => {}} /> );

3. 类型标注

// ✅ 正确 <Field<string[] | undefined> name="variable_selector">

// ❌ 错误 <Field<any> name="variable_selector">

4. 语言规范

代码和注释只使用英文，无中文。

完整示例

/**

• Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
• SPDX-License-Identifier: MIT */

import React from 'react'; import { Field } from '@flowgram.ai/free-layout-editor'; import { FreeFormMetaStoryBuilder, FormHeader } from '../../free-form-meta-story-builder';

const VariableSelector = React.lazy(() => import('@flowgram.ai/form-materials').then((module) => ({ default: module.VariableSelector, })) );

export const BasicStory = () => ( <FreeFormMetaStoryBuilder filterEndNode formMeta={{ render: () => ( <> <FormHeader /> <Field<string[] | undefined> name="variable_selector"> {({ field }) => ( <VariableSelector value={field.value} onChange={(value) => field.onChange(value)} /> )} </Field> </> ), }} /> );

export const FilterSchemaStory = () => ( <FreeFormMetaStoryBuilder filterEndNode formMeta={{ render: () => ( <> <FormHeader /> <Field<string[] | undefined> name="variable_selector"> {({ field }) => ( <VariableSelector value={field.value} onChange={(value) => field.onChange(value)} includeSchema={{ type: 'string' }} /> )} </Field> </> ), }} /> );

物料文档格式

使用模板

模板文件: ./templates/material.mdx

文档必须严格按照模板格式编写，包含以下章节：

• Import 语句

• 标题和简介（带可选配图）

• 案例演示（基本使用 + 高级用法）

• API 参考（Props 表格）

• 源码导读（目录结构、核心实现、流程图、依赖梳理）

参考示例

• dynamic-value-input.mdx

• 完整的流程图和依赖说明

• variable-selector.mdx

• 多个 API 表格和警告提示

关键注意事项

API 表格要求：

• 必须包含所有公开的 Props

• 类型使用反引号（如 string）

• 描述清晰简洁

• 多个相关类型分开列表

源码导读要求：

• 目录结构：展示文件列表及说明

• 核心实现：用代码片段说明关键逻辑

• 整体流程：Mermaid 流程图（推荐）

• 依赖梳理：分类列出 FlowGram API、其他物料、第三方库

图片处理指南

截图要求

• 时机: Story 组件完成后，运行 docs 站点截图

• 内容: 捕获物料的典型使用状态，清晰可见

• 格式: PNG，适当压缩

命名和存储

• 命名: {物料名称}.png （kebab-case）

• 存储: apps/docs/src/public/materials/{物料名称}.png

• 引用: /materials/{物料名称}.png

在文档中使用

<br /> <div> <img loading="lazy" src="/materials/{物料名称}.png" alt="{物料名称} 组件" style={{ width: '50%' }} /> </div>

翻译流程

翻译时机

• ✅ 用户明确要求翻译

• ✅ 中文文档已经用户审核确认

• ❌ 文档还在修改中

• ❌ 用户未确认最终版本

翻译原则

术语一致性：

• ComponentName → ComponentName（组件名不翻译）

• Props、Hook、Schema 等术语保持原文

代码不翻译：

• 所有代码块、命令、路径保持原样

链接处理：

• 内部链接：/zh/ → /en/

• 外部链接和 GitHub 链接：保持不变

格式保持：

• Markdown 格式、缩进、空行完全一致

翻译检查清单

• 标题和描述已翻译

• 代码示例未被翻译

• 命令和路径保持原样

• 内部文档链接已更新

• API 表格描述列已翻译

• Mermaid 图中文节点已翻译

• 术语使用一致

最佳实践

Props 提取技巧

• 查找 interface 或 type 定义

• 检查组件函数参数类型

• 查找 defaultProps 确认默认值

• 阅读 JSDoc 提取描述

依赖分析方法

• 查看 import 语句（直接依赖）

• 分析 Hook 调用（FlowGram API）

• 查找组件引用（其他物料）

• 检查 package.json（第三方库）

Mermaid 流程图建议

• 简洁明了，关注核心流程

• 使用时序图绘制

常见错误避免

❌ 直接导入物料而不使用 React.lazy

❌ API 表格遗漏 Props ❌ 依赖链接失效 ❌ 中英文混用 ❌ 路径格式错误

✅ 参考优秀示例 ✅ 仔细阅读源码 ✅ 验证所有链接 ✅ 保持语言和格式一致 ✅ 使用项目约定的路径格式

相关工具和资源

开发命令

启动文档站点

rush dev:docs

查看修改

git diff git diff --cached

关键目录

目录 说明

packages/materials/form-materials/src/components

物料源码

apps/docs/src/zh/materials/components

中文文档

apps/docs/src/en/materials/components

英文文档

apps/docs/components/form-materials/components

Story 组件

apps/docs/src/public/materials

图片资源

./templates

文档模板