Данный проект представляет собой редактор JSON на основе antd, который позволяет использовать ограничения JSON Schema. Он ориентирован на редактирование JSON и поддерживает различные функции JSON Schema, включая сложные комбинации. В отличие от других подобных продуктов, он поддерживает вложенные структуры oneOf/anyOf и комбинированные функции $ref, а также поддерживает множество вариантов использования различных функций.

Предварительный просмотр и документация

Страницы GitHub

Страницы Gitee

Использование и функциональность

Как обычно, сначала выполните npm install:

npm install json-schemaeditor-antd

Затем импортируйте его в свой jsx:

const JsonSchemaEditor, { metaSchema } = 'json-schemaeditor-antd'

// metaSchema is the meta mode, if you don't need to use the meta mode to edit the Json Schema, you can skip importing it

<JsonSchemaEditor data={data} schema={schema}
  onChange={(jsonData) => {
    console.log(jsonData)
  }}
/>

Компонент имеет три свойства: data, schema и onChange: (value: any) => void.

Используйте его как контролируемый компонент. Если вам нужен пакет в формате umd, вы можете импортировать json-schemaeditor-antd/dist.

Обратите внимание:

1. Убедитесь, что установлены все необходимые зависимости. Вы можете проверить это непосредственно в файле package.json проекта.

2. При использовании, если schema ts выдаёт ошибку, добавьте as any после неё, и всё будет в порядке. Вы должны самостоятельно убедиться в правильности схемы перед использованием. Этот проект использует ajv для проверки и подтверждения схемы. Если в схеме есть проблемы, вы увидите окно с ошибкой, и редактор будет отображаться без схемы.

   Я провёл первоначальное расследование и обнаружил несколько причин:

   • Для поля type значение JSONSchema6TypeName является допустимым значением типа перечисления в JSON Schema. Обычно импортированный json определяет поле type как тип string, а не значение перечисления (хотя json действительно соответствует), и выдаёт ошибку.

3. Изменения состояния соответствуют соглашению о неизменности.

Я новичок в разработке фронтенда, и это мой первый опыт упаковки и загрузки npm. Возможно, при реальном использовании возникнет много проблем.

Если вы обнаружите ошибки в этом проекте или у вас есть какие-либо предложения или обнаружите недостатки в дизайне, пожалуйста, не стесняйтесь создавать issue! Я постараюсь решить их как можно скорее.

Компонент Editor и ref

Компонент Editor предоставляет глобальный контекст ctx через useImperativeHandle.

Вы можете получить доступ к хранилищу redux через ctx.store;

Вы можете выполнять действия для изменения данных через ctx.executeAction(type, params);

Функции и параметры, связанные с ctx, можно найти в src/JsonSchemaEditor/context/index.ts.

Для получения дополнительной информации о доступных действиях см. раздел Reducer.

Идентификаторы всех полей

Каждый компонент поля имеет атрибут id, соответствующий ему, через который можно получить корневой элемент dom этого поля. Например, rootdata.user.abc[1] имеет идентификатор user.abc.1.

Обратите внимание:

1. Идентификатор корневого узла определяется переданным идентификатором редактора и не имеет префикса.
2. В настоящее время ни id, ни schemaEntry не выполняют обработку экранирования. Пожалуйста, не добавляйте символы . или / в имена атрибутов, иначе это вызовет ошибку.
3. Вы можете указать префикс компонента через options.idPerfix. Префикс будет добавлен непосредственно перед строкой идентификатора без разделителя. (Не реализовано)
4. Некоторые компоненты поля могут не отображаться на экране или быть скрыты, поэтому вы не сможете получить их элементы dom через id.

Опции (не реализованы)

В большинстве случаев вам не нужно ничего настраивать.

idPerfix, defaultValueFunction,

schemaDefault

Это поле используется для указания значения по умолчанию для функции, определённой редактором. Вы также можете указать их в конкретном поле схемы, чтобы переопределить значения по умолчанию, установленные схемой.

displaydesc, notinautofill

draggable

