GrIcon — Компоненты

Обзор

Когда брать

иконке нужен единый размер — --gr-icon-size вместо ширины и высоты в каждом месте;
иконка берёт цвет из палитры — tone вместо своего fill;
иконка значима — label даёт ей имя; без него она скрыта от скринридера, и это верно по умолчанию;
иконка вращается — spin для состояния ожидания без своей анимации.

Когда взять другое

Нужно	Берите
Иконка внутри кнопки	`GrButton` с `square`
Аватар человека	`GrAvatar`
Клавиша на клавиатуре	`GrKbd`
Индикатор ожидания	`GrLoading`

Саму иконку компонент не рисует — она приходит слотом из любого набора (unplugin-icons, свой SVG, спрайт). Своего набора иконок пакет не поставляет и не будет: дублировать поставку вредно.

Варианты все тона и виды — настоящим компонентом

`tone`

primary
neutral
success
warning
danger
info
slate
azure

Размеры

xs
sm
md
lg

Playground контролы выводятся из API, а не пишутся руками

Сцена

Загружается…

0 изменено· состояние — в адресе

Примеры 4 у каждого — живое демо и его код

Декоративная рядом со словом, с именем — когда одна
Рядом со своим словом иконка его повторяет, поэтому по умолчанию она скрыта от скринридера — aria-hidden помнить не нужно. Одна в ячейке она и есть сообщение, и label даёт ей role="img" и имя. Глиф приходит откуда угодно: из набора иконок или своим SVG.
- PasswordChanged 3 months ago
- Two-factor authenticationAuthenticator app
- Active sessions3 devices
Member 2FA Email
Ada Lin
Grace Wu
Linus Ray
Тон для смысла, по умолчанию — цвет родителя
tone красит глиф ролью -text, и треугольник предупреждения остаётся читаемым на фоне страницы. Без тона иконка current и идёт за родителем — стрелка становится ссылкой вместе со ссылкой.
- Deploy of api-gateway finished2 min
- Disk usage on db-2 passed 85 %14 min
- Payment webhook returned 502 three times31 min
- Maintenance window starts at 02:00 UTC1 h
- Grace Wu opened #41822 h
- Project «Q2 launch» archivedyesterday
View the full activity log
Размеры, привязанные к тексту
Каждая ступень size соответствует ступени текста, рядом с которым иконка стоит, а сама шкала живёт в токенах --gr-icon-size-*. Число — выход мимо шкалы для разовой графики, а панель инструментов задаёт размер один раз через GrConfigProvider.
Workspace settings lg
Billing and invoices md
Next invoice on 1 November sm
Prices exclude VAT xs
No messages:size="48"
Спиннер, который называет своё состояние
spin вращает глиф для работы в процессе, а под prefers-reduced-motion базовый кламп останавливает его ровно, а не под случайным углом. Каждый статус — одна иконка, поэтому у каждой есть label.
1. Install dependencies42 s
2. Type check and lint1 min 08 s
3. Unit tests4 812 of 5 947
4. Build packageswaiting
5. Publish to npmwaiting

API порождается из пакета · разойтись не может

Props

Prop	Type	по умолчанию	Описание
`tone`	`GrIconTone \| undefined`	`"current"`	Цвет из палитры. `current` — наследовать цвет текста родителя.
`size`	`number \| "xs" \| "sm" \| "md" \| "lg" \| undefined`	`undefined`	Размер по шкале пакета либо произвольный в пикселях.
`label`	`string \| undefined`	`undefined`	Имя значимой иконки. Задан — иконка объявляется `role="img"` и перестаёт быть скрытой. Не задан — иконка декоративна.
`spin`	`boolean \| undefined`	`false`	Вращение — для спиннеров.

Слоты

Slot	Type	Описание
`default`	`any`	Своя разметка иконки вместо имени из набора.

Типы

Все экспортируемые типы подпути, по файлам, где они объявлены. Имена, дженерики и тела читаются из файлов деклараций пакета и разойтись не могут.

Импорт

import type { GrIconSize, GrIconTone, GrIconConfigurableProps } from '@feugene/granularity/components/GrIcon'

Файлdist/types/components/GrIcon/config.d.ts

grIconConfigconst

const grIconConfig: import("@feugene/granum/contract").GranumComponentDescriptor<"GrIcon">;

Файлdist/types/components/GrIcon/safelist.d.ts

grIconSafelistconst

const grIconSafelist: string[];

Файлdist/types/components/GrIcon/grIconStyles.d.ts

GrIconSizetype

type GrIconSize = GrComponentSize;

GrIconTonetype

Цвет иконки: тон палитры либо наследование от родителя.

type GrIconTone = GrTone | 'current';

Файлdist/types/components/GrIcon/defaults.d.ts

GrIconConfigurablePropsinterface

Пропы GrIcon, настраиваемые глобально через <GrConfigProvider :component-defaults="{ GrIcon: { … } }">. Только оформление — см. GrButton/defaults.ts.

interface GrIconConfigurableProps {
    size: GrComponentSize;
}

Файлdist/types/components/GrIcon/GrIcon.vue.d.ts

GrIconPropsinterface

interface GrIconProps {
    /** Размер по шкале пакета либо произвольный в пикселях. */
    size?: GrIconSize | number;
    /**
     * Имя значимой иконки. Задан — иконка объявляется `role="img"` и перестаёт
     * быть скрытой. Не задан — иконка декоративна.
     */
    label?: string;
    /** Цвет из палитры. `current` — наследовать цвет текста родителя. */
    tone?: GrIconTone;
    /** Вращение — для спиннеров. */
    spin?: boolean;
}

Использование из прозы библиотеки

Декоративная и значимая

По умолчанию иконка декоративна: компонент сам ставит aria-hidden="true". В библиотеке иконка почти всегда сопровождает текст, и раньше атрибут писали руками в каждом месте вызова — достаточно забыть один раз, и диктор прочитает <title> из SVG.

Значимой иконку делает label: появляются role="img" и aria-label, а скрытие снимается.

vue

<!-- рядом есть текст «Сохранено» — иконка декоративна -->
<GrIcon>
<IconCheck />
</GrIcon>

<!-- иконка сама несёт смысл -->
<GrIcon label="Проверено">
<IconCheck />
</GrIcon>

Редкий случай «иконка значима, но имя даёт соседний элемент» выражается обычным атрибутом: fallthrough сильнее собственной привязки компонента.

Размер

size — шкала пакета (xs | sm | md | lg, по умолчанию md) или произвольное число в пикселях. Шкала читается из GrConfigProvider, число — локальный escape-hatch мимо конфига.

Значения шкалы живут токенами --gr-icon-size-xs…lg, поэтому размер иконок настраивается темой, а не пересборкой пакета. Сама переменная --gr-icon-size — точка кастомизации на месте: и обёртка, и вложенный SVG считают себя от неё.

Тон и вращение

tone красит иконку токеном текста (current по умолчанию — цвет наследуется от родителя). Насыщенный тон как цвет текста в пакете запрещён: на светлой подложке он даёт контраст около 2:1, поэтому используются -text роли, как в GrAlert.

spin включает вращение для спиннеров. Отдельной поддержки prefers-reduced-motion компоненту не нужно: глобальный кламп в base.css зажимает анимации, и вращение замирает в исходном положении, а не под случайным углом.

Стиль намеренно глобальный

Правило .gr-icon не scoped: SVG приходит слотом потребителя, и scoped-стиль до него не достаёт — пришлось бы писать :deep в каждом месте вызова.