@russian-flags/regions

English version

Нативная ESM-коллекция SVG-флагов регионов России. Пакет можно использовать как npm-зависимость в JavaScript/TypeScript-проекте или как набор готовых SVG-файлов и ленивых загрузчиков без React.

Пакет содержит 89 регионов: республики, края, области, города федерального значения, автономную область и автономные округа.

Превью

Регион	Код	ISO-код	Автокод	Флаг
Санкт-Петербург	SPE	RU-SPE	78
Москва	MOW	RU-MOW	77
Севастополь	SEV	RU-SEV	92, 93
Новосибирская область	NVS	RU-NVS	54

Возможности

• 89 локальных SVG-флагов в составе пакета.
• ESM-сборка с TypeScript-типами.
• Ленивые загрузчики для каждого флага.
• Поиск региона по коду, ISO-коду, автомобильному коду, названию или алиасу.
• Прямой импорт SVG-файлов через flags/<code> или svg/<code>.
• Подходит для обычного JavaScript, TypeScript и современных сборщиков.

Установка

npm install @russian-flags/regions

Для локальной проверки из папки проекта:

npm install .

Быстрый старт

import { loadFlag, regions } from "@russian-flags/regions";

console.log(regions[0]);
// {
//   code: "AD",
//   isoCode: "RU-AD",
//   nameRu: "Республика Адыгея",
//   nameEn: "Republic of Adygea",
//   numericCodes: [1],
//   aliases: ["ADYGEA", "АДЫГЕЯ"]
// }

const image = await loadFlag("TA", {
  alt: "Флаг Республики Татарстан",
  className: "flag",
});

document.body.append(image);

loadFlag - алиас для loadFlagImage. Функция лениво импортирует модуль нужного флага, создает <img> и по умолчанию ставит loading="lazy" и decoding="async".

Подключение SVG напрямую

Если нужен только файл флага, можно импортировать SVG напрямую. Entry-point'ы для файлов сделаны в нижнем регистре:

import tatarstanFlag from "@russian-flags/regions/flags/ta";
import tatarstanSvg from "@russian-flags/regions/svg/ta";

console.log(tatarstanFlag);
console.log(tatarstanSvg);

Вариант с расширением тоже поддерживается:

import tatarstanFlag from "@russian-flags/regions/flags/ta.svg";
import tatarstanSvg from "@russian-flags/regions/svg/ta.svg";

flags/<code> и svg/<code> указывают на один и тот же файл внутри пакета:

dist/flags/<code>.svg

После публикации пакет также можно использовать как источник SVG через npm CDN:

<img src="https://unpkg.com/@russian-flags/regions/dist/flags/ta.svg" alt="Флаг Республики Татарстан" />

Поиск региона

В большинство функций можно передавать:

• короткий код: "TA";
• ISO-код: "RU-TA";
• автомобильный код: 16, "16" или "016";
• русское или английское название;
• алиас из справочника, например "TATARSTAN".

import {
  getRegionMeta,
  regionCodes,
  regions,
  resolveRegionCode,
} from "@russian-flags/regions";

console.log(regions.length); // 89
console.log(regionCodes.includes("TA")); // true

console.log(resolveRegionCode("RU-TA")); // "TA"
console.log(resolveRegionCode(16)); // "TA"
console.log(resolveRegionCode("tatarstan")); // "TA"
console.log(resolveRegionCode("Республика Татарстан")); // "TA"
console.log(resolveRegionCode("unknown")); // undefined

console.log(getRegionMeta("RU-TA")?.nameRu); // "Республика Татарстан"

Ввод нормализуется: пробелы по краям удаляются, префикс RU- отбрасывается, регистр не важен, пробелы и дефисы приводятся к _.

Ленивое отображение списка

import { loadFlag, regions } from "@russian-flags/regions";

for (const region of regions) {
  const row = document.createElement("tr");
  row.dataset.code = region.code;
  row.textContent = region.nameRu;
  document.querySelector("tbody").append(row);
}

