@composy/json-editor-core

@composy/json-editor-core

@composy/json-editor-core 是一款框架无关的 JSON 可视化编辑器核心库，由 JSON Schema 驱动，默认提供 树形视图 与 代码视图 两种模式。它内建 JSON 解析与还原（树形节点模型）、Schema 校验、撤销/重做历史记录、主题系统、搜索高亮与展开/折叠控制，并通过 DOMRenderer 将节点渲染到宿主 DOM。核心采用「类实例 + 事件」架构：JsonEditor 接收 DOM 容器挂载实例，对外暴露完整的命令式 API（getValue/setValue/validate/undo/search 等），可无缝融入 Vue、React 或原生 JS 项目，附带完整的 TypeScript 类型定义。

安装

# pnpm
pnpm add @composy/json-editor-core
# npm
npm install @composy/json-editor-core

目录结构

packages/core/
├── .ldesign/
│   ├── builder.config.ts       # @composy/builder / rolldown
│   ├── tsconfig.esm.json       # ESM 类型检查
│   └── tsconfig.cjs.json       # CJS 类型检查
├── src/
│   ├── index.ts              # 公共入口，导出核心、解析器、主题、渲染器
│   ├── types/                # 类型定义（JsonNode、JsonSchema 等）
│   ├── core/
│   │   ├── json-editor.ts    # JsonEditor 主类 + createJsonEditor 工厂
│   │   ├── event-emitter.ts  # EventEmitter 事件系统
│   │   ├── history-manager.ts# HistoryManager 撤销/重做
│   │   ├── schema-validator.ts# SchemaValidator + validateValue 校验
│   │   └── json-parser.ts    # JSON 解析/还原、节点搜索等
│   ├── renderer/
│   │   ├── dom-renderer.ts   # DOMRenderer 树/代码渲染
│   │   └── style-manager.ts  # 样式注入/移除（injectStyles / removeStyles）
│   └── theme/
│       ├── theme-manager.ts  # ThemeManager 主题切换
│       └── tokens.ts         # ThemeTokens、lightTokens / darkTokens
├── package.json
├── tsconfig.json             # 指向 .ldesign/tsconfig.esm.json 的兼容入口
└── tsconfig.cjs.json         # 指向 .ldesign/tsconfig.cjs.json 的兼容入口

核心 API 详表

类（Class）

函数（Function）

类型（Type / Interface）

常量

使用示例

import { createJsonEditor } from '@composy/json-editor-core'

// 创建编辑器，挂载到 DOM 容器
const editor = createJsonEditor({
  container: '#app',
  value: { name: 'LDesign', tags: ['json', 'editor'], count: 3 },
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      count: { type: 'number', minimum: 0 },
    },
  },
  theme: 'light',
  mode: 'tree',
})

// 命令式 API：读写与校验
editor.getValue() // 当前 JSON 值
editor.setJson('{"key": "value"}') // 以 JSON 字符串设置
editor.validate() // Schema 校验

// 视图与历史控制
editor.setMode('code') // 切换代码视图
editor.setTheme('dark') // 切换主题
editor.expandAll() // 全部展开
editor.undo() // 撤销 / redo() 重做

// 搜索与销毁
editor.search('editor') // 搜索并高亮
editor.destroy() // 释放 DOM 与事件

构建脚本 & 验证命令

pnpm run type-check    # ESM TypeScript 类型检查
pnpm run type-check:cjs # CJS TypeScript 类型检查
pnpm run build         # 构建（ldesign-builder build）
pnpm run lint          # ESLint 检查
pnpm run lint:check    # ESLint 严格检查（--max-warnings 0）
pnpm run lint:fix      # ESLint 自动修复
pnpm test              # 单元测试（ltesting run:unit）
pnpm run test:coverage # 带覆盖率测试
pnpm run release       # 发布（ldesign-release publish --package-dir .）

产物说明

• es/：ESM 产物（index.js + index.d.ts），"module" 与 "import" 入口。
• esm/：保留源码模块结构的 ESM 产物与声明文件。
• lib/：CJS 产物（index.cjs），"main" / "require" 入口，兼容 Node 环境。
• dist/：浏览器 UMD 与压缩产物（index.js、index.min.js），unpkg / jsdelivr 指向压缩入口。
• exports 提供子路径：@composy/json-editor-core/core/*、/renderer/*、/theme/*、/types 与 /types/*。

备注

• peer 依赖：核心库为框架无关，运行时无强制 peer 依赖；开发依赖使用 @composy/builder、@composy/testing、@composy/release。
• 浏览器环境：JsonEditor、DOMRenderer、样式注入依赖 DOM / navigator.clipboard，需在浏览器中运行；服务端无法使用渲染相关 API。
• 发布源：publishConfig.registry 指向私有 npm 源 http://npm.longrise.cn:6286/。
• 包声明 sideEffects: false，可安全参与 tree-shaking。
• 当前 SchemaValidator 为简化实现，覆盖 JSON Schema 常用关键字；$ref 解析与复杂关键字的能力以实际实现为准。