Может ли элемент массива быть перемещён. Даже если установлено значение true, перетаскивание ограничено элементами в схеме.

type: boolean

default: true

ui

denseGrid,

Краткое введение в JSON Schema

JSON Schema — это рекурсивная грамматика, которая описывает, какими свойствами должен обладать файл JSON. В этом проекте используется версия спецификации draft6.

Введение в JSON Schema - Zhihu (zhihu.com)

Далее кратко описывается определение JSON Schema и различия между ним и этим редактором:

• Функция проверки полностью реализована с помощью ajv.
• Кроме того, этот редактор определяет некоторые новые ключевые слова JSON Schema для дальнейшей настройки пользовательского интерфейса. Эти новые определения ключевых слов не влияют на проверку данных JSON. Вы можете найти конкретные ключевые слова и их влияние на пользовательский интерфейс в определении ключевых слов ниже. Схема: определение типа схемы

Примечание: если схема имеет логическое значение, то она напрямую соответствует определению того, действительна ли переменная. true или {} — любое значение действительно. false или {"not": {}} — любое значение недействительно.

Логическое значение / null

null не нужно отображать.

Число / целое число

Строка

https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.3

Массив

type — «массив».

https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.4

Оптимизация короткого массива:

Если все возможные элементы массива items являются только строкой/числом/логическим значением/нулем, и строка не использует длинный режим, массив будет использовать список коротких режимов для уменьшения пространства отображения и оптимизации.

Объект

проект 2020-12 проект 6

Схема определяет вложенный объект, чтение атрибутов — root.layer1.layer2, но чтение соответствующей схемы — root.properties.layer1.properties.layer2. Каждый слой атрибутов добавляет один слой properties.

В дизайне по умолчанию есть только обязательные атрибуты, затем выберите дополнительные атрибуты в поле выбора. Атрибуты могут быть добавлены позже. dependencies не устанавливает никаких специальных настроек для атрибутов выбора, а просто запрещает выбор недоступных атрибутов.

Проверка не конфликтует.

Что касается встраивания схемы в пользовательский интерфейс, это позволяет поддерживать согласованность. Однако, учитывая использование других схем пользовательского интерфейса, я считаю, что схемы пользовательского интерфейса не должны использоваться вместе. JSON Schema: версии и их различия

Версии широко используемой JSON Schema можно найти на сайтах:

• Specification | JSON Schema (json-schema.org);
• Specification Links | JSON Schema (json-schema.org).

Согласно спецификации, в настоящее время широко используются следующие версии: 2020-12, 2019-09, draft-07, draft-06, draft-04.

Вот таблица совместимости версий:

По умолчанию приложение поддерживает draft 6 и draft 7 как используемые схемы. Для более старых схем, таких как draft 4, необходимо использовать инструменты, такие как ajv-cli, для преобразования в более новые версии схем.

В демоверсии $schema.eslint.json — это схема, преобразованная из draft 7.

Однако редактор не предоставляет автоматического способа перехода к более новым версиям схем (хотя в будущем такая возможность может появиться).

Концепция дизайна

Гипотезы о шаблонах

Редактор использует схему для индивидуальной настройки пользовательского интерфейса, но чтобы этот процесс работал должным образом, схема должна соответствовать следующим предположениям:

1. Шаблон не меняется во время редактирования.
2. Все свойства, помеченные как «обязательные», присутствуют в разделе «свойства».
3. После установки типа свойства применяются ограничения этого типа.
4. Свойства oneOf, anyOf, enum и const не могут присутствовать одновременно.
5. Если есть свойства oneOf или anyOf, их параметры не должны образовывать циклические ссылки. Кроме того, если есть вложенные слои oneOf и anyOf, не должно быть повторяющихся ссылок.
6. Разделы «свойства» и «patternProperties» не должны соответствовать одному и тому же имени.
7. Если используется несколько схем для проверки, то должно выполняться предположение о замене. В противном случае некоторые функции могут работать некорректно. Подробнее см. раздел «Использование нескольких схем».

Короткие поля

