@glodon-aiot/json-schema-editor

可视化 JSON Schema 编辑器 React 组件库，支持字段管理、嵌套结构、类型校验与主题定制。

在线文档

Storybook 文档站

安装

npm install @glodon-aiot/json-schema-editor

快速上手

import { JsonSchemaEditor } from '@glodon-aiot/json-schema-editor'
import '@glodon-aiot/json-schema-editor/dist/style.css'

function App() {
  const [fields, setFields] = useState([])

  return (
    <JsonSchemaEditor
      value={fields}
      onChange={setFields}
    />
  )
}

功能特性

• 可视化编辑：通过 UI 操作增删字段、设置类型和描述
• 类型支持：String、Number、Integer、Boolean、Object（可嵌套）、Array（含 Items 配置）
• 嵌套结构：支持最多 5 层嵌套（maxDepth 可配置）
• 默认值编辑：根级字段支持展开详情面板设置 default 值，输入控件随字段类型自适应
• 字段校验：字段 key 格式校验、自定义错误提示文案
• 外部触发校验：通过 ref.current.validate() 命令式触发
• 命令式 API：addField、getFields、reset 等
• 受控 / 非受控：同时支持 value 受控和 defaultValue 非受控两种模式
• 主题定制：通过 theme prop 或 CSS 变量覆盖颜色、圆角、字号
• 无障碍：WCAG 2.1 AA，ARIA 属性，完整键盘导航支持

API

JsonSchemaEditor Props

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | value | FieldNode[] | — | 受控模式：字段列表 | | defaultValue | FieldNode[] | [] | 非受控模式：初始字段列表 | | onChange | (fields: FieldNode[]) => void | — | 字段变更回调 | | onError | (errors: ValidationError[]) => void | — | 校验失败回调 | | addButtonPosition | 'top' \| 'bottom' \| 'hidden' | 'top' | 添加字段按钮位置 | | validateTrigger | 'onBlur' \| 'onChange' \| 'manual' | 'onBlur' | 校验触发时机 | | maxDepth | number | 5 | 最大嵌套深度 | | disabled | boolean | false | 是否禁用编辑 | | messages | Partial<JsonSchemaEditorMessages> | — | 自定义错误提示文案 | | theme | Partial<JsonSchemaEditorTheme> | — | 主题配置 | | placeholders | Partial<JsonSchemaEditorPlaceholders> | — | 输入框占位文本 | | className | string | — | 根元素额外 class | | style | React.CSSProperties | — | 根元素额外样式 |

JsonSchemaEditorRef 命令式方法

| 方法 | 签名 | 说明 | |------|------|------| | validate | () => ValidationError[] | 触发校验，返回错误列表 | | addField | (field?: Partial<FieldNode>, position?: 'top' \| 'bottom') => void | 命令式添加字段 | | getFields | () => FieldNode[] | 获取当前字段列表 | | reset | () => void | 重置为初始状态 |

const ref = useRef<JsonSchemaEditorRef>(null)

// 触发校验
const errors = ref.current?.validate()

// 命令式添加字段
ref.current?.addField({ key: 'userId', type: 'string' }, 'top')

路径格式

所有涉及字段路径的 API 使用点分隔字符串：

• "name" — 根级字段
• "user.email" — 嵌套字段
• "tags.items" — Array 的 Items 节点

主题定制

方式一：theme prop（实例级）

<JsonSchemaEditor
  theme={{
    colorPrimary: '#1677ff',
    colorError: '#ff4d4f',
    borderRadius: '6px',
  }}
/>

方式二：CSS 变量（全局覆盖）

:root {
  --jse-color-primary: #1677ff;
  --jse-color-error: #ff4d4f;
  --jse-border-radius: 6px;
  --jse-font-size-base: 14px;
}

完整 CSS 变量列表参见 Storybook 主题文档。

自定义错误文案

<JsonSchemaEditor
  messages={{
    required: '字段名不能为空',
    invalidKey: '字段名只能包含字母、数字和下划线',
    duplicateKey: '字段名已存在',
  }}
/>

默认值编辑

根级字段（第一层）行右侧有 ≡ 按钮，点击后展开详情面板，可为字段设置 default 值：

| 字段类型 | 输入控件 | |---------|---------| | string | 文本输入框 | | number / integer | 数字输入框 | | boolean | 下拉（未设置 / true / false） | | object / array | JSON 文本区（失焦时校验格式） |

默认值会写入生成的 JSON Schema 的 default 关键字。

自定义占位文本

<JsonSchemaEditor
  placeholders={{
    key: '字段名',
    description: '字段描述（可选）',
  }}
/>

本地开发

# 克隆仓库（需权限）
git clone [email protected]:glodon-aiot/json-schema-editor.git
cd json-schema-editor

# 一键初始化（安装依赖 + git hooks + gitleaks）
npm run setup

# 启动 Storybook
npm run storybook

# 运行测试
npm test

# 构建组件库
npm run build

贡献指南

请阅读 CONTRIBUTING.md。

许可证

MIT