Цвет

<sf-color> — контрол выбора цвета: образец открывает системную палитру, рядом стоят цвета, которые у продукта уже есть, а кнопка возврата снимает выбор, и снова действует унаследованный цвет. Берите его для цвета темы, внешнего вида сайта, метки или серии графика.

Пример

<div class="flex flex-col gap-3">
  <div class="flex flex-col gap-1">
    <span class="weight-6">Основной цвет</span>
    <sf-color
      id="brand-colour"
      name="brand"
      label="Основной цвет"
      value="#2a5bd7"
      swatches="#2a5bd7|Фирменный, #0f9d58|Успех, #d93025|Ошибка, #f4b400|Внимание"
      clearable>
    </sf-color>
  </div>

  <div class="flex flex-col gap-1">
    <span class="weight-6">Акцент</span>
    <sf-color
      id="accent-colour"
      name="accent"
      label="Акцент"
      inherited-value="#2a5bd7"
      clearable>
    </sf-color>
  </div>

  <p id="colour-status" class="m-0 color-on-surface-variant" aria-live="polite">Измените цвет — здесь появится значение из события.</p>
</div>

// Two colours, so the difference between «chosen» and «inherited» can be seen
// side by side: the first carries a value, the second carries none and shows
// the colour that applies while it stays empty.
const initializeColourExample = async () => {
  const status = document.getElementById('colour-status');
  if (!status || status.dataset.exampleReady === 'true') return;
  status.dataset.exampleReady = 'true';

  await customElements.whenDefined('sf-color');
  for (const colour of document.querySelectorAll('#brand-colour, #accent-colour')) {
    colour.addEventListener('change', (event) => {
      // An empty value means the inherited colour applies again, which is not
      // the same as that colour written out: only the first follows the theme.
      const {name, value} = event.detail;
      status.textContent = value ? `${name}: ${value}` : `${name}: наследуется`;
    });
  }
};

initializeColourExample();

Применение

Выбранный и унаследованный цвет

value — выбранный цвет в виде #rgb, #rrggbb или #rrggbbaa; другие строки контрол не принимает и считает значение пустым. Пустой value значит, что ничего не выбрано и действует inherited-value. Унаследованный цвет контрол показывает как унаследованный, с подписью «наследуется», а не как значение: «не задано» и «задан тот же цвет» различаются, и при смене темы следует за ней только первое.

clearable показывает рядом с выбранным цветом кнопку, которая возвращает контрол к унаследованному цвету.

Палитра продукта

swatches — цвета продукта через запятую, каждый как #hex или #hex|Название. Каждый цвет становится кнопкой с этим названием, поэтому пользователь выбирает фирменный цвет, а не подбирает его на глаз. Название может состоять из нескольких слов: #1f6feb|Фирменный синий, #0a7d33|Зелёный. Цвета без названий можно разделять и пробелом.

Вид, размер и подписи

appearance выбирает, чем ограничен образец: bordered, outlined или plain. size выбирает ступень размерной шкалы 1/2, 1 или 2, чтобы контрол рядом с полем ввода встал с ним по одной линии.

Подписи управления — choose-label у образца, clear-label у кнопки возврата и inherited-text вместо значения — следуют языку страницы; задайте их явно, если нужны другие слова.

Значение и события input и change

Пока пользователь ведёт цвет в палитре, элемент на каждом шаге отправляет всплывающее событие input. Когда цвет зафиксирован — палитра закрыта, нажат цвет продукта или возврат к унаследованному, — элемент один раз отправляет change. У обоих событий одинаковый event.detail:

События внутреннего поля палитры за пределы элемента не выходят.

setValue(value) задаёт цвет так же, как пользователь, и отправляет change, если цвет изменился; clear() — то же, что setValue(''). Оба возвращают true, если значение изменилось.

Значение в форме

С атрибутом name элемент кладёт в форму скрытое поле с этим именем. Его значение — выбранный цвет, а пока действует унаследованный — пустая строка, поэтому форма передаёт «не задано» без дополнительного кода.

