Arc Rider Docs · Markdown

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 ( &lt;ArcWidgetCalendarGrid config={{ lang: &quot;en&quot;, dateSettings: { month: 1, year: 2027, header: { title: {} }, day: { maxTimeEntries: { amount: 2, suffix: &quot;more&quot; } }, }, timeEntries: entries, }} onEntryDragSave={(entryIndex, _startData, endData) =&gt; persist(entryIndex, endData) } onDailyEntryDragSave={(entryIndex, _startData, endData) =&gt; persist(entryIndex, endData) } /&gt; ); }</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 &amp; { 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&lt;ArcWidgetCalendarGridData&gt; { onEntryClick?: (entryIndex: number) =&gt; void; onDayClick?: (dateMillis: number) =&gt; void; onEntryDragSave?: ( entryIndex: number, startData: ArcWidgetCalendarGridEntryDragSavePayload, endData: ArcWidgetCalendarGridEntryDragSavePayload ) =&gt; void; onDailyEntryDragSave?: ( entryIndex: number, startData: ArcWidgetCalendarGridDailyEntryDragSavePayload, endData: ArcWidgetCalendarGridDailyEntryDragSavePayload ) =&gt; void; }</code></pre>