Datepicker

<sf-datepicker> — выбор одной даты или периода в календаре с переходом по месяцам и годам. Берите его, когда дату удобнее найти в календаре, чем напечатать; если основной сценарий — ввод с клавиатуры, хватит поля ввода. Оформление календаря — из компонента Datepicker.

Пример

HTML

<div class="flex flex-col gap-2">
  <sf-datepicker
    id="meeting-date"
    label="Дата встречи"
    name="meeting"
    value="2026-09-03"
    min-date="2026-09-01"
    placeholder="ДД.ММ.ГГГГ">
  </sf-datepicker>
  <output id="meeting-date-output" class="color-on-surface-variant" aria-live="polite">Выбрано: 03.09.2026 (2026-09-03)</output>
</div>

JavaScript

// `change` carries the picked date twice: as shown in the field
// (formattedValue) and as YYYY-MM-DD (value), the form a server takes.
const initializeMeetingDate = async () => {
  const picker = document.getElementById('meeting-date');
  const output = document.getElementById('meeting-date-output');
  if (!picker || !output || picker.dataset.exampleReady === 'true') return;
  picker.dataset.exampleReady = 'true';

  await customElements.whenDefined('sf-datepicker');
  picker.addEventListener('change', (event) => {
    if (event.target !== picker) return;
    const {value, formattedValue} = event.detail;
    output.value = value ? `Выбрано: ${formattedValue} (${value})` : 'Дата не выбрана';
  });
};

initializeMeetingDate();

Применение

Поле и всплывающий календарь

По умолчанию компонент — поле с подписью label и значком календаря; календарь открывается по щелчку или с клавиатуры. Напечатать дату в поле нельзя: оно только показывает выбранное значение. После выбора дня окно закрывается; close-on-select="false" оставляет его открытым. size выбирает ступень размерной шкалы поля: 1/2, 1 или 2.

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

value задаёт выбранную дату в виде ГГГГ-ММ-ДД. format — как дата видна в поле, по умолчанию DD.MM.YYYY; маркеры DD, MM, YYYY и YY. min-date и max-date ограничивают выбор: дни вне границ недоступны, а месяцы и годы вне границ не выбираются. Границы — постоянные даты ISO; относительных значений вроде «сегодня» нет. Границу «с завтрашнего дня» страница вычисляет сама и записывает в атрибут.

date — то же, что value; если заданы оба, действует date. month (от 0 для января до 11) и year задают месяц и год, которые показывает календарь; без них он показывает месяц выбранной даты, а без даты — текущий. context="month" или context="year" открывает календарь сразу на выборе месяца или года; из кода то же делает setContext().

mask и атрибуты mask-pattern, mask-lazy, mask-placeholder-char, mask-options передаются внутреннему полю. Поле только для чтения, дату в нём не печатают, поэтому на выбор даты маска не влияет.

Период

range включает выбор периода: первый щелчок задаёт начало, второй — конец. Если второй день раньше первого, границы меняются местами. Начальный период задают start-value и end-value.

HTML

<sf-datepicker
  label="Период отчёта"
  name="period"
  range
  start-value="2026-09-07"
  end-value="2026-09-13"
  placeholder="ДД.ММ.ГГГГ - ДД.ММ.ГГГГ">
</sf-datepicker>

Быстрые диапазоны

В режиме периода presets выводит рядом с сеткой список готовых диапазонов. В атрибуте их перечисляют через запятую встроенными id: today, yesterday, last-7-days, last-30-days, this-week, this-month, last-month. Свои диапазоны задаются свойством presets — массивом {id, label, relative} или {id, label, range: [from, to]}. Относительный диапазон считается от сегодняшнего дня в часовом поясе пользователя, а неделя начинается с того же дня, что и в сетке. Диапазоны обрезаются по min-date и max-date; диапазон, от которого ничего не осталось, недоступен. Пункт «Свой период» в конце списка снимает быстрый диапазон и переводит фокус в сетку.

Выбор диапазона ставит даты и показывает месяц, которым он заканчивается. В detail события change приходит preset: {id, relative} для относительного диапазона, {id} — для фиксированного и null, если период выбран в сетке. Так хост может сохранить «последние 7 дней», а не даты, которые они означали сегодня. Чтобы восстановить выбор, верните id в атрибут preset: он важнее start-value и end-value, вычисляется при отрисовке и событий не отправляет.

