FastGPT 前端组件开发规范基于 React TypeScript Chakra UI 的组件结构、状态管理与国际化实践【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT本篇指南以 FastGPT 仓库内置的 前端开发规范 为核心骨架系统讲解 FastGPT 前端projects/app与packages/web在组件结构、状态管理、样式体系、国际化与性能优化五个维度的工程约定。读者在阅读后将掌握 FastGPT 团队的组件写法与可复用的代码模板并能把这些规范直接应用于 FastGPT 相关的二次开发、功能扩展与 PR 代码审查。技术栈基线React TypeScript Chakra UIFastGPT 前端统一采用React TypeScript Chakra UI技术栈这一点在 projects/app/package.json 的依赖声明中可以得到印证应用层直接引用了chakra-ui/react、chakra-ui/icons、chakra-ui/next-js与chakra-ui/system等 Chakra 系列包同时搭配react-hook-form处理表单、zustand管理全局状态、next-i18next承担国际化。这意味着所有新增组件都应遵守以下基线使用函数式组件Function Component与 React Hooks不使用 Class 组件类型系统使用 TypeScript 严格模式Props 必须显式声明类型UI 基础元素一律取自 Chakra UI不自行封装原生 DOM 样式组件。3.1 组件结构规范审查要点✅ 使用函数式组件和 Hooks✅ 组件使用React.memo优化性能✅ Props 有明确的类型定义✅ 使用 TypeScripttype而不是interface项目约定FastGPT 约定 Props 类型统一使用type关键字而非interface这是为了保持类型声明的统一性并规避 interface 在类型合并declaration merging上的隐式扩展行为。组件定义建议采用「具名函数 React.memo包裹」的写法既保留组件名便于 DevTools 调试又能避免不必要的重渲染。标准模板import React from react; import { Box, Button } from chakra-ui/react; type YourComponentProps { title: string; onClick: () void; disabled?: boolean; }; export const YourComponent React.memo(function YourComponent({ title, onClick, disabled false }: YourComponentProps) { return ( Box Button onClick{onClick} isDisabled{disabled} {title} /Button /Box ); });源码印证在 FastGPT 的共享组件库 packages/web/components 中React.memo与useMemo/useCallback被大量使用。例如 packages/web/components/common/Icon/index.tsx、packages/web/components/common/MyBox/index.tsx 等高频复用组件均采用React.memo包裹说明这套约定并非停留在文档层面而是贯穿整个 Web 端代码库的既有实践。审查 PR 时可重点检查新增组件是否继承了这一写法。3.2 状态管理规范审查要点✅ 本地状态使用useState✅ 全局状态使用 Zustand store✅ 表单状态使用useFormreact-hook-form✅ 复杂状态逻辑使用useReducerFastGPT 对状态管理的分层约定非常清晰按状态作用域选择不同工具避免「什么都往全局 store 里塞」状态类型推荐方案适用场景组件本地状态useState开关、输入值、临时 UI 状态全局共享状态Zustand store用户信息、应用配置、跨页面共享数据表单状态useFormreact-hook-form表单校验、字段联动、受控输入复杂状态逻辑useReducer多步骤流程、状态机式更新源码印证Zustand 的依赖声明位于 packages/web/package.jsonzustand: ^4.3.5而 react-hook-form 则声明在 projects/app/package.json。在 packages/web/store 与 packages/web/context 目录中可以找到全局状态与上下文的实际组织方式表单类页面如知识库数据集创建、应用编排配置面板普遍通过useForm承载字段值与校验逻辑。审查时需确认若某状态仅影响单个组件子树不应提升为全局 store若表单逻辑复杂含联动校验也不应退化为手写useState。3.3 样式规范审查要点✅ 优先使用 Chakra UI props✅ 响应式设计使用 Chakra UI 的断点系统✅ 自定义样式放在styles/theme.ts✅ 避免内联样式为什么禁用内联样式内联样式style{{ ... }}存在三个问题无法参与主题化不能引用primary.600等语义色、无法利用 Chakra 的伪类与断点能力、难以被测试和覆盖。因此规范要求一律使用 Chakra 的语义化 props。正反例对照// ❌ 不好的实践内联样式脱离主题系统 Box style{{ backgroundColor: blue, padding: 16px }} // ✅ 好的实践主题化颜色 间距 token Box bgblue.500 p{4}bgblue.500与p{4}分别映射到主题色板与 4×4px 的间距刻度能够随主题统一变化也天然支持 hover/focus 等伪类样式。主题系统源码解析FastGPT 的自定义主题定义在 packages/web/styles/theme.ts该文件使用extendTheme在 Chakra 默认主题之上扩展了完整的设计体系自定义色板定义了myGray灰阶从myGray.05到myGray.900、primary品牌蓝primary.600为#3370FF、red/green/yellow等语义色以及透明度变体如primary.1 10% 透明度组件样式体系通过defineStyleConfig与createMultiStyleConfigHelpers为 Button、Input、NumberInput、Textarea、Switch、Select、Radio、Checkbox、Modal、Table 等组件定义了统一的size/variant体系例如 Button 提供primary、primaryOutline、whiteBase、dangerFill等十余种 variant全局基础样式在styles.global中统一了html, body的字号、颜色与溢出行为并集中关闭了*的_focusVisible阴影。因此当开发者需要新增自定义视觉样式时正确做法是先检查 packages/web/styles/theme.ts 是否已有可复用的 token 或组件 variant确有需要再通过extendTheme扩展而不是在组件里写死内联样式。3.4 国际化规范审查要点✅ 所有用户可见文本使用t服务端使用i18nT✅ 翻译 key 使用命名空间✅ 动态文本使用插值FastGPT 的国际化遵循「客户端组件用useTranslation的t、服务端/公共层用i18nT标记」的双轨约定。客户端组件用法next-i18nextimport { useTranslation } from next-i18next; const { t } useTranslation(); const message t(user:welcome, { name: userName });服务端 / 非组件层用法i18nTimport { i18nT } from fastgpt/web/i18n/utils; const message i18nT(user:welcome, { name: userName });源码剖析i18nT 的双层实现i18nT在仓库中有两层实现理解其分工有助于正确使用服务端/公共层packages/global/common/i18n/utils.ts 中的i18nT是一个 key 标记函数——它直接返回传入的 key 本身(key: T) key用于在 global/service 层声明可翻译字段并保留字面量类型真正的翻译由前端 i18next 在运行时处理。同文件中的parseLocale负责将浏览器/Cookie/请求头里的语言标签如zh-TW、en_US归一化为 FastGPT 支持的 locale。Web 出口packages/web/i18n/utils.ts 从fastgpt/global/common/i18n/utils重新导出i18nT方便 Web 侧统一引用。翻译 key 统一使用命名空间前缀如user:welcome动态文本一律通过插值{ name }传入参数禁止字符串拼接用户可见文案。FastGPT 的翻译资源按语言组织在 packages/web/i18n 目录下zh-CN、en等语言包新增用户可见文本时应同步补充对应语言的翻译条目。3.5 性能优化规范审查要点✅ 列表渲染使用 key✅ 大列表使用虚拟化✅ 避免在渲染中创建新对象/函数✅ 使用useMemo缓存计算结果✅ 使用useCallback缓存函数FastGPT 的前端以工作流画布、知识库文档列表等重交互、长列表场景为主性能约定因此尤为关键列表 keymap渲染时必须提供稳定且唯一的key优先使用数据 id避免使用数组索引大列表虚拟化超过百级数量的列表项应引入虚拟滚动避免一次性渲染全部 DOM 节点渲染期防抖不要在 render 过程中直接创建对象/数组/箭头函数字面量否则每次渲染都会生成新引用导致React.memo失效、子组件全量重渲染缓存策略计算开销大的派生值用useMemo缓存传给React.memo子组件的回调函数用useCallback稳定引用。反模式示例审查时重点拦截// ❌ 每次渲染都产生新数组与回调引用React.memo 失效 const list items.map(item ({ ...item, extra: compute(item) })); Child onSelect{(id) handleSelect(id)} / // ✅ 用 useMemo / useCallback 稳定引用 const list useMemo(() items.map(item ({ ...item, extra: compute(item) })), [items]); const onSelect useCallback((id) handleSelect(id), []);结合 3.1 组件结构规范 中React.memo的使用useCallback与React.memo是成对出现的优化手段父组件用useCallback稳定回调引用子组件用React.memo跳过无关渲染二者缺一不可。规范在 PR 审查中的落地这份规范文档位于仓库的 .agents/skills/system/pr-review/style/front.md它是 FastGPT PR 审查工作流中「前端代码风格」维度的检查清单由 .agents/skills/system/pr-review 下的审查体系统一调度。配合同目录下的 frontend-quality/typescript.md、frontend-quality/react-performance.md 与 frontend-quality/security.md共同覆盖了类型安全、渲染性能与前端安全三类审查视角。在实际审查中可以按以下顺序快速过一遍新增前端代码结构是否函数式组件 Hooks是否React.memoProps 是否type声明状态状态作用域是否匹配本地/全局/表单/复杂逻辑有无把本地状态错误提升到全局 store样式有无内联样式颜色是否取自主题 token自定义样式是否应沉淀到theme.ts国际化用户可见文本是否全部走t/i18nTkey 是否带命名空间动态内容是否插值性能列表有无 key大列表是否虚拟化渲染中有无新建对象/函数useMemo/useCallback依赖是否正确小结FastGPT 的前端规范可以用一句话概括以 Chakra UI 为主题体系、以 Zustand 与 react-hook-form 划分状态边界、以双轨 i18n 保证多语言、以 memo 族 API 守住渲染性能。无论是为 FastGPT 贡献新组件、扩展工作流节点界面还是参与 PR 审查都可以直接以本文中的模板与检查清单作为操作基准具体的主题 token 与组件 variant 可在 packages/web/styles/theme.ts 中随时查阅扩展。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考