Формат контракта

Каждый файл specs/<name>.json — это межплатформенный контракт компонента. Формат строго задан specs/schema.json.

Структура верхнего уровня

{
  "$schema": "./schema.json",
  "name": "button",
  "component": "LhButton",
  "since": "0.1.0",
  "description": "Кнопка: запускает немедленное действие; поддерживает тип, размер, состояние загрузки, отключённое состояние, значки и узорный китайский фон.",
  "props": [ ... ],
  "events": [ ... ],
  "slots": [ ... ],
  "behaviors": [ ... ],
  "tokenRefs": [ ... ]
}

Поле	Обязательно	Ограничение
name	Да	kebab-case: ^[a-z][a-z0-9-]*$, совпадает с именем файла
component	Да	PascalCase с префиксом Lh: ^Lh[A-Z][a-zA-Z0-9]*$
description	Да	Описание на китайском
props	Да	Массив, как минимум один элемент (схема требует minItems: 1)
since	Нет	Версия, в которой появился
events / slots / behaviors / tokenRefs	Нет	См. ниже

additionalProperties: false — лишние поля не допускаются.

props

{ "name": "size", "type": "enum", "values": ["small", "medium", "large"], "default": "medium", "description": "Размер кнопки" }

Поле	Обязательно	Описание
name	Да	camelCase: ^[a-z][a-zA-Z0-9]*$, единый для пяти платформ
type	Да	См. таблицу ниже
description	Да	Описание на китайском
values	Нет	Значения перечисления при type: enum (массив строковых литералов)
items	Обязательно при type: array	Тип элемента массива (string / number / boolean) + описание
default	Нет	Значение по умолчанию (любой JSON-тип); отсутствие означает, что значения по умолчанию нет
required	Нет	Логическое, по умолчанию false

Семь типов props:

Тип	Значение	Отображение на платформах
string	Строка	String / String / string / const char*
number	Число	Int / Double / number / int
boolean	Логическое	Boolean / Bool / boolean / bool
enum	Перечисление (требуется values)	На каждой платформе генерируется соответствующий тип перечисления
tokenRef	Точечный путь токена	Ссылка на токен; при verify проверяется существование пути (зарезервировано, ни один компонент сейчас не использует)
node	Содержимое слота / дочернего узла	Compose content, SwiftUI ViewBuilder, ArkUI Builder, C-дескриптор дочернего узла (зарезервировано, ни один компонент сейчас не использует)
array	Массив (требуется items)	Варианты выбора в селекторах и т. п.

events

{
  "name": "onValueChange",
  "payload": [{ "name": "value", "type": "string", "description": "Текст после изменения" }],
  "description": "Срабатывает при изменении текста; не срабатывает, когда disabled или readonly равно true"
}

• name: ^on[A-Z][a-zA-Z0-9]*$, единый для пяти платформ
• payload: массив полей (каждый элемент name + type + необязательный description); пустой массив означает отсутствие полезной нагрузки
• description: обязательно

slots

{ "name": "prefix", "description": "Содержимое префикса поля ввода (область слева, не являющаяся полем ввода)" }

name также в camelCase. Реализация слота на стороне платформы ложится на prop типа node или на механизм слотов каждой платформы.

behaviors

Массив описаний поведения на естественном языке, используется для извлечения cases и генерации документации:

"behaviors": [
  "При disabled === true: не реагирует на нажатия, отображает отключённый стиль (токены disabled.*), не запускает onClick",
  "Отображение size: small/medium/large берут токены размеров button.height.<size> и т. д."
]

tokenRefs

Список полных путей токенов, потребляемых этим компонентом, для проверки целостности ссылок командой pnpm verify:specs:

"tokenRefs": ["button.height.medium", "color.primary.default", "color.onPrimary"]

Почему именование такое строгое

Все регулярные выражения служат межплатформенному выравниванию: name определяет имя файла и имена тестов на каждой платформе, component — основа для имён классов на платформах, а имена props и событий остаются одинаковыми на всех пяти платформах — именно поэтому cases можно переводить.

Текущий список компонентов

15 компонентов: button, cell, checkbox, dialog, icon, input, loading, navbar, picker, radio, switch, tag, text, textarea, toast. Все контракты — на странице Справочник по контрактам компонентов.