NocoBase JsonTextArea 组件详解在表单中编辑 JSON / JSON5 配置【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobaseJsonTextArea是 NocoBasenocobase/client-v2前端包提供的一个 JSON 配置编辑器。它与普通文本域的最大区别在于value/onChange处理的是JS 值对象、数组等而不是字符串编辑时实时解析、失焦blur时自动格式化并触发onChange让“保存 JSON 配置”这类需求在表单里变得类型安全、开箱即用。本文基于仓库中的 JsonTextArea 文档 展开并结合其源码实现与测试用例讲清它的数据流、API 参数、表单集成方式与常见踩坑点。组件定位为“JSON 配置”而生的表单控件在 NocoBase 这类低代码 / 无代码平台中很多业务场景需要把结构化的配置通知规则、流程参数、界面 JSON Schema 等以 JSON 形式存进数据库字段。如果直接用普通Input.TextArea开发者必须自己处理“字符串 ↔ JS 对象”的转换、解析失败时的错误提示、格式化缩进等一系列琐碎问题。JsonTextArea正是为此封装好的开箱即用方案其核心设计理念可以概括为三点以 JS 值为唯一数据源组件对外暴露的value/onChange接收和返回的都是 JSON 对应的 JS 值unknown类型调用方无需关心字符串序列化细节实时解析 失焦提交输入过程中实时解析并校验出现语法错误立即在下方展示错误信息只有 blur 且解析成功后才格式化文本并触发onChange兼容 JSON5通过json5开关启用 JSON5 解析允许尾逗号、单引号、注释等宽松语法降低手工编辑配置的心智负担。在 NocoBase 的组件体系中它隶属于packages/core/client-v2/src/components/form/目录与VariableInput、VariableJsonTextArea等组件共同构成了“表单输入”的能力集合组件统一从 form/index.tsx 对外导出。基本用法组件的最简用法如下对应文档中的 实时预览 Demoimport React, { useState } from react; import { JsonTextArea } from nocobase/client-v2; import { Space, Typography } from antd; export default function JsonTextAreaDemo() { const [value, setValue] useStateunknown({ enabled: true, retry: 3 }); return ( Space directionvertical style{{ width: 420 }} JsonTextArea value{value} onChange{setValue} rows{6} json5 / Typography.Text typesecondary Parsed value: {JSON.stringify(value)} /Typography.Text /Space ); }在上面这个例子中初始值{ enabled: true, retry: 3 }会被序列化为格式化的 JSON 文本展示在文本域里当用户修改文本并失焦后onChange会收到解析后的 JS 对象页面下方的JSON.stringify(value)会同步刷新。在 Ant Design 表单里使用在真实的业务表单中通常与 antd 的Form.Item配合使用字段值直接就是对象import { JsonTextArea } from nocobase/client-v2; Form.Item namecustomConfig label{t(Custom config)} JsonTextArea rows{6} json5 / /Form.Item;由于value/onChange的类型是unknownJSON 可以是任意结构调用方应当按自己的业务约束在Form.Item.rules中追加 validator 来收紧类型。这一点在 client-v2 组件 README 中有明确说明。API 参数详解JsonTextArea在 antdInput.TextArea的基础上新增了以下参数参数类型默认值说明valueunknown-JSON 对应的 JS 值onChange(value: unknown) void-blur 且解析成功后触发spacenumber2序列化缩进json5booleanfalse是否使用 JSON5 解析showErrorbooleantrue是否显示解析错误其余参数rows、disabled、placeholder、maxLength、autoSize等继承自 antdInput.TextArea并原样透传。从源码看其 props 类型定义为// packages/core/client-v2/src/components/form/JsonTextArea.tsx#L17-L23 export interface JsonTextAreaProps extends OmitTextAreaProps, value | onChange { value?: unknown; onChange?: (value: unknown) void; space?: number; json5?: boolean; showError?: boolean; }注意OmitTextAreaProps, value | onChange表明它刻意覆盖了 antd 原始的字符串类型value/onChange以避免调用方误传字符串。参数行为说明space仅影响展示层序列化的缩进宽度。默认2会让组件在 blur 时以每层 2 个空格重新格式化文本在 JsonTextArea.test.tsx 中可以看到对象{ foo: bar }会被渲染成{\n foo: bar\n}。json5决定使用JSON5还是原生JSON进行解析与序列化。开启后允许尾逗号、单引号、注释等 JSON5 语法底层实现是const json json5 ? JSON5 : JSON;见 JsonTextArea.tsx所有 parse / stringify 都通过这个统一入口。showError解析失败时是否在输入框下方渲染红色错误文本Typography.Text typedanger。即使关闭blur 时的校验与onChange抑制逻辑依然生效只是不展示错误文案。源码实现深入理解数据流打开 JsonTextArea.tsx可以看到一个精心设计的状态机理解它有助于在实际使用中预测组件行为。1. 文本与 JS 值的双向映射组件内部维护两个状态text文本域当前展示的字符串初始值通过stringifyJsonValue(value, json, space)由 JS 值序列化而来error当前解析错误信息。当外部value变化时通过useEffect重新同步text见 JsonTextArea.tsx保证受控组件的一致性。stringifyJsonValue还有一个细节当value是字符串且能通过json.parse时会原样保留该字符串不二次序列化避免无谓的格式改动JsonTextArea.tsx。2. 输入时实时校验handleChange在用户每次输入时更新text并调用validateText尝试解析解析失败时把错误信息存入error状态JsonTextArea.tsx。空字符串被parseText视为null不会报错。3. 失焦时格式化并提交handleBlur是核心逻辑JsonTextArea.tsxtry { const parsed parseText(event.target.value); setError(undefined); setText(parsed null ? : json.stringify(parsed, undefined, space) ?? ); onChange?.(parsed); } catch (err) { setError(err instanceof Error ? err.message : String(err)); }可以看到解析失败时既不会触发onChange也不会覆盖用户输入而是展示错误信息解析成功时会把文本重新格式化为缩进规范space指定的空格数的 JSON再把解析后的 JS 值交给onChange。这也是文档中“blur 时会格式化并触发 onChange”这一描述的源码级印证。4. 错误状态与 UI 呈现mergedStatus status || (error ? error : undefined)会把解析错误联动到 antd 输入框的 error 状态样式若showError为true且存在error则在下方渲染红色错误文案JsonTextArea.tsx。组件还内置了等宽字体样式Consolas、Monaco 等字体栈与autoSize最小 5 行、最大 10 行等体验细节。测试用例验证行为即规范仓库为JsonTextArea提供了完整的行为测试位于 JsonTextArea.test.tsx可以当作组件行为的“规范文档”来读格式化对象值并在 blur 时输出解析后的 JSON渲染value{{ foo: bar }}后断言文本为{\n foo: bar\n}随后change为{foo:baz}并blur断言onChange收到{ foo: baz }且文本被格式化为{\n foo: baz\n}测试用例 L16-L29解析失败不输出非法值输入{后 blur断言onChange从未被调用且页面中出现包含JSON的错误文本测试用例 L31-L42。这两个用例恰好覆盖了组件最核心的两条行为契约“合法 JSON 一定格式化并回传 JS 值”“非法 JSON 一定拦截且不污染表单值”。进阶需要插入变量时使用 VariableJsonTextArea如果 JSON 配置里需要插入运行期变量例如{{ $env.API_ENDPOINT }}则应使用基于本组件扩展的VariableJsonTextArea。它继承了JsonTextArea的全部能力并在右上角叠加了一个变量选择按钮选中变量后会把{{ ... }}表达式插入当前光标位置见 VariableJsonTextArea.tsx 的insertAtCaret实现。import { VariableJsonTextArea } from nocobase/client-v2; VariableJsonTextArea json5 rows{8} namespaces{[$env, $user]} value{{ endpoint: {{ $env.API_ENDPOINT }} }} onChange{(value) { console.log(value); }} /;完整的可运行示例包含通过插件在 Flow Engine 上下文中注册$env、$user属性树的代码见 variable-json-text-area Demo。它的 API 文档位于 variable-json-text-area.md额外支持namespaces限定变量选择器的顶层命名空间、extraNodes追加局部变量节点、metaTree完全自定义变量树与formatPathToValue自定义变量路径格式化等参数。选择建议如果配置里不需要变量直接用JsonTextArea更简单只有确实需要动态引用环境变量、当前用户等信息时才升级到VariableJsonTextArea。实践建议与注意事项综合文档、源码与测试使用JsonTextArea时有几点值得留意不要在onChange中依赖字符串onChange回调收到的是解析后的 JS 值可能是对象、数组、数字或null如果需要字符串形式请自行JSON.stringify空值语义空文本会被解析为null并通过onChange回传value为null/undefined时文本域显示为空字符串类型约束靠表单规则组件的值类型是unknown业务层面的结构校验如“必须是数组”“必须有某字段”请放在Form.Item.rules的 validator 中实现JSON5 按需开启默认走严格 JSON 解析如果业务配置经常手写且希望容忍尾逗号、单引号、注释再设置json5为true组件导出位置JsonTextArea与VariableJsonTextArea均从nocobase/client-v2的 form 模块导出form/index.tsxVariableJsonTextArea还以VariableJSON为别名导出。相关资源JsonTextArea 官方文档中文VariableJsonTextArea 官方文档中文JsonTextArea 源码实现JsonTextArea 行为测试client-v2 组件总览 README【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考