Если рядом с сеткой списку не хватает места, он переносится над ней строкой. Список — одна остановка табуляции, по пунктам ходят стрелками.

HTML

<sf-datepicker
  label="Период отчёта"
  name="period"
  range
  presets="today,yesterday,last-7-days,last-30-days,this-month,last-month"
  placeholder="ДД.ММ.ГГГГ - ДД.ММ.ГГГГ">
</sf-datepicker>

Календарь на странице

input="false" выводит календарь прямо на странице, без поля и окна, — например, в боковой панели с расписанием.

Язык и начало недели

Названия месяцев и дней недели, подписи кнопок перехода следуют языку ближайшего элемента с lang, а не только документа. locale задаёт язык явно, например ru-RU. Неделя по умолчанию начинается так, как принято в языке страницы, по данным Intl браузера: с понедельника для ru, с воскресенья для en-US, с субботы для ar-EG. week-start задаёт первый день явно, независимо от языка: от 0 — воскресенье до 6 — суббота (1 — понедельник). format языку не следует: поле показывает дату в заданном формате, по умолчанию DD.MM.YYYY, на любом языке.

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

input-name (или name, если input-name не задан) передаётся полю, и форма отправляет показанный текст: дату в формате format, для периода — две даты через -. Если серверу нужна дата ГГГГ-ММ-ДД, берите её из события change или из свойства value, например в скрытое поле формы рядом с календарём:

HTML

<sf-datepicker label="Дата доставки" input-name="delivery_date_text"></sf-datepicker>
<input type="hidden" name="delivery_date">
<script>
  const picker = document.querySelector('sf-datepicker[input-name="delivery_date_text"]');
  const iso = document.querySelector('input[name="delivery_date"]');
  picker.addEventListener('change', (event) => { iso.value = event.detail.isoValue ?? ''; });
</script>

Событие `change`

Выбор дня отправляет на элементе всплывающее событие change. Его event.detail:

Поле	Содержимое
`value`	дата `ГГГГ-ММ-ДД`; для периода — массив `[начало, конец]`
`formattedValue`	дата или период в формате `format`, как в поле
`range`	`true` при выборе периода
`preset`	для периода: выбранный быстрый диапазон — `{id, relative}`, `{id}` или `null`
`format`	значение атрибута `format`
`startValue`, `endValue`	для периода: границы в виде `ГГГГ-ММ-ДД`
`formattedStartValue`, `formattedEndValue`	для периода: границы в формате `format`
`date`, `isoValue`	значение в формате ISO: для одной даты — то же, что `value`, для периода — интервал ISO 8601 `начало/конец` (пока конец не выбран — только начало)

При выборе периода событие приходит дважды: после начала — с пустым endValue, и после конца. formattedValue есть в каждом change.

Событие change на элементе отправляет только сам компонент: поле календаря только для чтения и своего нативного change не даёт. Слушатель на предке, например на форме, слышит и change других полей, поэтому проверяет event.target.

Устаревшее событие sf-change приходит вместе с change и с тем же detail. Подписывайтесь на change.

Свойство value возвращает дату или массив границ периода и принимает то же при присваивании. Кнопки очистки у календаря нет: из кода присвойте value = ''; событие change при этом не приходит. Свойство formattedValue возвращает выбранную дату в формате format, для периода — formattedStartValue и formattedEndValue; читать их можно в любой момент, без события. openPanel(), closePanel() и togglePanel() открывают и закрывают окно из кода; openPanel({focusCalendar: true}) переводит фокус на активный день, closePanel({restoreFocus: true}) возвращает его в поле.

JavaScript

const period = document.querySelector('sf-datepicker[name="period"]');
period.addEventListener('change', (event) => {
  const {startValue, endValue} = event.detail;
  if (startValue && endValue) loadReport(startValue, endValue);
});
period.value = ['2026-10-01', '2026-10-31'];

Доступность

