Качество
Качество Smart-компонента — это язык интерфейса, доступность и оформление, понятные ошибки и проверки, которые всё это держат. Здесь — требования и как их проверить.
Качество: язык, доступность, оформление
Глава собирает требования к качеству, которым отвечает каждый Smart-компонент: язык интерфейса, доступность и геометрия. Они делают компоненты одинаковыми по поведению и виду на любой странице.
Язык
Слова, которые компонент показывает сам (подписи кнопок «Закрыть», «Очистить», пустое состояние), подчиняются общему правилу языка интерфейса (см. Язык интерфейса):
- по умолчанию — английские, на русской странице — русские, через общий помощник языка страницы;
- английское слово лежит в словаре компонента, в записи
en, а не в значении по умолчанию свойства: свойство с подписью объявляется с пустым значением по умолчанию (default: ''). Иначе компонент не отличит отсутствующий атрибут от английского слова, и русская страница покажет английский текст; - текст, который передал хост, показывается как есть: подпись читается как
this.getProp('closeLabel') || SF.pageText(TEXT, 'close', this); - слово ищется по цепочке: язык страницы с регионом (
pt-br), язык без региона (pt), английский, а если слова нет и там — показывается сам ключ. На каждом шаге слова, зарегистрированные проектом черезSF.language, сильнее словаря компонента. Так работаетSF.pageText(dictionary, key, node).
Доступность
- У компонента есть доступное имя.
- Виджет объявляет поддерживаемые клавиши и сохраняет видимый фокус.
- Диалог удерживает фокус внутри и возвращает его на место при закрытии.
- Всё это записано в разделе
accessibilityманифеста.
Оформление и геометрия
- Цвета — только токенами; стороны — логическими свойствами (работает в обоих направлениях письма).
- Всплывающее берёт пару «поверхность + тень» одной ступени высоты.
- Граница контрола —
--sf-outline(контраст 3:1);--sf-outline-variant— граница области, а не контрола. - Размер — ступень общей лестницы; вложенные части имеют размеры той же лестницы; поле и список выровнены по одной линии.
- Компонент оформляет только своё поддерево: без глобальных селекторов и без сброса стилей страницы.
- Геометрия измеряется по нарисованному результату, а не по механизму: отступ от края, равенство ширин, на настольной и мобильной ширине.
Смотрите также
- Границы, Высота: поверхность и тень — токены цвета, границы и высоты.
- Одна лестница размеров, Геометрия: стандарт и проверка — лестница размеров и геометрия.
- Язык интерфейса — язык интерфейса.
- Проверки — проверки качества.
Ошибки и диагностика
Глава описывает, как компонент ведёт себя при ошибке и как найти на странице разметку, которая использует имена для совместимости. Компонент при ошибке не роняет страницу и не показывает незавершённое как выполненное.
Поведение при ошибке
| Ситуация | Что делает компонент |
|---|---|
| Нет внешнего шаблона | Рисует встроенный; предупреждение в консоли — только если файл найден, но не загрузился как модуль |
| Недопустимое значение настройки | Использует значение по умолчанию |
| Не загрузились стили | Продолжает отрисовку, не блокируя страницу |
| Нет порта хоста | Прямо сообщает, что возможность не подключена |
| Ошибка при отрисовке | Пишет ошибку в консоль, ставит себе data-sf-error с этапом (render) и отправляет всплывающее sf-component-error с detail: {phase, message, element}; граница фрагмента показывает на его месте состояние ошибки |
Имена для совместимости на странице
Когда компонент принимает имя атрибута или значения для совместимости, он
записывает это в SF.deprecations; SF.deprecations.list() показывает, что на
этой странице их ещё использует, а SF.deprecations.clear() очищает список.
Предупреждения в консоли, жизненный цикл изменений, журнал и обновление проекта
инструментом sf-upgrade — см. Жизненный цикл изменений и Как обновить проект.
Смотрите также
- Жизненный цикл изменений, Как обновить проект — совместимость и обновление проекта.
- Имена для совместимости — имена для совместимости в объявлении свойств.
- Безопасность и поведение при ошибке — ошибки внешнего шаблона.
- Правила взаимодействия компонентов — изоляция сбоев, уменьшение движения и проверка каждого правила в сборке.
- Жизненный цикл изменений (
simai.change-lifecycle) — стандарт жизненного цикла изменений.
Проверки
Каждое правило этой части держится проверкой в гейте Framework, а правила порта хоста — ещё и в гейте владельца компонента, который работает через порт (см. Эталонный хост). Правило без проверки — пожелание. Таблица связывает правило с проверкой, которая его держит.
| Что проверяется | Правило | Проверка |
|---|---|---|
| Манифест соответствует схеме | Для чего нужен манифест | сборка и сверка контрактов (contract:verify) |
| Реестр совпадает с манифестами | Реестр | generated-registry-matches-manifests |
| Значение по умолчанию — то, что делает компонент | Значение по умолчанию — это обещание | manifest-defaults (браузер) |
| Свойство не читается как поле экземпляра | Как компонент читает свойство | undeclared-prop-reads |
| Шаблон читает разрешённые значения | Шаблон и templateContext | template-context (контракт и браузер) |
| Имена настроек и имена для совместимости | Имена настроек, Имена для совместимости | public-api-axes |
Изменение значения — change, один раз |
Соглашение change |
change-event (контракт и браузер) |
| Имена для совместимости записываются, журнал верен | Имена для совместимости на странице | change-lifecycle (контракт и браузер) |
| Слоты читаются до первой отрисовки | Содержимое и слоты | проверки слотов компонентов |
| Жизненный цикл и освобождение ресурсов | Жизненный цикл | smart-lifecycle-hooks, проверки *-lifecycle компонентов |
| Устаревший ответ внешнего шаблона не рисуется | Безопасность и поведение при ошибке | smart-external-view-race |
| Двойная регистрация тега невозможна | Регистрация тега | smart-base-define-guard |
| Порт объявляет каждый читаемый ключ | Порт хоста | гейт владельца компонента (см. Эталонный хост) |
| Намерения, события, набор проверок порта | Порт хоста | эталонный хост и гейт владельца компонента (см. Эталонный хост) |
| Запрос порта | Как компонент получает порт | гейт владельца компонента (контракт и браузер) |
| Язык страницы | Язык | page-language |
| Пара поверхности и тени | Оформление и геометрия | elevation-shadow |
| Граница контрола | Оформление и геометрия | control-boundary |
| Фокус и контраст кольца | Доступность | focus-ring-* (браузер) |
| Геометрия по лестнице размеров | Оформление и геометрия | геометрические пробы компонентов (браузер) |
| Стандарты и их наследование | Требования стандарта, Связь с приложением: порты хоста и намерения | standards |
| Правила Loader | Подключение к странице, Как работает Loader | loader-* |
Как запускать проверки
Слои гейта владельца и команды для каждого — см. Как Framework проверяет себя. Коротко:
npm testзапускает только контрактные проверки и сверку с документацией;- сверка манифестов (
npm run contract:verify), браузерные пробы на собранном кандидате и проверка воспроизводимости сборки выпуска запускаются отдельно; - перед изданием выпуска проверки запускаются против кандидата, а не против уже опубликованного выпуска.
Проверка при изменении компонента
- Манифест обновлён и проходит схему; реестр пересобран.
- Новые и изменённые свойства — с типом, значением по умолчанию и именами для совместимости, если они есть.
- События объявлены со схемой
detail; изменение значения —change. - Геометрия измерена на настольной и мобильной ширине.
- Клавиатура и фокус проверены.
- Добавить — удалить — добавить: одно действие даёт одно событие.
- Если менялось имя — запись в журнале изменений.
Смотрите также
- Как Framework проверяет себя — слои гейта и команды.
- Стандарт разработки Smart-компонентов с ИИ — стандарт разработки с ИИ.