В разделах «объект» и «массив» многие поля занимают мало места. Если можно определить эти поля с помощью схемы и отобразить их в виде сетки, можно значительно повысить эффективность использования пространства. Такие поля называются короткими полями. Вот критерии определения коротких полей:

Поле должно соответствовать следующим условиям, чтобы считаться коротким полем: — только один возможный тип; — нет параметров oneOf/anyOf.

Если поле соответствует этим условиям, оно считается коротким полем, если удовлетворяет следующим правилам:

1. Формат поля — короткий формат строки. Это короткое поле (самый высокий приоритет).
2. Если поле имеет ключевое слово view (используется настраиваемый компонент view), решение о том, является ли оно коротким полем, зависит от свойства shortable в определении view.
3. Если тип поля — integer/number, boolean/null или enum/const, и используется стандартный компонент для отображения, поле считается коротким полем.

Короткие поля могут быть плотно размещены в виде сетки в объектах и массивах, что позволяет использовать меньше места для отображения по сравнению с длинными полями и повышает эффективность использования экрана.

Операционное пространство для коротких полей находится в правой части кнопок. При нажатии кнопки можно выбрать операцию и выполнить её.

Можно доказать, что все вложенные форматы, кроме enum/const/настраиваемых компонентов view, являются длинными полями.

Обратите внимание, что настраиваемые компоненты view...

Операционное пространство (операции, которые можно выполнять)

Здесь перечислены не все операции, а только некоторые из них. Некоторые операции не являются универсальными, например создание и переименование. Подробности смотрите по ссылкам.

Копирование и вставка (в разработке)

В режиме списка можно скопировать несколько элементов (создать массив) и вставить их в список по очереди.

При вставке выполняется поверхностная проверка.

Отмена и возврат

Это просто операции отмены и возврата. Однако для их реализации требуется хорошее понимание React и Redux!

Поверхностная проверка

Схема выполняет простую и быструю проверку данных. По сравнению со всей схемой проверки она занимает меньше времени. Вот как это работает:

1. Если схема содержит константы или перечисления, возвращается результат проверки этих ключевых слов.
2. Если в схеме определён уникальный тип и он совпадает с типом данных, выполняются следующие действия: — если данные являются объектом, проверяется значение каждого обязательного поля в схеме; — если данные представляют собой массив, проверяется каждое поле элемента массива; — при проверке внутренних полей объекта или массива, если эти поля также являются объектами или массивами, проверяется только их тип, без дальнейшей рекурсивной проверки внутренних полей; — если данные имеют строковый тип и имеют атрибут формата, проверяется соответствие формата; — для других типов, если они совпадают, возвращается true.

Примечание: поверхностная проверка не проверяет поля, определённые как oneOf/anyOf, и сразу возвращает true.

Интерфейс компонента

Каждому полю соответствует компонент Field. Фактический компонент, используемый для отображения поля, определяется функцией getEditComponent.

Фактический компонент может выполнять следующие операции через интерфейс IField: — получить путь к полю; — получить данные поля; — получить объединённую схему поля.

Дополнительная информация

ajv и его конфигурация

Этот редактор использует ajv для проверки достоверности, но на основе конфигурации ajv по умолчанию добавлены следующие настройки: — добавлены методы проверки некоторых форматов с помощью ajv.addFormat(); — добавлены будущие соединения (не реализованы).

Шаблоны для шаблонов — меташаблоны

Описание схемы JSON называется меташаблоном. Меташаблон используется для проверки правильности схемы JSON.

Проект использует шаблон draft6 в качестве меташаблона, но для удобства редактирования проект расширяет меташаблон и добавляет некоторые общие соглашения с некоторыми ограничениями. Смотрите экспортированный metaSchema.

Внимание к нескольким схемам

В некоторых случаях необходимо проверить данные с использованием нескольких схем. Это происходит в следующих ситуациях: — используется $ref; — одно свойство соответствует свойствам и patternProperties; — oneOf, anyOf, allOf.