Задайте видимую подпись в label: она даёт полю доступное имя. Календарю на странице (input="false") имя даёт название месяца и года.
ArrowDown, Enter или Space в поле открывают календарь и переводят фокус на активный день. В порядке Tab находится только один день.
Стрелки перемещают по дням, при письме справа налево горизонтальные стрелки зеркалятся. Home и End переходят к началу и концу недели, PageUp и PageDown — на месяц назад и вперёд.
Escape сначала закрывает выбор месяца или года, затем окно календаря и возвращает фокус в поле.
Каждый день — кнопка с полной датой в доступном имени; сегодняшний отмечен aria-current="date", выбранный — aria-pressed.

Справочник API

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

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


Тег	`<sf-datepicker>`
Назначение	Доступный выбор даты и диапазона дат во всплывающем и встроенном режимах, с навигацией по календарю и значениями, которыми управляет элемент.
Контракт	`smart.datepicker`, версия `1.0.0`
Поставка	выпуск Framework `ui-106d5901f8c3`
Жизненный цикл	экспериментальный: API может меняться между выпусками
Готовность	принят в продукт
Заготовка до прихода кода	сервер пишет `data-sf-skeleton="block"`; своего скелетона при загрузке данных нет (Заготовка до прихода кода)

Атрибуты

template — string, по умолчанию default. Шаблон, которым рисуется элемент.
value — string, по умолчанию пусто. Дата в ISO (yyyy-mm-dd). Как свойство — [start, end] для диапазона; атрибут совпадает с date.
date — string, по умолчанию пусто. Выбранная дата в ISO (yyyy-mm-dd); при отсутствии date читается value.
start-value — string, по умолчанию пусто. Только для диапазона: начальная дата в ISO.
end-value — string, по умолчанию пусто. Только для диапазона: конечная дата в ISO.
max-date — string, по умолчанию пусто. Самая поздняя дата в ISO, которую можно выбрать; более поздние дни отключены.
min-date — string, по умолчанию пусто. Самая ранняя дата в ISO, которую можно выбрать; более ранние дни отключены.
range — boolean, по умолчанию false. Выбирать начало и конец вместо одной даты.
month — number, по умолчанию null. Месяц, показываемый при открытии панели, 0-11; по умолчанию — месяц выбранной даты, иначе текущий.
year — number, по умолчанию null. Год, показываемый при открытии панели; по умолчанию — год выбранной даты, иначе текущий.
context — string, по умолчанию пусто, значения: пусто, month, year. На какой сетке открывается панель: дни (пусто), month или year.
week-start — number, по умолчанию null. Первый день недели: от 0 — воскресенье до 6 — суббота (1 — понедельник). Без атрибута следует языку страницы (ru — понедельник, en-US — воскресенье, ar-EG — суббота).
locale — string, по умолчанию пусто. Язык названий месяцев и дней; по умолчанию — язык страницы.
format — string, по умолчанию DD.MM.YYYY. Как дата показывается в поле, например DD.MM.YYYY. Значение остаётся в ISO.
root-class — string, по умолчанию пусто. Классы, добавляемые корневому элементу компонента.
close-on-select — boolean, по умолчанию true. Закрывать панель после выбора даты (или конца диапазона).
input — boolean, по умолчанию true. Рисует текстовое поле; без него рисуется только панель.
open — boolean, по умолчанию false. Открыта ли панель.
portal — boolean, по умолчанию true. Рисует панель в конце документа, чтобы её не обрезал ни один обрезающий предок.
input-type — string, по умолчанию bordered. Вид поля (по умолчанию с рамкой), как у sf-inputs.
size — string, по умолчанию 1, значения: 1/2, 1, 2. Размер поля формы.
input-name — string, по умолчанию пусто. Имя поля формы для значения; сильнее name.
placeholder — string, по умолчанию пусто. Текст-заполнитель поля.
label — string, по умолчанию пусто. Видимая подпись поля.
disabled — boolean, по умолчанию false. Отключает поле и панель.
required — boolean, по умолчанию false. Отмечает поле как обязательное в форме.
icon-start — string, по умолчанию calendar_today. Иконка в начале поля; каноническое имя для left-icon.
left-icon — string, по умолчанию calendar_today. Устаревшее имя icon-start, поддерживается; если заданы оба, приоритет у icon-start.
input-root-class — string, по умолчанию пусто. Классы, добавляемые корневому элементу поля.
mask — boolean, по умолчанию false. Ограничивает ввод в поле маской формата.
mask-pattern — string, по умолчанию 00.00.0000. Маска ввода; если не задана, выводится из format, поэтому формат по умолчанию DD.MM.YYYY даёт 00.00.0000.
mask-lazy — boolean, по умолчанию false. Показывать символы-заполнители маски только по мере ввода.
mask-placeholder-char — string, по умолчанию _. Символ, обозначающий ещё не введённую позицию.
mask-options — string, по умолчанию пусто. Дополнительные параметры маски в JSON, передаются маске поля.
name — string, по умолчанию пусто. Имя поля формы для значения. input-name делает то же и сильнее, если заданы оба.
presets — string | array, по умолчанию пусто. Только для режима диапазона: быстрые диапазоны рядом с сеткой. Встроенные id через запятую (today, yesterday, last-7-days, last-30-days, this-week, this-month, last-month) или свойство [{id, label, relative} | {id, label, range: [from, to]}]. Диапазоны обрезаются по min-date и max-date; диапазон, от которого ничего не осталось, недоступен.
preset — string, по умолчанию пусто. id выбранного быстрого диапазона. Если его задаёт хост, он важнее start-value и end-value; относительный диапазон при отрисовке считается от сегодняшнего дня в часовом поясе пользователя. Событие при этом не отправляется.

