Premium Widgets
Custom Calendar (Week)
CalendarWeek en React
Muestra citas en una vista semanal con cuadrícula horaria. El ejemplo mantiene la selección y las citas en la aplicación.
Referencia para @arcrider/arcwidgets-react@0.1.0-alpha.5. <a href="/docs/react/intro/setup-react">Instalación</a> · <a href="/docs/react/intro/react-components">Todos los componentes</a>.
Ejemplo completo
import { useState } from 'react';
import { ArcWidgetCalendarWeek } from '@arcrider/arcwidgets-react';
import type {
ArcWidgetCalendarWeekCreatePayload,
ArcWidgetCalendarWeekDailyEntryDragSavePayload,
ArcWidgetCalendarWeekDragSourcePayload,
ArcWidgetCalendarWeekEntryDragSavePayload,
ArcWidgetCalendarWeekTimeEntry,
} from '@arcrider/arcwidgets-react';
const DAY = 86400000; const monday = new Date(2027, 0, 4).getTime(); const day = (index: number) => monday + index * DAY; const at = (hours: number, minutes = 0) => (hours * 60 + minutes) * 60000;
const initialEntries: ArcWidgetCalendarWeekTimeEntry[] = [ { title: 'Team Offsite', subtitle: '2 days', dateFrom: day(0), dateTo: day(1), draggable: true, }, { title: 'Public Holiday', subtitle: 'All-day', dateFrom: day(2), dateTo: day(2), draggable: true, }, { title: 'Team Meeting', subtitle: '09:00 - 10:30', dateFrom: day(0), dateTo: day(0), timeFrom: at(9), timeTo: at(10, 30), draggable: true, }, { title: 'Code Review', subtitle: '10:00 - 11:00', dateFrom: day(1), dateTo: day(1), timeFrom: at(10), timeTo: at(11), draggable: true, }, { title: 'Workshop', subtitle: '13:30 - 17:00', dateFrom: day(1), dateTo: day(1), timeFrom: at(13, 30), timeTo: at(17), insetBorder: { stroke: 'dotted' }, draggable: true, }, { title: 'Sprint Planning', subtitle: '09:00 - 12:00', dateFrom: day(4), dateTo: day(4), timeFrom: at(9), timeTo: at(12), draggable: true, }, ];
export default function Example() { // Only the visible week, hours and entries are set; look and behavior are widget defaults. // Entries without times span whole days: one day (Public Holiday) or several (Team Offsite). // Inset line: every timed entry shows a vertical line on its left edge (all-day entries do not). // It takes the entry's styles.color, or #18181b. insetBorder on an entry changes that entry: // stroke ('solid', 'dashed' or 'dotted'), width, color, position ('left' or 'right'), // enabled: false hides it. Put insetBorder on data to apply it to all entries // (see the Minimalistic example); fields set on an entry win over it. // // Drag and save: draggable: true lets an entry be moved. The calendar only reports the drop. // Write endData into the entry at source.entry_index, then save it to your API. // If saving fails, put startData back. Without this step the entry jumps back on the next update. // // Create: createNew turns on drawing a new range over empty slots (or over the all-day row). // onCreate reports it; your app validates it, gives it an id and saves it. Without createNew // dragging over empty slots does nothing. const [entries, setEntries] = useState(initialEntries);
const persist = ( source: ArcWidgetCalendarWeekDragSourcePayload, endData: ArcWidgetCalendarWeekEntryDragSavePayload | ArcWidgetCalendarWeekDailyEntryDragSavePayload, ) => { setEntries((current) => current.map((entry, index) => (index === source.entry_index ? { ...entry, ...endData } : entry)), ); };
const create = (values: ArcWidgetCalendarWeekCreatePayload) => { const allDay = values.timeFrom === undefined; setEntries((current) => [ ...current, { id: new-${current.length + 1}, title: 'New entry', subtitle: allDay ? 'All-day' : undefined, ...values, draggable: true, }, ]); };
return ( <ArcWidgetCalendarWeek data={{ lang: 'en', dateSettings: { startDate: monday, duration: 7 }, timeSettings: { timeStart: at(8), duration: at(12) }, height: '800px', createNew: {}, timeEntries: entries, }} onCreate={create} onEntryDragSave={(_entryIndex, _startData, endData, source) => persist(source, endData)} onDailyEntryDragSave={(_entryIndex, _startData, endData, source) => persist(source, 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 ArcWidgetCalendarWeekData. 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 pieza pulsada. Solo se dispara para entradas con clickable: true. Los segmentos y las divisiones se despliegan en piezas separadas, por lo que el índice solo coincide con data.timeEntries en entradas sin segments.
onEntryClick?: (entryIndex: number) => void;
onDayClick
Día seleccionado como milisegundos epoch a las 00:00 UTC. Se dispara al hacer clic en la cabecera de un día con dateSettings.day.clickable: true.
onDayClick?: (dateMillis: number) => void;
onEntryDragSave
Fin del arrastre de una pieza con hora: startData (antes) y endData (destino) — persiste endData. source localiza la pieza en tus timeEntries (entry_index, segment_index, split_index). Cuando un grupo de segmentos se mueve en conjunto, el callback se dispara una vez por cada pieza movida.
onEntryDragSave?: (
entryIndex: number,
startData: ArcWidgetCalendarWeekEntryDragSavePayload,
endData: ArcWidgetCalendarWeekEntryDragSavePayload,
source: ArcWidgetCalendarWeekDragSourcePayload
) => 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: ArcWidgetCalendarWeekDailyEntryDragSavePayload,
endData: ArcWidgetCalendarWeekDailyEntryDragSavePayload,
source: ArcWidgetCalendarWeekDragSourcePayload
) => void;
onCreate
Nuevo rango dibujado sobre franjas vacías, o un createNew.item colocado. Requiere createNew. timeFrom / timeTo faltan en un rango de día completo. La validación y el guardado los realiza la aplicación.
onCreate?: (values: ArcWidgetCalendarWeekCreatePayload) => void;
Configuración
Los siguientes campos pertenecen a data. 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.
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). El círculo de hoy en la cabecera por defecto usa fontColor como relleno y backgroundColor como color del número.
Tipo: ArcWidgetCalendarWeekStyles.
weekdaySettings
Semana ISO y año que se muestran cuando dateSettings.startDate no está establecido, p. ej. { week: 1, year: 2027 }. El rango empieza entonces a las 00:00 UTC del primer día de esa semana.
Tipo: ArcWidgetCalendarWeekdaySettings.
weekStart
Primer día de la semana para weekdaySettings y la semana por defecto: 1 = lunes … 7 = domingo. Valor por defecto: 1.
Tipo: number.
dateSettings
Rango visible, cabecera de día y marcados. startDate (milisegundos epoch) define el primer día visible y tiene prioridad sobre weekdaySettings; las fechas de las entradas se colocan en relación con él. endDate (exclusivo) o duration (días, por defecto 7) define la longitud. Sábado y domingo se tiñen por defecto de un gris suave; un marcado para esos días sustituye el color y backgroundColor: 'transparent' lo quita. weekends: false oculta sábado y domingo desde el principio (el menú de ajustes puede volver a mostrarlos).
Tipo: ArcWidgetCalendarWeekDateSettings.
timeZoneBalance
Desplazamiento en horas que se suma a las etiquetas de hora y a las etiquetas de hora de las entradas, p. ej. -1; la posición de las entradas no cambia. Valor por defecto: 0.
Tipo: number.
timeSettings
Horas visibles del día: timeStart y duration en milisegundos (8 * 3600000 = 08:00). Por defecto: el día completo.
Tipo: ArcWidgetCalendarWeekTimeSettings.
currentTime
true muestra una línea de la hora actual; un string de color como "#f95757" define además su color. Valor por defecto: false.
Tipo: boolean | string.
dragStep
Paso de ajuste al arrastrar y crear, en milisegundos. Valor por defecto: 300000 (5 minutos).
Tipo: number.
lang
Locale para los nombres de los días de la semana y de los meses y para la barra de herramientas. Valor por defecto: "de".
Tipo: string.
timeSlotWidth
Ancho mínimo de una columna de día, p. ej. "200px".
Tipo: string.
timeSlotHeight
Altura mínima de una fila de hora. Valor por defecto: "50px". Si el calendario es más alto de lo que necesitan todas las horas con esta altura, las filas crecen por igual y no queda ninguna franja vacía bajo la última hora. Si es más bajo, el calendario se desplaza.
Tipo: string.
allDayHeight
Altura del área para citas de día completo, p. ej. "120px". Por defecto: se ajusta a sus entradas.
Tipo: string.
createNew
Activa la creación de citas; el nuevo rango llega en onCreate. Sin item, arrastrar sobre franjas vacías dibuja un rango. Con item, una cita predefinida sigue al puntero y se coloca con un clic.
Tipo: ArcWidgetCalendarWeekCreateNew.
segmentSettings
Comportamiento de arrastre de las entradas segmentadas: dayJump, lockGroups, edgeMagnetism y la toolbar de segmentos.
Tipo: ArcWidgetCalendarWeekSegmentSettings.
insetBorder
Línea vertical en el borde izquierdo de cada entrada con hora; las entradas de todo el día no la muestran. Está activa por defecto. Con { enabled: false } la ocultas en todas partes; con stroke, width, color y position cambias el estilo de todas las líneas. Un insetBorder en una entrada o segmento concreto tiene prioridad campo a campo. Con segments divides la línea en tramos, p. ej. uno por persona, si quieres colocados por hora (ver abajo).
Tipo: ArcWidgetCalendarWeekInsetBorder.
timeEntries
Citas con valores de fecha, horas y contenidos. Omite tanto timeFrom como timeTo para una barra de día completo.
Tipo: ArcWidgetCalendarWeekTimeEntry[].
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 en la misma base de tiempo que
dateSettings.startDate, p. ej. new Date(2027, 0, 4).getTime() para ambos; las horas son milisegundos desde el inicio del día (9 * 3600000 = 09:00). 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, source) / onDailyEntryDragSave — persiste endData en source.entry_index / source.segment_index. startData es el estado antes del arrastre. Sin draggable: true la entrada no se puede arrastrar.
- Guardar un arrastre, paso a paso: (1) escribe
endData en la entrada de source.entry_index en tu estado timeEntries, (2) guárdalo en tu backend, (3) si falla, restaura startData. El calendario se redibuja con los timeEntries que le pasas; una entrada que no actualizas vuelve a su posición anterior en la siguiente actualización. Ejemplo completo: calendar_week-00-defaults.tsx.
- El rango horario visible se configura mediante
timeSettings.timeStart y timeSettings.duration en milisegundos.
onCreate entrega los valores de la selección. Tu aplicación los valida, asigna un ID y adopta la nueva cita.
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 ArcWidgetCalendarWeekBorderLine =
| boolean
| {
enabled?: boolean;
color?: string;
width?: string;
};
export interface ArcWidgetCalendarWeekBorders { color?: string; width?: string; outer?: ArcWidgetCalendarWeekBorderLine; columns?: ArcWidgetCalendarWeekBorderLine; rows?: ArcWidgetCalendarWeekBorderLine; }
export interface ArcWidgetCalendarWeekStyles { borders?: ArcWidgetCalendarWeekBorders; borderColor?: string; borderSize?: string; borderRadius?: string; backgroundColor?: string; headerBackgroundColor?: string; fontColor?: string; mutedColor?: string; subtleColor?: string; }
export interface ArcWidgetCalendarWeekHeaderText { label?: string; fontSize?: string; fontColor?: string; fontWeight?: string | number; alignX?: 'left' | 'center' | 'right'; }
export interface ArcWidgetCalendarWeekHeader { backgroundColor?: string; title?: ArcWidgetCalendarWeekHeaderText; subtitle?: ArcWidgetCalendarWeekHeaderText; }
export interface ArcWidgetCalendarWeekHighlightStyles { backgroundColor?: string; borderColor?: string; borderSize?: string; borders?: Pick<ArcWidgetCalendarWeekBorders, 'color' | 'width' | 'columns' | 'rows'>; }
export interface ArcWidgetCalendarWeekHighlight { date?: number | string; weekday?: number; color?: string; styles?: ArcWidgetCalendarWeekHighlightStyles; title?: ArcWidgetCalendarWeekHeaderText; subtitle?: ArcWidgetCalendarWeekHeaderText; }
export interface ArcWidgetCalendarWeekDay { clickable?: boolean; }
export interface ArcWidgetCalendarWeekDateSettings { startDate?: number; endDate?: number; duration?: number; weekends?: boolean; header?: ArcWidgetCalendarWeekHeader; day?: ArcWidgetCalendarWeekDay; highlights?: ArcWidgetCalendarWeekHighlight[]; }
export interface ArcWidgetCalendarWeekdaySettings { week?: number; year?: number; }
export interface ArcWidgetCalendarWeekTimeSettings { timeStart?: number; duration?: number; }
export interface ArcWidgetCalendarWeekDayJump { threshold?: number; startTime?: number; }
export interface ArcWidgetCalendarWeekSegmentSettings { dayJump?: ArcWidgetCalendarWeekDayJump; lockGroups?: boolean; edgeMagnetism?: boolean; toolbar?: boolean; }
export interface ArcWidgetCalendarWeekInsetSegment { color?: string; stroke?: 'solid' | 'dashed' | 'dotted'; label?: string; size?: 'fraction' | 'auto' | (string & {}); timeFrom?: number; timeTo?: number; offset?: number; duration?: number; }
export interface ArcWidgetCalendarWeekInsetBorder { enabled?: boolean; position?: 'left' | 'right'; width?: string; stroke?: 'solid' | 'dashed' | 'dotted'; color?: string; align?: 'start' | 'center' | 'end'; segments?: ArcWidgetCalendarWeekInsetSegment[]; }
export type ArcWidgetCalendarWeekEntryStyles = ArcWidgetCssProperties;
export interface ArcWidgetCalendarWeekSplit { title?: string; subtitle?: string; value?: string; customLayout?: ArcWidgetSlot; styles?: ArcWidgetCalendarWeekEntryStyles; insetBorder?: ArcWidgetCalendarWeekInsetBorder; timeFrom?: number; timeTo?: number; offset?: number; duration?: number; }
export interface ArcWidgetCalendarWeekSegment { title?: string; subtitle?: string; value?: string; customLayout?: ArcWidgetSlot; styles?: ArcWidgetCalendarWeekEntryStyles; insetBorder?: ArcWidgetCalendarWeekInsetBorder; dateFrom?: number; dateTo?: number; timeFrom?: number; timeTo?: number; linked?: boolean; segmentSettings?: Pick<ArcWidgetCalendarWeekSegmentSettings, 'dayJump'>; splits?: ArcWidgetCalendarWeekSplit[]; clickable?: boolean; draggable?: boolean; }
export interface ArcWidgetCalendarWeekTimeEntry { id?: string | number; title?: string; subtitle?: string; value?: string; customLayout?: ArcWidgetSlot; dateFrom?: number; dateTo?: number; timeFrom?: number; timeTo?: number; styles?: ArcWidgetCalendarWeekEntryStyles; insetBorder?: ArcWidgetCalendarWeekInsetBorder; clickable?: boolean; draggable?: boolean; segments?: ArcWidgetCalendarWeekSegment[]; segmentSettings?: Pick<ArcWidgetCalendarWeekSegmentSettings, 'dayJump'>; }
export interface ArcWidgetCalendarWeekPlaceOffset { days?: number; time?: number; }
export interface ArcWidgetCalendarWeekPlaceSegment { title?: string; subtitle?: string; value?: string; customLayout?: ArcWidgetSlot; styles?: ArcWidgetCalendarWeekEntryStyles; insetBorder?: ArcWidgetCalendarWeekInsetBorder; linked?: boolean; duration?: number; offset?: ArcWidgetCalendarWeekPlaceOffset; dateFrom?: number; dateTo?: number; timeFrom?: number; timeTo?: number; splits?: ArcWidgetCalendarWeekSplit[]; }
export interface ArcWidgetCalendarWeekPlaceItem extends ArcWidgetCalendarWeekPlaceSegment { active?: boolean; segments?: ArcWidgetCalendarWeekPlaceSegment[]; }
export interface ArcWidgetCalendarWeekCreateNew { item?: ArcWidgetCalendarWeekPlaceItem | null; }
export interface ArcWidgetCalendarWeekData { width?: string; height?: string; lang?: string; weekStart?: number; weekdaySettings?: ArcWidgetCalendarWeekdaySettings; dateSettings?: ArcWidgetCalendarWeekDateSettings; timeSettings?: ArcWidgetCalendarWeekTimeSettings; timeZoneBalance?: number; currentTime?: boolean | string; dragStep?: number; timeSlotWidth?: string; timeSlotHeight?: string; allDayHeight?: string; styles?: ArcWidgetCalendarWeekStyles; createNew?: ArcWidgetCalendarWeekCreateNew; segmentSettings?: ArcWidgetCalendarWeekSegmentSettings; insetBorder?: ArcWidgetCalendarWeekInsetBorder; timeEntries?: ArcWidgetCalendarWeekTimeEntry[]; }
export interface ArcWidgetCalendarWeekEntryDragSavePayload { dateFrom: number; dateTo: number; timeFrom: number; timeTo: number; }
export interface ArcWidgetCalendarWeekDailyEntryDragSavePayload { dateFrom: number; dateTo: number; }
export interface ArcWidgetCalendarWeekDragSourcePayload { entry_index: number; segment_index: number | null; split_index: number | null; }
export interface ArcWidgetCalendarWeekCreatePayload { dateFrom: number; dateTo: number; timeFrom?: number; timeTo?: number; }
export interface ArcWidgetCalendarWeekProps extends ArcReactWidgetProps<ArcWidgetCalendarWeekData> { onEntryClick?: (entryIndex: number) => void; onDayClick?: (dateMillis: number) => void; onEntryDragSave?: ( entryIndex: number, startData: ArcWidgetCalendarWeekEntryDragSavePayload, endData: ArcWidgetCalendarWeekEntryDragSavePayload, source: ArcWidgetCalendarWeekDragSourcePayload ) => void; onDailyEntryDragSave?: ( entryIndex: number, startData: ArcWidgetCalendarWeekDailyEntryDragSavePayload, endData: ArcWidgetCalendarWeekDailyEntryDragSavePayload, source: ArcWidgetCalendarWeekDragSourcePayload ) => void; onCreate?: (values: ArcWidgetCalendarWeekCreatePayload) => void; }</code></pre>