JSONEditor 项目 API 深度解析与使用指南

JSONEditor 项目 API 深度解析与使用指南

jsoneditor A web-based tool to view, edit, format, and validate JSON 项目地址: https://gitcode.com/gh_mirrors/js/jsoneditor

一、JSONEditor 简介

JSONEditor 是一个功能强大的 Web 工具，用于查看、编辑、格式化和验证 JSON 数据。它提供了多种显示模式，包括树形视图、表单视图、代码编辑视图等，能够满足不同场景下的 JSON 数据处理需求。

二、核心 API 详解

1. 构造函数

JSONEditor 通过构造函数初始化：

new JSONEditor(container [, options [, json]])

参数说明：

• container: HTML DIV 元素，作为编辑器容器
• options: 配置对象（可选）
• json: 初始 JSON 数据（可选）

示例：

const container = document.getElementById('jsoneditor');
const editor = new JSONEditor(container, {
  mode: 'tree'
}, { name: 'John' });

2. 主要配置选项

编辑器模式控制

• mode: 设置初始模式，可选值：

  • tree: 树形视图（默认）
  • view: 只读视图
  • form: 表单视图
  • code: 代码编辑器
  • text: 纯文本
  • preview: 预览模式（支持大文件）

• modes: 允许用户切换的模式数组

数据验证

• schema: 指定 JSON Schema 进行验证
• onValidate: 自定义验证函数
• onValidationError: 验证错误回调

验证示例：

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  }
};

const editor = new JSONEditor(container, {
  schema: schema,
  onValidationError: function(errors) {
    console.error('验证错误:', errors);
  }
});

交互回调

• onChange: 内容变化回调
• onEditable: 控制节点可编辑性
• onClassName: 自定义节点 CSS 类
• onNodeName: 自定义节点显示名称

编辑器功能

• search: 启用搜索功能
• history: 启用撤销/重做
• templates: 预定义模板
• autocomplete: 自动完成配置

三、高级功能详解

1. 自动完成功能

JSONEditor 提供了强大的自动完成功能，可通过 autocomplete 选项配置：

const editor = new JSONEditor(container, {
  autocomplete: {
    caseSensitive: false,
    getOptions: function(text, path, input, editor) {
      if (path.length === 0) {
        return ['firstName', 'lastName', 'age'];
      }
      return null;
    }
  }
});

2. 模板功能

通过预定义模板可以快速插入常用 JSON 结构：

const options = {
  templates: [
    {
      text: '用户信息',
      value: {
        name: '',
        email: '',
        address: {
          city: '',
          country: ''
        }
      }
    }
  ]
};

3. 自定义节点样式

使用 onClassName 可以根据节点内容动态设置样式：

function onClassName({ path, field, value }) {
  if (field === 'status' && value === 'error') {
    return 'error-node';
  }
}

const editor = new JSONEditor(container, {
  onClassName: onClassName
});

四、最佳实践

1. 大型 JSON 处理

对于大型 JSON 文档：

• 使用 preview 模式
• 关闭历史记录 history: false
• 禁用搜索 search: false

const editor = new JSONEditor(container, {
  mode: 'preview',
  history: false,
  search: false
});

2. 表单模式应用

表单模式适合配置编辑场景：

const editor = new JSONEditor(container, {
  mode: 'form',
  schema: {
    type: 'object',
    properties: {
      username: { type: 'string' },
      password: { type: 'string' }
    },
    required: ['username', 'password']
  }
});

3. 与 JSON Schema 集成

JSON Schema 提供了强大的数据约束能力：

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 2 },
    age: { type: 'integer', minimum: 0 },
    email: { type: 'string', format: 'email' }
  },
  required: ['name']
};

const editor = new JSONEditor(container, {
  schema: schema
});

五、常见问题解决方案

1. 性能优化：

   • 对于大型文档，优先考虑 preview 模式
   • 延迟加载非必要功能

2. 验证错误处理：

   editor.validate();
   const errors = editor.getValidationErrors();
   

3. 数据获取与更新：

   // 获取数据
   const json = editor.get();
   
   // 更新数据
   editor.set({ new: 'data' });
   

JSONEditor 提供了丰富的 API 和配置选项，能够满足从简单查看到复杂编辑的各种 JSON 处理需求。通过合理配置和组合使用各种功能，可以构建出强大的 JSON 数据处理界面。

jsoneditor A web-based tool to view, edit, format, and validate JSON 项目地址: https://gitcode.com/gh_mirrors/js/jsoneditor