منتقي التاريخ واجهة البرمجة

الفتحات

في DatePicker عدد 15 من الفتحات. مرّر بديلًا لأي منها في components، وكل فتحة لا تمرّرها تبقى على بديلها الافتراضي. فتحات العناصر تستقبل خصائص DOM فيناسبها عنصر المكتبة كما هو، وفتحات الأدوات تستقبل خصائص مسمّاة وتحتاج عادة إلى بضعة أسطر من المحوّل.

الاسم	النوع	الخصائص التي تستقبلها	البديل الافتراضي	سمات `data-*`
`Root`	<element>	خصائص DOM: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	مصدر البديل `Root: ({ className, ...props }) => <div className={cx("sdp", className)} {...props} />`	`data-disabled` `data-empty` `data-invalid` `data-mode` `data-open`
`Trigger`	<element>	خصائص DOM: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	مصدر البديل `Trigger: ({ className, ...props }) => <div className={cx("sdp__trigger", className)} {...props} />`	`data-disabled` `data-empty` `data-invalid` `data-open` `data-trigger`
`Input`	<element>	خصائص DOM: `Omit<InputHTMLAttributes<HTMLInputElement>, "color" \| "size">` `ref?: Ref<HTMLInputElement>`	مصدر البديل `Input: ({ className, ...props }) => <input className={cx("sdp__input", className)} {...props} />`	`data-empty` `data-invalid` `data-open`
`Toggle`	<element>	خصائص DOM: `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "color" \| "type">` `ref?: Ref<HTMLButtonElement>` `type?: "button"`	مصدر البديل `Toggle: ({ className, type = "button", ...props }) => ( <button type={type} className={cx("sdp__toggle", className)} {...props} /> )`	`data-open`
`Value`	{widget}	`text?: string` The formatted selection, when there is one. `placeholder: string` Shown when nothing is picked. `empty: boolean` Whether anything is picked.	مصدر البديل `Value: ({ text, placeholder, empty }) => ( <span className={cx("sdp__value", empty && "sdp__value--empty")}>{empty ? placeholder : text}</span> )`	—
`Icon`	{widget}	`open: boolean` Whether the calendar is open.	مصدر البديل `Icon: () => <CalendarIcon />`	—
`Clear`	{widget}	`onClick: () => void` Clears it. `aria-label: string` Accessible name.	مصدر البديل `Clear: ({ onClick, ...aria }) => ( <button type="button" className="sdp__clear" onClick={(event) => { event.stopPropagation(); onClick(); }} {...aria} > <CrossIcon /> </button> )`	—
`Popup`	<element>	خصائص DOM: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	مصدر البديل `Popup: ({ className, ...props }) => <div className={cx("sdp__popup", className)} {...props} />`	`data-placement`
`Calendar`	<element>	خصائص DOM: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	مصدر البديل `Calendar: ({ className, ...props }) => <div className={cx("sdp__calendar", className)} {...props} />`	—
`Caption`	{widget}	`month: ISODate` The month being shown, as the 1st of that month. `monthLabel: string` The month's name in the current locale. `monthIndex: number` The month being shown, `0` for January. `year: number` The year being shown. `months: string[]` Every month name, January first, for a dropdown. `years: number[]` The years that can be picked. `onMonthChange: (month: number) => void` Shows a different month of the same year. Takes a month index. `onYearChange: (year: number) => void` Shows the same month of a different year. `labels: { month: string; year: string }` Accessible names for the two controls.	مصدر البديل Caption: function Caption({ monthIndex, year, months, years, onMonthChange, onYearChange, labels }) { // An id rather than a name keeps the selects out of an enclosing form's submission. const id = useId(); return ( <span className="sdp__caption"> <select id={`${id}-month`} className="sdp__select" aria-label={labels.month} value={monthIndex} onChange={(event) => onMonthChange(Number(event.target.value))} > {months.map((name, index) => ( <option key={name} value={index}> {name} </option> ))} </select> <select id={`${id}-year`} className="sdp__select" aria-label={labels.year} value={year} onChange={(event) => onYearChange(Number(event.target.value))} > {years.map((value) => ( <option key={value} value={value}> {value} </option> ))} </select> </span> ); }	—
`Nav`	{widget}	`direction: "previous" \| "next"` Which way its arrow should point, as if the page were left to right. In right-to-left this is reversed for you: the control that moves back in time sits on the right and points right, so it is told `next`. `aria-label` always says what it does. `onClick: () => void` Moves the calendar. `disabled: boolean` Whether the move would leave the allowed range. `aria-label: string` Accessible name.	مصدر البديل `Nav: ({ direction, onClick, disabled, ...aria }) => ( <button type="button" className="sdp__nav" onClick={onClick} disabled={disabled} {...aria}> <ChevronIcon flip={direction === "next"} /> </button> )`	—
`Weekday`	{widget}	`label: string` The name in the current locale, in the chosen `weekdayFormat`. `name: string` The full name, e.g. "Saturday". `index: number` 0 to 6, in display order.	مصدر البديل `Weekday: ({ label }) => <span className="sdp__weekday">{label}</span>`	—
`Day`	<element>	خصائص DOM: `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "color" \| "type">` `type?: "button"` `ref?: Ref<HTMLButtonElement>`	مصدر البديل `Day: ({ className, ...props }) => <button type="button" className={cx("sdp__day", className)} {...props} />`	`data-date` `data-disabled` `data-focused` `data-in-preview` `data-in-range` `data-outside` `data-range-end` `data-range-start` `data-selected` `data-today` `data-weekend`
`DayContent`	{widget}	`day: CalendarDay` The day being rendered. `selected: boolean` Whether it is picked. `inRange: boolean` Whether it sits inside a picked range. `inPreview: boolean` Whether it sits inside the range preview. `disabled: boolean` Whether it cannot be picked.	مصدر البديل `DayContent: ({ day }) => <span>{day.day}</span>`	—
`Footer`	{widget}	`presets: DatePickerPreset[]` The shortcuts to offer. `onPreset: (value: ISODate \| DateRange) => void` Applies one. `onToday: () => void` Jumps to today without picking it. `todayLabel: string` The label for that control — navigation, so it should read and look apart from the presets rather than like one of them.	مصدر البديل `Footer: ({ presets, onPreset, onToday, todayLabel }) => ( <div className="sdp__footer"> {presets.map((preset) => ( <button key={preset.label} type="button" className="sdp__preset" onClick={() => onPreset(preset.value)}> {preset.label} </button> ))} <button type="button" className="sdp__preset sdp__preset--today sdp__today" onClick={onToday}> <TodayIcon /> {todayLabel} </button> </div> )`	—