const accent = document.querySelector('sf-color[name="accent"]');
accent.addEventListener('change', (event) => {
  saveTheme({accent: event.detail.value || null});
});
accent.clear();

Доступность

• label задаёт доступное имя образца, но видимой подписи не выводит: поставьте рядом видимую подпись с тем же текстом, как в примере.
• Образец — нативное поле выбора цвета: Tab переводит на него фокус, Enter или Space открывают системную палитру.
• Цвета продукта — отдельные кнопки в общей группе. Название цвета служит доступным именем кнопки, aria-pressed отмечает выбранный цвет.
• Кнопка возврата к унаследованному цвету — следующая остановка Tab; её имя задаёт clear-label.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.

Атрибуты

• template — string, по умолчанию default. Шаблон, которым рисуется элемент.
• value — string, по умолчанию пусто. Цвет в формате #rgb, #rrggbb или #rrggbbaa. Пустое значение означает, что ничего не выбрано и действует унаследованный цвет.
• size — string, по умолчанию 1, значения: 1/2, 1, 2. Ступень шкалы размеров, чтобы цвет рядом с текстовым полем выравнивался с ним.
• appearance — string, по умолчанию bordered, значения: bordered, outlined, plain. Как ограничен образец цвета.
• swatches — string, по умолчанию пусто. Цвета, которые уже есть у продукта, через запятую, каждый в виде #hex или #hex|Name; имя может содержать пробелы. Фрагмент без имени может перечислять несколько цветов через пробел. Пользователь выбирает фирменный цвет, а не подбирает hex на глаз.
• inherited-value — string, по умолчанию пусто. Цвет, который действует, пока ничего не выбрано. Показывается как унаследованный, а не как значение: если бы элемент управления рисовал его как значение, «не задано» и «задан тот же цвет» выглядели бы одинаково, а при смене темы следует за ней только первый вариант.
• clearable — boolean, по умолчанию false. Можно ли вернуть выбранный цвет к унаследованному.
• disabled — boolean, по умолчанию false.
• name — string, по умолчанию пусто. Имя в форме. Под ним скрытый input передаёт значение; оно пустое, пока действует унаследованный цвет.
• label — string, по умолчанию пусто. Доступное имя элемента управления.
• choose-label — string, по умолчанию пусто. Слова на образце цвета. Без атрибута компонент берёт текст на языке страницы (по-английски — «Choose a colour»).
• clear-label — string, по умолчанию пусто. Текст элемента управления, который возвращает унаследованный цвет. Если не задан, используется язык страницы.
• inherited-text — string, по умолчанию пусто. Текст, который выводится вместо значения, пока ничего не выбрано. Если не задан, используется язык страницы.

Методы

• setValue(value: string) — возвращает boolean. Устанавливает и фиксирует цвет так же, как это делает пользователь: нормализует его, отражает в value и отправляет input, а затем change, если цвет отличается от зафиксированного. Возвращает, изменилось ли значение.
• clear() — возвращает boolean. Возвращает унаследованный цвет; то же, что setValue(““). Возвращает, изменилось ли значение.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

• change — detail: { value?: string, name?: string }. Цвет зафиксирован: один раз, когда закрывается палитра платформы или нажат образец либо очистка, а не на каждом шаге перетаскивания. Передаёт значение и имя в форме; пустое значение означает, что снова действует унаследованный цвет. Собственное событие change палитры не выходит за пределы хост-элемента.
• input — detail: { value?: string, name?: string }. Цвет изменился — на каждом шаге перетаскивания в палитре платформы и перед каждым change. Передаёт значение и имя в форме.

Доступность

• Роль: группа (group).
• Доступное имя: рекомендуется.
• Клавиши: Tab, Enter, Space.
• Фокус: Поле выбора цвета платформы, каждый образец и кнопка очистки получают фокус по порядку и сохраняют видимое кольцо фокуса. Образцы сообщают через aria-pressed, выбраны ли они.

Минимальная разметка

<sf-color label="Brand colour" clearable inherited-value="#1f6feb" swatches="#1f6feb|Brand blue, #e5534b|Alert"></sf-color>

Источник

• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/color
• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-color