Настройка редактора заключается в том, что каждый шаблонный вход ссылается на шаблонное отображение в виде карты ($ref, schemaInfo), хранящейся в контексте редактора ctx.

Предположение о замене

Когда дело доходит до нескольких объектов схемы, результатом проверки схемы является объединение результатов проверки всех связанных схем (с использованием логического оператора «и»).

Для шаблона, который имеет $ref и связан с несколькими объектами схемы, предполагается, что его поведение такое же, как если бы связанные схемы были объединены. Объединение выполняется с использованием object.assign, где свойства $ref заменяются свойствами связанного шаблона.

Если вы используете шаблон с $ref, который связан с несколькими шаблонами, и эти шаблоны имеют одинаковые или разные свойства проверки, результаты будут отличаться от тех, которые соответствуют предположению о замене.

Обычно, если вы не делаете это намеренно, вы не будете этого делать.

Что касается шаблонов с $ref, лучше всего, чтобы $ref не включал никаких свойств проверки. Самое большее, что вы можете сделать, это включить свойства title и description для замены значений этих свойств в связанном шаблоне.

Исключением из предположения о замене в редакторе является поддержка пользовательского интерфейса: свойства и patternProperties не заменяют друг друга. Если корневой узел в схеме определён как массив и его фактический тип также является массивом, то данные будут отображаться в виде двухколоночного списка. В левой колонке можно перетащить и выбрать несколько элементов для копирования и вставки. (Пока не реализовано).

string

Формат строки

https://ajv.js.org/packages/ajv-formats.html

Примечание: некоторые форматы специализированных компонентов редактирования ещё не реализованы, но проверка всё равно работает.

В формате строки format устанавливается. Кроме того, были добавлены другие форматы:

Некоторые форматы строк не поддерживают оптимизацию по длине, поэтому они отображаются как длинные компоненты. Длинные форматы делятся на две категории: однострочные длинные форматы longFormats и многострочные длинные форматы extraLongFormats.

Однострочные длинные форматы по-прежнему отображаются в одной строке, но длина увеличивается. Многострочные длинные форматы отображаются на новой строке и могут занимать несколько строк.

На данный момент существует проблема с форматами:

Проверка формата может быть функцией или регулярным выражением. Честно говоря, формат, помимо того, что он делает, должен быть переопределён. Формат должен иметь функцию проверки и значение по умолчанию. Зачем нужно значение по умолчанию? Если у вас есть поле с oneOf, каждый вариант соответствует определённому формату строки. Если вы переключаетесь, а формат по умолчанию не установлен, вы теряете данные. Замена пустой строкой не поможет вам определить, какой элемент был выбран.

number/integer/boolean/null

• Обязательно короткие поля.

Пользовательский вид (только дизайн)

В схеме можно использовать view через поле view:

{
  "view": {
    "type": "your_view_type",
    "params": {
      "any": "any"
    }
  }
}

Можно создать собственный компонент json-schemaeditor и опубликовать его в npm. Таким образом, при использовании json-schemaeditor можно использовать пользовательские компоненты view, настроив файл конфигурации json-schemaeidtor.json (использовать ли json-пакет или требовать js).

Примечание: пользовательские компоненты вида отличаются от пользовательских компонентов формата строки тем, что они не ограничиваются использованием в строковом типе.

Пользовательские компоненты вида

Пользовательские компоненты вида должны быть настроены следующим образом:

1. Условия действительности данных этой конфигурации должны соответствовать типу схемы, чтобы указать, какие компоненты можно редактировать с помощью этого компонента.
2. Условия действительности конфигурации должны соответствовать типу схемы и указывать, какими должны быть параметры view.
3. Информация о компоненте включает в себя класс типа компонента type (это значение поля view type), информацию о состоянии короткой оптимизации компонента (short/long/extralong).

{
  "type": "your_view_type"
}

Затем добавьте некоторые соглашения о каталогах...

Встроенные компоненты вида

• Корневой список (реализован, но не абстрагирован в view).
• Корневая папка.
• Кривая.
• Градиент.
• Визуализация диаграммы.
• ...