الخصائص

كل خصائص DatePicker مجمّعة كما في توثيق المكتبة. الحالة المتحكَّم بها تأتي أزواجًا: مرّر القيمة مع معالج تغييرها، أو القيمة الابتدائية وحدها لتبقى الحالة داخل المكوّن.

الاسم	النوع	الافتراضي	الوصف
Value and mode
`mode`single mode	`"single"`	—	One date. The default mode.
`mode`مطلوبةmultiple mode	`"multiple"`	—	Any number of dates, toggled one click at a time.
`mode`مطلوبةrange mode	`"range"`	—	A start and an end: the first click sets the start, the second the end.
`value`single mode	`ISODate \| null`	—	The picked date, or `null` for nothing.
`value`multiple mode	`ISODate[]`	—	The picked dates.
`value`range mode	`DateRange \| null`	—	The picked range. Either end may be missing while picking.
`defaultValue`single mode	`ISODate \| null`	—	The picked date while uncontrolled.
`defaultValue`multiple mode	`ISODate[]`	—	The picked dates while uncontrolled.
`defaultValue`range mode	`DateRange \| null`	—	The picked range while uncontrolled.
`onChange`single mode	`(value: ISODate \| null) => void`	—	The new date, or `null` when cleared.
`onChange`multiple mode	`(value: ISODate[]) => void`	—	The new dates, sorted, always an array.
`onChange`range mode	`(value: DateRange \| null) => void`	—	The new range, or `null` when cleared.
`clearable`	`boolean`	`true`	Whether the clear control is offered. Defaults to `true`.
`closeOnSelect`	`boolean`	`true` in single mode and `false` otherwise	Whether picking closes the popup. Defaults to `true` in single mode and `false` otherwise.
`valueFormat`	`DateValueFormat`	`"iso-datetime"`; `"YYYY-MM-DD"` keeps the calendar day alone	How the days the picker exchanges with you are written: `value`, `defaultValue`, `onChange`, `minDate`, `maxDate`, the presets and the day `disabledDates` is asked about. A pattern such as `"DD/MM/YYYY"`, `"iso-datetime"` for the instant the day starts in `timeZone`, or a codec of your own. Defaults to `"iso-datetime"`; `"YYYY-MM-DD"` keeps the calendar day alone.
`timeZone`	`string`	the browser's own	The time zone the calendar works in: an IANA name such as `"Asia/Tokyo"`, `"UTC"`, or an offset such as `"+09:00"`. Today is today in that zone, and with `valueFormat: "iso-datetime"` (the default) a picked day is the instant it starts there and an instant is read as the day it falls on there. Defaults to the browser's own.
`name`	`string`	—	The form field name. The root then holds a hidden input of that name per picked day, written as `valueFormat` says, so a plain HTML form submits the value: one day, each of several days, or a range's start then end.
Calendar
`locale`	`LocaleInput`	the provider's, then `en-US`	The language: a locale object, or a BCP 47 tag. A tag formats dates and names with `Intl` as always, and takes its labels from the pack of that language given to `SlotsmithProvider`, if there is one. Defaults to the provider's, then `en-US`.
`weekStartsOn`	`WeekStart`	the locale's own first day	The first column of the grid. Defaults to the locale's own first day.
`weekdayFormat`	`"narrow" \| "short" \| "long"`	`narrow`	How long the column headers are. `narrow` is a single character in every language, and is the only form that reliably fits a square day column. Defaults to `narrow`.
`presets`	`DatePickerPreset[]`	—	Shortcuts shown under the grid. A date preset in range mode picks that one day.
Bounds
`minDate`	`ISODate`	—	Nothing before this date can be picked, and the calendar does not page past it.
`maxDate`	`ISODate`	—	Nothing after this date can be picked, and the calendar does not page past it.
`disabledDates`	`(date: ISODate) => boolean`	—	Blocks individual dates — weekends, holidays, days already booked. They stay focusable.
Open state
`open`	`boolean`	—	Whether the popup is open.
`defaultOpen`	`boolean`	—	Whether the popup starts open.
`onOpenChange`	`(open: boolean) => void`	—	Told when the popup opens or closes.
`disabled`	`boolean`	—	Disables the whole control. Separate from `disabledDates`.
`invalid`	`boolean`	—	The value failed validation. Sets `aria-invalid` on the combobox and `data-invalid` on the root and trigger, so a skin can show its error style. Pair it with `aria-errormessage` or `aria-describedby` pointing at the message. Default `false`.
`onBlur`	`(event: FocusEvent<HTMLElement>) => void`	—	Told when focus leaves the whole control, for form libraries.
Display
`trigger`	`DatePickerTriggerKind`	—	What opens the calendar. `"input"`, the default, is a text field the date can be typed into, in the locale's numeric order (`MM/DD/YYYY` in en-US), with a calendar button beside it. `"button"` is one control that shows the formatted value and opens the calendar when pressed.
`openOnFocus`	`boolean`	`false`	With the `"input"` trigger, focusing or clicking the text field opens the calendar too. Defaults to `false`.
`placeholder`	`string`	—	Shown when nothing is picked. With the `"button"` trigger it defaults to `labels.placeholder`; the `"input"` trigger's text field shows the date order to type in, such as `MM/DD/YYYY`.
`format`	`Intl.DateTimeFormatOptions`	`{ day: "numeric", month: "short", year: "numeric" }`	How the trigger formats a date. Defaults to `{ day: "numeric", month: "short", year: "numeric" }`.
`placement`	`PopupPlacement`	`bottom`	Which side of the trigger the popup prefers. Defaults to `bottom`.
`popupOffset`	`number`	`4`	Gap between trigger and popup, in pixels. Defaults to 4.
`portal`	`PortalTarget`	`false`	Renders the popup in a portal: `true` for `document.body`, or an element of your own. It then escapes any ancestor's `overflow`, `transform` or stacking context, and still counts as part of the control. Set the `--ss-*` tokens and the dark class on `:root` or on that element, which the popup then inherits from. Defaults to `false`.
Slots and labels
`components`	`Partial<DatePickerComponents>`	—	Replace any part; the rest fall back to `SlotsmithProvider`'s `components.datePicker`, then to the built-in ones.
`labels`	`Partial<DatePickerLabels>`	—	Override any string. Wins over `locale`.
`slotProps`	`DatePickerSlotProps`	—	Extra DOM props for the element parts.