Прежние имена:

Имя	Прежнее имя	Состояние	Убирается после
`size`	`input-size`	работает, отмечается в `SF.deprecations`	2026-12-01
`size="1/2"`	`size="1/3"`	работает, отмечается в `SF.deprecations`	2026-12-01
`size="2"`	`size="3"`	работает, отмечается в `SF.deprecations`	2026-12-01

Методы

setContext(context: string) — возвращает object. Открывает контекст календаря: день, месяц или год.
openPanel(options: object) — возвращает object. Открывает всплывающее окно; при необходимости переносит фокус в календарь.
closePanel(options: object) — возвращает object. Закрывает всплывающее окно; при необходимости возвращает фокус в поле.
togglePanel() — возвращает object. Открывает или закрывает всплывающий список, не меняя выбранное значение.
choosePreset(item: object) — возвращает object. Выбирает быстрый диапазон: ставит его даты, показывает месяц, которым он заканчивается, и один раз отправляет change.
chooseCustomRange() — возвращает object. Покидает список быстрых диапазонов и переводит фокус в сетку дней.

События

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

change — detail: { value: string|array, range: boolean, format: string, formattedValue?: string, date?: string, isoValue?: string, startValue?: string, endValue?: string, startIsoValue?: string, endIsoValue?: string, formattedStartValue?: string, formattedEndValue?: string, preset?: object|null }. Выбрана дата или граница диапазона; событие отправляется на элементе. Имя для привязки.
sf-datepicker-change — устаревший псевдоним события change: приходит с тем же detail, подписывайтесь на change.
sf-change — устаревший псевдоним события change: приходит с тем же detail, подписывайтесь на change.

Доступность

Роль: dialog в режиме popup; group в режиме inline.
Доступное имя: обязательно.
Клавиши: Tab, Shift+Tab, Enter, Space, Escape, ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Home, End, PageUp, PageDown.
Фокус: ArrowDown открывает всплывающее окно и переносит фокус на активный день. В порядке табуляции находится только один день. Escape закрывает всплывающее окно и возвращает фокус в поле. В RTL физические горизонтальные стрелки меняются местами, а хронологическое перемещение сохраняется.

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

HTML

<sf-datepicker label="Дата" value="2026-09-03"></sf-datepicker>

Источник

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

Навигация

Главное

Документация

Содержание

Datepicker

Пример

Применение

Поле и всплывающий календарь

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

Период

Быстрые диапазоны

Календарь на странице

Язык и начало недели

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

Событие `change`

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

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

Источник

Настройки

Datepicker

Пример

Применение

Поле и всплывающий календарь

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

Период

Быстрые диапазоны

Календарь на странице

Язык и начало недели

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

Событие change

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

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

Источник

Поиск по документации

Событие `change`