npm package: @glodon-aiot/json-schema-editor
Description: 可视化 JSON Schema 编辑器 React 组件库
Author: Glodon AIoT Team
Latest version: 0.1.0-beta.3

# @glodon-aiot/json-schema-editor

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

[![npm version](https://img.shields.io/npm/v/@glodon-aiot/json-schema-editor)](https://www.npmjs.com/package/@glodon-aiot/json-schema-editor)
[![license](https://img.shields.io/npm/l/@glodon-aiot/json-schema-editor)](./LICENSE)

## 在线文档

[Storybook 文档站](https://glodon-aiot.github.io/json-schema-editor-docs)

## 安装

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

## 快速上手

```tsx
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` | 重置为初始状态 |

```tsx
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（实例级）

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

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

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

完整 CSS 变量列表参见 [Storybook 主题文档](https://glodon-aiot.github.io/json-schema-editor-docs/?path=/docs/theming--docs)。

## 自定义错误文案

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

## 默认值编辑

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

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

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

## 自定义占位文本

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

## 本地开发

```bash
# 克隆仓库（需权限）
git clone git@github.com: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](./CONTRIBUTING.md)。

## 许可证

[MIT](./LICENSE)