تُمرَّر أي خاصية أخرى إلى العنصر الجذر <div>.

النصوص واللغات

كل نص يعرضه DatePicker أو يعلنه، مع قيمته الافتراضية بالإنجليزية. مرّر labels لتغيير بعضها في مكوّن واحد، أو locale لتحويل كل النصوص إلى لغة أخرى. العرض أدناه يفعل الأمرين.

المفتاح	النوع	الافتراضي بالإنجليزية	الوصف
`placeholder`	`string`	`"Pick a date"`	Trigger text when nothing is picked, and the trigger's default accessible name.
`clear`	`string`	`"Clear date"`	Accessible name for the clear control.
`openCalendar`	`string`	`"Open calendar"`	Accessible name for the calendar button beside the text field.
`previous`	`string`	`"Previous month"`	Accessible name for the previous-month control.
`next`	`string`	`"Next month"`	Accessible name for the next-month control.
`today`	`string`	`"Go to today"`	Label for the control that jumps to today's month without picking it — a navigation verb, not the bare word "today", so it reads apart from the presets.
`month`	`string`	`"Month"`	Accessible name for the month dropdown.
`year`	`string`	`"Year"`	Accessible name for the year dropdown.
`dialog`	`string`	`"Choose a date"`	Accessible name for the popup.
`count`	`(count: number) => string`	`count(3)` يطبع `"3 dates selected"`	Multiple mode: how the trigger summarises more than two dates.
`rangeStart`	`(from: string) => string`	`rangeStart("Mar 3")` يطبع `"Mar 3 — …"`	Range mode, when only the start is picked. Receives the formatted start.
`range`	`(from: string, to: string) => string`	`range("Mar 3", "Mar 9")` يطبع `"Mar 3 — Mar 9"`	Range mode, when both ends are picked. Receives both formatted ends.

