Premium Widgets
Custom Calendar Grid
CalendarGrid en React
Muestra citas en una vista mensual y selecciona días o entradas.
AI Defaults
Ejemplo completo
import { useState } from "react";
import { ArcWidgetCalendarGrid } from "@arcrider/arcwidgets-react";
import type {
ArcWidgetCalendarGridDailyEntryDragSavePayload,
ArcWidgetCalendarGridEntryDragSavePayload,
ArcWidgetCalendarGridTimeEntry,
} from "@arcrider/arcwidgets-react";
const day = (date: number) => Date.UTC(2027, 0, date); const at = (hours: number, minutes = 0) => (hours * 60 + minutes) * 60000;
const initialEntries: ArcWidgetCalendarGridTimeEntry[] = [ { title: "Team Offsite", dateFrom: day(4), dateTo: day(5), draggable: true, }, { title: "Public Holiday", dateFrom: day(6), dateTo: day(6), draggable: true, }, { title: "Team Meeting", dateFrom: day(4), dateTo: day(4), timeFrom: at(9), timeTo: at(10, 30), draggable: true, }, { title: "Code Review", dateFrom: day(5), dateTo: day(5), timeFrom: at(10), timeTo: at(11), draggable: true, }, { title: "Workshop", subtitle: "Room 2", dateFrom: day(5), dateTo: day(5), timeFrom: at(13, 30), timeTo: at(17), draggable: true, }, { title: "Lunch", dateFrom: day(5), dateTo: day(5), timeFrom: at(12), timeTo: at(13), draggable: true, }, { title: "Retro", dateFrom: day(5), dateTo: day(5), timeFrom: at(17), timeTo: at(18), draggable: true, }, { title: "Sprint Planning", dateFrom: day(8), dateTo: day(8), timeFrom: at(9), timeTo: at(12), draggable: true, }, // Timed, several days in one week. The bar lines up with Thursday–Saturday. // 15:00 is written at the right edge. { title: "Conference", dateFrom: day(7), dateTo: day(9), timeFrom: at(11), timeTo: at(15), draggable: true, }, // Continues onto the next week row: that row repeats the title, and 11:00 // is written at the right edge of the last piece only. { title: "Client Workshop", dateFrom: day(8), dateTo: day(11), timeFrom: at(16), timeTo: at(11), draggable: true, }, { title: "Stand-up", dateFrom: day(18), dateTo: day(18), timeFrom: at(9), timeTo: at(9, 30), draggable: true, }, { title: "Design Review", dateFrom: day(20), dateTo: day(20), timeFrom: at(14), timeTo: at(16), draggable: true, }, { title: "All-Hands", dateFrom: day(22), dateTo: day(22), timeFrom: at(10), timeTo: at(11), draggable: true, }, { title: "Office Closed", dateFrom: day(29), dateTo: day(29), draggable: true, }, { title: "Release", subtitle: "v2.1", dateFrom: day(18), dateTo: day(22), timeFrom: at(10), timeTo: at(17), draggable: true, }, { title: "Onboarding", subtitle: "Berlin office", dateFrom: day(25), dateTo: day(28), timeFrom: at(9), timeTo: at(16), draggable: true, }, ];
export default function Example() { // Only the month and the entries are set; look and behavior are widget defaults. // A timed entry on one day is text with a stripe. The start time sits at the right edge. // Entries without times are light gray bars (Public Holiday, Team Offsite), with the same stripe. // A timed entry across days is the same kind of bar, lined up with the days. The end time sits at the right edge; if the bar wraps, its first row shows the start time at the right edge of the start day. // // Drag and save: draggable: true lets an entry be moved to another day. Its left and right // edge make it shorter or longer, from one day to several. The calendar only reports the // result. Write endData into the entry at entryIndex, then save it to your API. // If saving fails, put startData back. Without this step the entry jumps back on the next update. // // Day 5 has four timed entries. maxTimeEntries.amount: 2 shows two and turns the rest into "+ 2 more". const [entries, setEntries] = useState(initialEntries);
const persist = ( entryIndex: number, endData: | ArcWidgetCalendarGridEntryDragSavePayload | ArcWidgetCalendarGridDailyEntryDragSavePayload, ) => { setEntries((current) => current.map((entry, index) => index === entryIndex ? { ...entry, ...endData } : entry, ), ); };
return ( <ArcWidgetCalendarGrid config={{ lang: "en", dateSettings: { month: 1, year: 2027, header: { title: {} }, day: { maxTimeEntries: { amount: 2, suffix: "more" } }, }, timeEntries: entries, }} onEntryDragSave={(entryIndex, _startData, endData) => persist(entryIndex, endData) } onDailyEntryDragSave={(entryIndex, _startData, endData) => persist(entryIndex, endData) } /> ); }</code></pre>
Props del componente
id
ID de DOM opcional. No es necesario en el uso normal; se genera automáticamente si se omite.
data
Configuración de tipo ArcWidgetCalendarGridData. Pasa los cambios como objetos nuevos; gestiona los datos de negocio y la selección en el estado de React.
onAction
Fallback opcional (type: string, ...args: unknown[]) => unknown. El callback concreto tiene prioridad. Detalles: <a href="/docs/react/patterns/react-state-events">Estado y eventos</a>.
onEntryClick
Índice (base 0) de la cita pulsada en config.timeEntries. Solo se dispara para entradas con clickable: true.
onEntryClick?: (entryIndex: number) => void;
onDayClick
Día seleccionado como milisegundos epoch a las 00:00 UTC. Solo se dispara con dateSettings.day.clickable: true.
onDayClick?: (dateMillis: number) => void;
onEntryDragSave
Fin del arrastre de una cita con hora: startData (antes) y endData (destino) — persiste endData.
onEntryDragSave?: (
entryIndex: number,
startData: ArcWidgetCalendarGridEntryDragSavePayload,
endData: ArcWidgetCalendarGridEntryDragSavePayload
) => void;
onDailyEntryDragSave
Fin del arrastre de una cita de día completo: startData y endData solo con dateFrom / dateTo — persiste endData.
onDailyEntryDragSave?: (
entryIndex: number,
startData: ArcWidgetCalendarGridDailyEntryDragSavePayload,
endData: ArcWidgetCalendarGridDailyEntryDragSavePayload
) => void;
Configuración
Los siguientes campos pertenecen a config. Los tamaños se indican como strings, los números y valores de tiempo según su tipo respectivo.
width
Ancho del widget, p. ej. "100%".
Tipo: string.
height
Altura del widget, p. ej. "320px". Los valores porcentuales necesitan un contenedor padre con altura definida.
Tipo: string.
timeZoneBalance
Desplazamiento en horas que se suma a las etiquetas de hora de las citas, p. ej. -1. Valor por defecto: 0.
Tipo: number.
styles
Marco, líneas de la cuadrícula, superficie de la cabecera y tonos de texto (borders, borderColor, borderSize, borderRadius, backgroundColor, headerBackgroundColor, fontColor, mutedColor, subtleColor).
Tipo: ArcWidgetCalendarGridStyles.
dateSettings
Rango visible, cabeceras, celdas de día y marcados. Establece month (1–12) y year para una vista mensual de seis semanas, o startDate con endDate / duration (días) para un rango libre. Sin ninguno de los dos se muestra el mes actual.
Tipo: ArcWidgetCalendarGridDateSettings.
lang
Locale para los nombres de los días de la semana y de los meses, p. ej. "en". También define el primer día de la semana: domingo para en-US, en-CA, ja, ko, zh-CN y zh-TW; si no, lunes. Valor por defecto: "de".
Tipo: string.
timeEntries
Citas con valores de fecha, horas y contenidos. Omite tanto timeFrom como timeTo para una barra de día completo.
Tipo: ArcWidgetCalendarGridTimeEntry[].
Comportamiento y límites
- Para JSX en citas usa
customLayout. Los campos estándar title, subtitle y value se procesan como texto o HTML.
- Los valores de fecha son milisegundos epoch del día a las 00:00 UTC, p. ej.
Date.UTC(2024, 10, 6); las horas son milisegundos desde el inicio del día (9 * 3600000 = 09:00). Omite ambas horas para una barra de día completo. Consulta <a href="/docs/react/patterns/react-dates">Fecha y hora</a>.
clickable: true activa la selección. Un índice de callback no es un ID de registro; resuélvelo mediante tu lista actual de entradas.
- Arrastre: establece
draggable: true en la entrada. Callback onEntryDragSave(entryIndex, startData, endData) / onDailyEntryDragSave — persiste endData (dateFrom/dateTo/timeFrom/timeTo). startData es el estado antes del arrastre. Sin draggable: true la entrada no se puede arrastrar. El mismo indicador añade una zona de agarre en el inicio y el final reales de la entrada: arrástrala para acortar o alargar la entrada por días completos, de un día a varios y de vuelta, también entre filas de semanas. Solo cambian dateFrom/dateTo; las horas se mantienen. Si una entrada con hora se reduce a un día y terminaría antes de empezar, timeTo pasa justo después de timeFrom. El resultado llega a los mismos callbacks que al mover. En pantallas táctiles, toca primero la entrada y luego arrastra su borde. Escape cancela.
dateSettings.month empieza en uno: enero es 1. Los marcados están en dateSettings.highlights.
Los campos ArcWidgetSlot admitidos permiten elementos JSX individuales, texto o descriptores de widget. Pasa texto externo como texto JSX; los strings HTML se interpretan como HTML. <a href="/docs/react/patterns/nested-widget-descriptors">Combinar contenidos</a>.
Tipos de datos
Estos tipos relacionados con el widget se exportan desde el paquete. También están disponibles tipos comunes como ArcWidgetSlot y ArcReactWidgetProps. Los objetos de configuración son cerrados, por lo que una clave mal escrita o no admitida se notifica como error de tipo.
export type ArcWidgetCalendarGridBorderLine =
| boolean
| {
enabled?: boolean;
color?: string;
width?: string;
};
export interface ArcWidgetCalendarGridBorders { color?: string; width?: string; outer?: ArcWidgetCalendarGridBorderLine; columns?: ArcWidgetCalendarGridBorderLine; rows?: ArcWidgetCalendarGridBorderLine; }
export interface ArcWidgetCalendarGridStyles { borders?: ArcWidgetCalendarGridBorders; borderColor?: string; borderSize?: string; borderRadius?: string; backgroundColor?: string; headerBackgroundColor?: string; fontColor?: string; mutedColor?: string; subtleColor?: string; }
export interface ArcWidgetCalendarGridHeaderText { label?: string; fontSize?: string; fontColor?: string; fontWeight?: string | number; alignX?: 'left' | 'center' | 'right'; }
export interface ArcWidgetCalendarGridHeader { backgroundColor?: string; title?: ArcWidgetCalendarGridHeaderText; subtitle?: ArcWidgetCalendarGridHeaderText; }
export interface ArcWidgetCalendarGridWeekdays { label?: string; backgroundColor?: string; alignX?: 'left' | 'center' | 'right'; fontSize?: string; fontColor?: string; fontWeight?: string | number; padding?: string; }
export interface ArcWidgetCalendarGridWeekNumber { fontColor?: string; fontWeight?: string | number; fontSize?: string; }
export interface ArcWidgetCalendarGridWeek { show?: boolean; number?: ArcWidgetCalendarGridWeekNumber; }
export interface ArcWidgetCalendarGridDayNumber { fontSize?: string; fontColor?: string; fontWeight?: string | number; backgroundColor?: string; borderRadius?: string; border?: string; }
export interface ArcWidgetCalendarGridMaxTimeEntries { amount?: number; suffix?: string; }
export interface ArcWidgetCalendarGridDay { clickable?: boolean; height?: string; alignX?: 'left' | 'center' | 'right'; backgroundColor?: string; hoverBackgroundColor?: string; padding?: string; number?: ArcWidgetCalendarGridDayNumber; maxTimeEntries?: ArcWidgetCalendarGridMaxTimeEntries; }
export interface ArcWidgetCalendarGridHighlight { weekday?: number; date?: number; day?: ArcWidgetCalendarGridDay; color?: string; }
export interface ArcWidgetCalendarGridDateSettings { month?: number; year?: number; startDate?: number; endDate?: number; duration?: number; header?: ArcWidgetCalendarGridHeader; weekdays?: ArcWidgetCalendarGridWeekdays; week?: ArcWidgetCalendarGridWeek; day?: ArcWidgetCalendarGridDay; highlights?: ArcWidgetCalendarGridHighlight[]; }
export type ArcWidgetCalendarGridEntryStyles = ArcWidgetCssProperties & { fontColor?: string; };
export interface ArcWidgetCalendarGridTimeEntry { id?: string | number; title?: string; subtitle?: string; value?: string; customLayout?: ArcWidgetSlot; dateFrom?: number; dateTo?: number; timeFrom?: number; timeTo?: number; styles?: ArcWidgetCalendarGridEntryStyles; borderLeft?: string; clickable?: boolean; draggable?: boolean; }
export interface ArcWidgetCalendarGridData { width?: string; height?: string; timeZoneBalance?: number; lang?: string; styles?: ArcWidgetCalendarGridStyles; dateSettings?: ArcWidgetCalendarGridDateSettings; timeEntries?: ArcWidgetCalendarGridTimeEntry[]; }
export interface ArcWidgetCalendarGridEntryDragSavePayload { dateFrom: number; dateTo: number; timeFrom: number; timeTo: number; }
export interface ArcWidgetCalendarGridDailyEntryDragSavePayload { dateFrom: number; dateTo: number; }
export interface ArcWidgetCalendarGridProps extends ArcReactWidgetProps<ArcWidgetCalendarGridData> { onEntryClick?: (entryIndex: number) => void; onDayClick?: (dateMillis: number) => void; onEntryDragSave?: ( entryIndex: number, startData: ArcWidgetCalendarGridEntryDragSavePayload, endData: ArcWidgetCalendarGridEntryDragSavePayload ) => void; onDailyEntryDragSave?: ( entryIndex: number, startData: ArcWidgetCalendarGridDailyEntryDragSavePayload, endData: ArcWidgetCalendarGridDailyEntryDragSavePayload ) => void; }</code></pre>