Smart-компоненты ui.*

Smart-компоненты ui.* — готовые элементы интерфейса из SIMAI Framework: кнопка, уведомление, поле ввода и другие. В Markdown они вызываются блоком :::ui.имя с параметрами в JSON. Docara сверяет параметры с описанием компонента ещё при сборке, а в браузере компонент работает так же, как в других продуктах на SIMAI Framework.

Чем они отличаются от обычных компонентов Docara:

• обычный компонент, например уведомление :::alert, пишется Markdown-текстом и подходит для большинства страниц;
• Smart-компонент принимает параметры именно так, как их описывает Framework, и нужен, когда на странице должен быть настоящий элемент Framework: кнопка с состоянием загрузки, уведомление с заголовком и поясняющим текстом и т. п.

Как сайт разрешает компоненты

Сайт может вызвать только те Smart-компоненты, которые перечислены в файле simai-framework.lock.json рядом с docara.json, в разделе manifests. Для каждого компонента там закреплены поставщик, точная версия и контрольная сумма его описания, а также ограничения для статического сайта:

{
  "manifests": {
    "ui.button": {
      "provider": "larena/ui",
      "provider_revision": "4b055d09926fec4c32f2ae43b2e7e0a6f64d7663",
      "sha256": "235e049d…"
    },
    "ui.alert": {
      "provider": "larena/ui",
      "provider_revision": "4b055d09926fec4c32f2ae43b2e7e0a6f64d7663",
      "sha256": "056329bb…",
      "consumer_policy": {
        "blocked": [
          {"prop": "closable", "value": true, "code": "FRAMEWORK_PROP_UNSUPPORTED_IN_BOUNDED_RUNTIME"},
          {"prop": "type", "value": "success", "code": "FRAMEWORK_PROP_UNSUPPORTED_IN_BOUNDED_RUNTIME"}
        ]
      }
    }
  }
}

Файл создаёт docara init; обновление Docara его не меняет. Сборка сверяет контрольные суммы с описаниями компонентов, которые поставляются с Docara: если компонента нет в lock или описание не совпадает, сборка останавливается. Lock этого сайта разрешает ui.button и ui.alert — те же, что получает новый проект. Подробно поля lock описаны в справочнике Framework lock.

Кнопка ui.button

:::ui.button
{"preset":"primary","text":"Продолжить","aria-label":"Продолжить настройку"}
:::

Результат:

preset выбирает готовое оформление: primary, secondary, tonal_on_surface, outline, outline_on_surface, link, link_on_surface или on_surface. Остальные параметры:

ui.button — кнопка действия в интерфейсе, а не ссылка. Чтобы кнопка вела на другую страницу, используйте кнопку-ссылку :button[...] или блок cta.

Уведомление ui.alert

:::ui.alert
{"type":"info","variant":"default","title":"Сборка проверяет параметры","supporting-text":"Неизвестный параметр или значение остановит сборку до публикации.","closable":false,"aria-label":"Сборка проверяет параметры"}
:::

Результат:

type=success и closable=true lock этого сайта запрещает: на статическом сайте их нечем поддержать. Такой вызов останавливает сборку с FRAMEWORK_PROP_UNSUPPORTED_IN_BOUNDED_RUNTIME. Идентификатор id Docara задаёт сама.

Другие компоненты

• ui.input, ui.checkbox, ui.dropdown и ui.list-item (только текстовый вариант внутри ui.dropdown) тоже поставляются с Docara. Их используют собственные компоненты сайта, например конструктор команды установки — см. примеры расширений. Прямо в Markdown они вызываются только на сайте, чей lock их разрешает.
• ui.badge, ui.tabs и ui.dataview пока не приняты. Вместо них используйте бейдж, вкладки и таблицу Docara.

Какие компоненты доступны вашему сайту, покажет команда php vendor/bin/docara atlas --json, а подробности одного компонента — php vendor/bin/docara inspect smart ui.button --json. Как устроены Smart-компоненты внутри и как написать собственный, описано в разделе Smart-компоненты Docara.

Ошибки

Неверный вызов останавливает сборку. Чаще всего встречаются:

Причины и способы исправления всех кодов — в справочнике ошибок страниц.