import { DatePicker } from "slotsmith/date-picker";
import { de } from "slotsmith/locales/de";

export default function Labels() {
  return (
    <DatePicker
      mode="multiple"
      // Every string in German, from the ready-made pack; month and weekday names come from Intl…
      locale={de}
      // …except these two, replaced for this picker only.
      labels={{ openCalendar: "Kalender zeigen", today: "Heute anzeigen" }}
      aria-label="Urlaubstage"
    />
  );
}

حزم اللغات الجاهزة ودعم الكتابة من اليمين إلى اليسار واللغة على مستوى التطبيق موضّحة في صفحة اللغات.

التنسيق

أسماء الأصناف التي تضعها البدائل الافتراضية في DatePicker على عناصرها، والمتغيرات التي يقرؤها ملف تنسيقه. اضبط متغيرًا على المكوّن أو على أي عنصر يحيط به لتغيير مظهره، واستهدف الصنف فقط لما لا يغطيه متغير.

الصنف	الفتحة
`.sdp`	`Root`
`.sdp__header`	—
`.sdp__cell`	—
`.sdp__weekdays`	—
`.sdp__columnheader`	—
`.sdp__week`	—
`.sdp__chevron`	—
`.sdp__icon`	`Icon`
`.sdp__today-icon`	—
`.sdp__clear`	`Clear`
`.sdp__caption`	`Caption`
`.sdp__select`	—
`.sdp__nav`	`Nav`
`.sdp__weekday`	`Weekday`
`.sdp__footer`	`Footer`
`.sdp__preset`	—
`.sdp__preset--today`	—
`.sdp__today`	—
`.sdp__trigger`	`Trigger`
`.sdp__input`	`Input`
`.sdp__toggle`	`Toggle`
`.sdp__value`	`Value`
`.sdp__value--empty`	—
`.sdp__popup`	`Popup`
`.sdp__calendar`	`Calendar`
`.sdp__day`	`Day`

المتغير	الطبقة
`--sdp-accent`	هذا المكوّن
`--sdp-border`	هذا المكوّن
`--sdp-cell`	هذا المكوّن
`--sdp-danger`	هذا المكوّن
`--sdp-font-size`	هذا المكوّن
`--sdp-gap`	هذا المكوّن
`--sdp-hover`	هذا المكوّن
`--sdp-muted`	هذا المكوّن
`--sdp-on-accent`	هذا المكوّن
`--sdp-radius`	هذا المكوّن
`--sdp-surface`	هذا المكوّن
`--sdp-text`	هذا المكوّن
`--ss-accent`	مشترك بين كل المكوّنات
`--ss-border`	مشترك بين كل المكوّنات
`--ss-danger`	مشترك بين كل المكوّنات
`--ss-font-size`	مشترك بين كل المكوّنات
`--ss-hover`	مشترك بين كل المكوّنات
`--ss-muted`	مشترك بين كل المكوّنات
`--ss-on-accent`	مشترك بين كل المكوّنات
`--ss-radius`	مشترك بين كل المكوّنات
`--ss-surface`	مشترك بين كل المكوّنات
`--ss-text`	مشترك بين كل المكوّنات

تنتقل كل المتغيرات إلى قيمها الداكنة تحت .dark, [data-theme="dark"]، على الصفحة أو على أي عنصر يحيط بالمكوّن.

صفحة السمات تشرح المتغيرات والسمات الجاهزة.