Справочник по API · Основные темы

@oriatheme/core

API-интерфейсы контракта темы, проверки, разрешения и импорта/экспорта без зависимости от DOM, Storage, React или Vue.

Упаковка и окружающая среда

Чистый TypeScript; безопасно при оценке модулей Node, SSR и браузера.

bash

pnpm add @oriatheme/core

bash

npm install @oriatheme/core

bash

yarn add @oriatheme/core

bash

bun add @oriatheme/core

Используйте менеджер пакетов и файл блокировки, уже выбранный потребительским проектом. В примерах используется только экспорт корня пакета; не выполняйте глубокий импорт из шаблонов src, dist или реестра.

Общественные функции

Экспорт	Подпись	Описание
`defineTokenContract`	`(input: TokenContractInput) => TokenContract`	Создает неизменяемый проверенный контракт.
`extendTokenContract`	`(base, extension) => TokenContract`	Добавляет токены контракта без потери базы.
`getTokenDefinition`	`(contract, path) => TokenDefinition \| undefined`	Ищет объявленный токен.
`token / colorToken`	`(type, options) => TokenDefinition`	Создает определения токенов контракта.
`validateTheme`	`(input, contract) => ValidationResult<ThemeDefinition>`	Никогда не выдает ошибку для ненадежного сериализованного ввода.
`normalizeTheme`	`(theme, contract) => ThemeDefinition`	Канонизирует заказ и заполняет значения контракта по умолчанию.
`resolveTheme`	`(theme, mode, options?) => ResolvedTheme`	Разрешает ссылки и компилирует безопасные переменные CSS.
`resolveThemeWithContract`	`(theme, contract, mode, options?) => ResolvedTheme`	Безопасный преобразователь с явным контрактом.
`cloneTheme`	`(theme, identity, clock?) => ThemeDefinition`	Создает полную копию с отметкой времени.
`createThemeFromSeed`	`(seed, options) => ThemeDefinition`	Создает полную пользовательскую тему стандартного контракта.
`exportTheme`	`(theme) => string`	Сериализует общедоступный формат темы.
`importTheme`	`(json, options) => ImportResult`	Проверяет JSON, устанавливает пользовательский вид и обрабатывает конфликты.
`analyzeTheme`	`(theme, contract) => ThemeDiagnostics`	Возвращает ошибки блокировки и предупреждения о контрастности.
`contrastRatio`	`(foreground, background) => number`	Вычисляет контраст WCAG для статических шестнадцатеричных цветов.
`toCssVariable`	(path, prefix?, cssNameStyle?) => `--${string}`	Преобразует проверенный путь в настраиваемое свойство CSS.
`isTokenPath`	`(value) => value is TokenPath`	Сужает строку до пути фирменного токена.
`oriaStandardContract / oriaDefaultTheme`	`TokenContract / ThemeDefinition`	Контракт oria-standard@2 по умолчанию и тема по умолчанию, начиная с версии 0.3.0.
`oriaStandardContractV1 / oriaDefaultThemeV1`	`TokenContract / ThemeDefinition`	Экспорт устаревшей версии 1 сохранялся только в качестве входных данных для миграции.
`migrateOriaStandardV1ToV2`	`(input: unknown) => ThemeMigrationResult`	Преобразует полную стандартную тему v1 в v2 с предупреждениями и требует просмотра.

import { oriaStandardContract, resolveTheme, validateTheme } from "@oriatheme/core";

const checked = validateTheme(input, oriaStandardContract);
if (checked.ok) {
  const resolved = resolveTheme(checked.value, "dark");
  // resolved.variables is safe compiler output.
}

Ветвь по результатам validateTheme или importTheme для пользовательского ввода; не соответствуют сообщениям об ошибках.

Важные типы и границы

ThemeDefinition — это полная сериализованная тема (schemaVersion 1; контракт по умолчанию — oria-standard@2, начиная с 0.3.0); TokenContract описывает пути и безопасные значения; ValidationResult / ImportResult различает ОК; OriaThemeError.code — это стабильная ветвь ошибок. ResolvedTheme содержит скомпилированные переменные и цветовую схему. ThemeMigrationResult содержит перенесенную тему, предупреждения и requireReview.