const observer = new IntersectionObserver((entries) => {
  for (const entry of entries) {
    if (!entry.isIntersecting) continue;

    observer.unobserve(entry.target);

    loadFlag(entry.target.dataset.code).then((image) => {
      entry.target.append(image);
    });
  }
});

document
  .querySelectorAll("tr[data-code]")
  .forEach((row) => observer.observe(row));

Preload

preloadFlag запускает загрузку модуля флага без ожидания результата. Это удобно на hover, focus или перед появлением строки во viewport.

import { preloadFlag } from "@russian-flags/regions";

button.addEventListener("pointerenter", () => {
  preloadFlag("TA");
});

Неизвестные значения игнорируются и не выбрасывают ошибку.

API

Экспорт	Описание
regions	Массив метаданных { code, isoCode, nameRu, nameEn, numericCodes, aliases }.
regionCodes	Массив всех доступных коротких кодов регионов.
normalizeRegionCode(input)	Нормализует пользовательский ввод перед поиском.
resolveRegionCode(input)	Возвращает короткий код региона по коду, ISO-коду, номеру, названию или алиасу.
isRegionCode(input)	Type guard для канонического RegionCode.
getRegionMeta(input)	Возвращает метаданные региона или undefined.
getFlagModuleLoader(input)	Возвращает ленивый загрузчик модуля флага или undefined.
getRegionFlagModuleLoader(input)	Алиас для getFlagModuleLoader.
loadFlagModule(input)	Лениво импортирует модуль флага. Бросает ошибку для неизвестного значения.
loadRegionFlagModule(input)	Алиас для loadFlagModule.
loadFlagImage(input, options)	Загружает флаг и возвращает HTMLImageElement.
loadRegionFlagImage(input, options)	Алиас для loadFlagImage.
loadFlag(input, options)	Алиас для loadFlagImage.
preloadFlag(input)	Запускает загрузку модуля без ожидания результата.
preloadRegionFlag(input)	Алиас для preloadFlag.
createFlagImage(src, defaultAlt, options)	Создает и настраивает <img> для SVG-флага.

Типы

Пакет поставляет .d.ts файлы и экспортирует основные типы:

import type {
  FlagImageOptions,
  FlagModule,
  RegionCode,
  RegionInput,
  RegionMeta,
} from "@russian-flags/regions";

FlagImageOptions поддерживает:

Поле	Назначение
alt	Альтернативный текст изображения.
decoding	Значение свойства HTMLImageElement.decoding.
loading	Значение свойства HTMLImageElement.loading.
className	CSS-класс изображения.
title	Атрибут title.
id	Атрибут id.
width, height	Размеры изображения.
style	Inline-стили.
dataset	Значения для data-*.
attributes	Произвольные HTML-атрибуты.

Совместимость

Пакет рассчитан на современные ESM-проекты и браузерное окружение. Функции loadFlag, loadFlagImage и createFlagImage создают HTMLImageElement, поэтому для них нужен DOM.

Метаданные (regions, regionCodes, resolveRegionCode, getRegionMeta) можно использовать отдельно, например для поиска, автокомплита или генерации списка доступных флагов.

Демо

cd examples
npm install
npm run dev

Vite откроет страницу примера в браузере. Пример устанавливает пакет из корня репозитория через file:.. и импортирует @russian-flags/regions так же, как это будет делать обычное приложение-потребитель.

Разработка

npm install
npm run build
npm test
npm run typecheck
npm run pack:dry

Сборка устроена так:

1. scripts/build-source.js читает src/regions.ts, проверяет assets/<code>/index.svg и генерирует TypeScript-исходники.
2. scripts/build.js собирает JavaScript через esbuild и копирует SVG в dist/flags/<code>.svg.
3. tsc -p tsconfig.build.json генерирует .d.ts файлы в dist.

Чтобы добавить новый регион, добавьте запись в src/regions.ts, положите SVG в assets/<code-in-lowercase>/index.svg и запустите сборку.

Репозиторий

• GitHub: https://github.com/russian-flags/regions
• Issues: https://github.com/russian-flags/regions/issues

Лицензия

Код пакета распространяется по лицензии MIT. SVG-флаги не входят в MIT-лицензию кода и сохраняют свои исходные лицензии.