Reducer

Компоненты редактора используют useImperativeHandle для раскрытия хранилища, которое можно получить и напрямую отправить действие для изменения. Ниже описаны основные действия:

// Пример: добавление поля 1 в подарки со значением { "name": "gold", "number": 10 }
const action = {
  type: 'create',
  route: ['gifts'],
  field: '1',
  value: {
    name: 'gold',
    number: 10
  }
}

Для компонента Field доступ к себе осуществляется через access, доступ к родительскому элементу — через route, а доступ к дочернему элементу — через access+sfield.

Обратите внимание, что после отправки действия в reducer выполняется только проверка того, можно ли выполнить действие непосредственно на уровне json, но не проверка на уровне схемы. Если действие, отправленное в reducer, не может быть выполнено, будет выведено сообщение об ошибке.

Тестирование проекта

Текущее тестирование проекта (модульное тестирование, интеграционное тестирование и т. д.) не завершено, оно охватывает только основной поток и имеет покрытие около 70%.

Мы постараемся исправить это как можно скорее.

Другие проблемы

Окружение

После последнего обновления npm этот проект использует dumi в качестве среды разработки.

Хотя dumi также имеет некоторые недостатки, он всё ещё является надёжным решением для разработки библиотек компонентов.

antd

Этот проект не упаковывает antd, а использует собственные зависимости antd.

antd можно упростить с помощью babel, и этот проект использовал эту функцию. Однако по неизвестной причине (возможно, из-за конфигурации упаковки, но она не была тщательно исследована), импорт пакета проекта не загружает css-файл antd вместе, необходимо вручную загрузить полный antd.css, чтобы применить стили (если используется umi или аналогичные фреймворки, фреймворк автоматически загрузит его за вас).

Кроме того, используемый в проекте antd зависит от используемого вами antd темы. При разработке использовалась компактная тема.

При тестировании проекта можно нормально импортировать и применять этот компонент в среде umi.

Конфигурация для индивидуальной разработки

Запишите конфигурацию для индивидуальной разработки, которая может служить ориентиром при возникновении проблем.

v0.1.4 до: os: windows 11 nodejs v14.18.0 npm v6.14.15

v0.1.4: os: windows 11 nodejs v16.14.2 npm v8.5.0

Неразрешённые проблемы

• Часть стилей требует улучшения.
• Реакция на изменение столбца отображения коротких оптимизированных элементов (но нельзя использовать antd list response напрямую, он учитывает только ширину окна, а не ширину dom).
• Не очень хорошо, если нет значения по умолчанию для настройки без значения по умолчанию.
• Специальные символы в экранированных именах свойств.
• Завершение тестирования.

Будущие обновления

Здесь можно свободно выражать свои мысли, но всё, что можно сделать, можно сделать. Можно ли реализовать или никогда не узнать.

• Описать функции, которые ещё предстоит реализовать.
• Поддержка order и dependence.
• Возможность чтения внешних схем и сетевых схем, возможность прямого чтения или обработки через интерфейс.
• json-pointer для перехода.
• Меню и соответствующие функции (текущий дизайн также не ясен).
• Список страниц + виртуальный список.
• Бесшовный переход с клавиатуры и фокус.
• Самопроверка формата и генерация значений по умолчанию.
• anchor.
• Действия с побочными эффектами, позволяющие панели выполнять реальные операции.
• Локальное редактирование навигации (маршрутизация) по хлебным крошкам.
• Если возможно, поддержка xml/yaml/bson, а также нестандартных jsonschema (в будущем, возможно, даже будет предложен улучшенный черновик схемы).
• Вставка файлов и отображение файлов через интерфейс.
• Совместимость с более ранними версиями схемы (на данный момент её можно решить только путём перехода на более новую версию схемы). Некоторые аспекты экосистемы json-schema: популярные коллекции json-schema доступны по ссылке: https://www.schemastore.org/json/.

[npm-image] [npm-url] [quality-image] [quality-url] [node-url] [download-image] [download-url]