Общие сведения о файле components.json и формате

Общий формат

Общий формат файла components.json:

• В каждом компоненте указаны его свойства. Свойства "components" или "apps" верхнего уровня устарели.

• Каждый компонент имеет свойство "type". Компоненты могут иметь только определенные значения (все возможные значения перечислены в таблице компонентов по умолчанию).

• Каждый компонент имеет свойство "id", которое должно быть уникальным. Это свойство позволяет различать компоненты с одинаковым значением "type". Ранее у приложений было свойство "appName". Хотя свойство "appName" продолжает работать, если свойство "id" недоступно, свойство "appName" устарело.

• Каждый компонент имеет свойство "name", которое служит отображаемым именем в пользовательском интерфейсе. Если резервные значения не указаны, для компонентов данное значение — это имя соответствующего компонента по умолчанию, а для удаленных компонентов значение — идентификатор.

Ниже приведен пример файла components.json:

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                ...
            },
            {
                ...
            },...
        ]
    },
    {
        "name": "My own category name",
        "list": [ ... ]
    }
]

Общая структура представляет собой массив JSON объектов категорий. Каждый объект категории имеет свойства "name" и "list". Свойство "name" может быть ключом, который сопоставляется локализованной строке. Если категорий по умолчанию недостаточно, можно указать собственное имя категории, которое не будет локализовано. В следующей таблице перечислены доступные категории по умолчанию и соответствующие ключи.

Свойство "list" в каждом объекте категории содержит массив объектов компонентов. Каждый компонент или объект должен иметь свойства "type" и "id". Другие свойства не обязательны.

• Свойство "type" должно соответствовать одному из типов компонентов по умолчанию. Если свойства "type" еще нет, компонент не отображается.

• Свойство "id" должно быть уникальным для всех компонентов. Если "id" уже существует, компонент не будет отображаться.

• Свойство "name" — это отображаемое имя компонента в пользовательском интерфейсе. Это заменяет предыдущее свойство "appName" для приложений (теперь удаленные компоненты).

• Все остальные свойства обрабатываются так же, как и в предыдущих версиях.

Добавление новых компонентов в components.json

Изменять компоненты по умолчанию запрещено. Однако на основе существующего компонента по умолчанию можно создать новый компонент. Например, новый компонент можно создать на основе компонента "scs-title", который задает текст по умолчанию. При добавлении нового компонента, как минимум, требуется указать свойства "type" и "id".

• Свойство "type" должно соответствовать одному из типов компонентов по умолчанию. Если свойства "type" еще нет, компонент не отображается.

• Свойство "id" должно быть уникальным для всех компонентов. Если "id" уже существует, компонент не будет отображаться.

Ниже приведен пример кода для добавления нового компонента "Заголовок". Этот компонент будет отображаться вместе с компонентом "Заголовок" по умолчанию.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline"
            }
        ]
    }
]

Ниже приведен пример кода для добавления нового компонента "Заголовок" с отображаемым именем и текстом по умолчанию.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                "initialData": {
                    "userText": "This is a second title component"
                }
            }
        ]
    }
]

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

Обратная совместимость

Файлы components.json в предыдущем формате по-прежнему могут быть прочитаны.

• Файлы со свойствами верхнего уровня "components" или "apps".

• Если файл содержит свойство "apps", пользовательские удаленные компоненты с этим свойством по-прежнему загружаются.

• Если файл содержит свойство верхнего уровня "apps", предполагается, что все удаленные компоненты, перечисленные ниже, имеют тип "scs-app".

• Если свойство "appName" присутствует, задайте свойству "id" значение "appName". Отображаемое имя будет совпадать со значением "name", если оно указано, или вернется к значению "id".