К содержанию

Главное

Справочник компонента

Справочник компонента показывает его тег, атрибуты, события, методы, CSS-переменные и доступность. Сборка читает их из манифестов компонента, поэтому страница не расходится с тем, что выпущено. Ставьте блок на страницу компонента под заголовком «Параметры» или «Справочник».

Пример

Тег
<demo-counter>
Назначение
Числовое поле с кнопками «минус» и «плюс», которое держит значение в заданных пределах.
Контракт
demo.counter, версия 1.0.0
Жизненный цикл
экспериментальный: API может меняться между выпусками

Атрибуты

Атрибут Значения По умолчанию Описание
label (обязательный) string — Название поля для программ экранного доступа.
value number 0 Текущее значение.
step number 1 На сколько меняет значение одно нажатие кнопки.
size 1/2, 1, 2 1 Шаг шкалы размеров Framework.
placeholder string пусто Текст, который видно, пока поле пустое.

События

Событие Данные в detail Описание
demo-counter-change { value: number, previous?: number } Значение изменилось после нажатия кнопки, клавиши или ввода.

Прежние имена, которые ещё приходят следом с тем же detail: demo-counter-input → demo-counter-change.

Методы

Метод Возвращает Описание
increment(amount?: number) number Прибавляет шаг или указанное число и возвращает новое значение.
reset() — —

CSS-переменные

Переменная Тип Описание
--demo-counter-gap length Расстояние между полем и кнопками.
--demo-counter-accent color Цвет кнопок при наведении.

Доступность

Роль
spinbutton
Доступное имя
обязательно
Клавиши
ArrowUp
ArrowDown
Home обнуляет значение
Фокус
Фокус получает поле; Tab пропускает кнопки.

Разметка

Markdown
:::component_reference {component=sf-view-table}
:::
  • Блок пустой: содержимое собирает сборка.
  • component — тег компонента. Сборка ищет его манифесты в папке components/ проекта: components/<папка>/smart.manifest.json и, если есть, components/<папка>/component.json. Папка — тег без приставки sf-: для sf-view-table это components/view-table/, для demo-counter — components/demo-counter/. Так устроена папка smart/ в выпуске SIMAI Framework или набора, поэтому её можно скопировать как есть.
  • Манифест должен описывать тот же тег (custom_element), иначе сборка остановится.
Code
docara.json
components/
  view-table/
    smart.manifest.json
    component.json
content/
  ru/
    lang.json
    component-reference.json

Что показывает справочник

Часть Откуда берётся
overview Тег, summary, id и version, lifecycle манифеста
attributes inputs.properties: тип или допустимые значения, значение по умолчанию, description; обязательные — из inputs.required
events events: данные detail из payload и summary; прежние имена с alias_of перечислены под таблицей
methods methods: аргументы, returns и summary
css css-variables из component.json: имя и тип
accessibility accessibility: роль, доступное имя, клавиши, фокус

Описания, которые ничего не добавляют к имени, например «Public runtime method reset.», не показываются. Раздела, которого нет в манифесте, справочник не скрывает: под заголовком будет «В манифесте не объявлено».

Варианты

Только часть справочника

sections выбирает части и их порядок. Если частей несколько, каждая, кроме overview, получает свой заголовок третьего уровня. Одна часть выводится без заголовка: его пишет автор страницы.

Событие Данные в detail Описание
demo-counter-change { value: number, previous?: number } Значение изменилось после нажатия кнопки, клавиши или ввода.

Прежние имена, которые ещё приходят следом с тем же detail: demo-counter-input → demo-counter-change.

Перевод

Текст манифестов написан по-английски. Чтобы справочник на странице языка был на этом языке, положите словарь component-reference.json в папку содержимого языка, рядом с lang.json:

JSON
{
    "schema": "docara.component_reference.v1",
    "strings": {
        "The current value.": "Текущее значение.",
        "css:--demo-counter-gap": "Расстояние между полем и кнопками."
    }
}
  • Ключ — строка манифеста ровно как она записана, значение — перевод. Обратные кавычки в переводе дают код.
  • У CSS-переменных в component.json нет описания для читателя: его задаёт ключ css:<имя переменной>. Без словаря столбец описания пустой.
  • Язык без словаря показывает текст манифеста как есть.
  • Словарь сверяется при каждой сборке. Если для строки, которую показывает блок, нет перевода, сборка останавливается с кодом COMPONENT_REFERENCE_TRANSLATION_MISSING и называет первые такие строки. Если в словаре осталась строка, которую не показывает ни один блок сайта, полная сборка останавливается с кодом COMPONENT_REFERENCE_TRANSLATION_STALE: удалите её или обновите под новый текст манифеста. Сборка одной страницы видит только её и устаревшие строки не проверяет.

Подписи справочника — «Атрибуты», «По умолчанию», «Описание» и другие — это строки reference.* в lang.json, их можно заменить своими.

Доступность

  • Атрибуты, события, методы и CSS-переменные — обычные таблицы с заголовками столбцов.
  • Тег, контракт и доступность — списки определений: программы экранного доступа читают название и значение парой.
  • Заголовки частей входят в оглавление страницы.

Параметры

Параметр Значения По умолчанию Что задаёт
component (обязательный) строка — Тег компонента, справочник которого показать, например sf-view-table. Манифесты читаются из components/<папка>/.
sections строка overview,attributes,events,methods,css,accessibility Какие части справочника показать и в каком порядке, через запятую: overview, attributes, events, methods, css, accessibility. Без параметра — все.

См. также