Premium Widgets
Custom Kanban
Kanban en React
Representa tareas o procesos como tarjetas en columnas de estado. La selección y el estado guardado del tablero pertenecen a tu aplicación React.
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
Solo se definen los títulos de las columnas y las tarjetas; todo lo demás es el valor por defecto: cabeceras oscuras con texto pequeño en negrita, columnas grises con el mismo redondeo que el Button y un pequeño espacio entre cabecera y columna.
import { ArcWidgetKanban, ArcWidgetLayout } from '@arcrider/arcwidgets-react';
export default function Example() { // Only required fields are set on the board; everything else is the widget default. // The Layout gives the board a white surface. return ( <ArcWidgetLayout data={{ direction: 'vertical', alignX: 'stretch', height: 'auto', paddingX: '12px', paddingY: '12px', backgroundColor: '#FFFFFF', border: { radius: '12px' }, blocks: [ { value: ( <ArcWidgetKanban data={{ height: '320px', swimlanes: [ { title: 'To do', items: [ { id: 'brief', title: 'Write brief', subtitle: 'Due Friday' }, { id: 'venue', title: 'Book venue', subtitle: 'Due next week' }, ], }, { title: 'In progress', items: [{ id: 'poster', title: 'Design poster', subtitle: 'Draft 2' }], }, { title: 'Done', items: [{ id: 'kickoff', title: 'Kickoff call', subtitle: 'Completed' }], }, ], }} /> ), }, ], }} /> ); }</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 ArcWidgetKanbanData. 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>.
onItemClick
Evento del ratón y posición de la tarjeta. No se dispara para tarjetas con clickable: false ni justo después de un arrastre.
onItemClick?: (event: MouseEvent, payload: ArcWidgetKanbanItemClickPayload) => void;
onItemDrop
Origen y nueva posición de una tarjeta movida; la tarjeta queda al final de la columna o sección de destino. Un promise de guardado devuelto mantiene el tablero bloqueado hasta que se resuelve; si se rechaza, la tarjeta vuelve a su posición anterior.
onItemDrop?: (payload: ArcWidgetKanbanItemDropPayload) => void | Promise<unknown>;
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.
height
Altura del widget, p. ej. "320px". Por defecto 100%. Los valores porcentuales necesitan un contenedor padre con altura definida.
Tipo: string.
empty
Visualización para columnas vacías; true o una etiqueta y colores propios. Desactivada por defecto; el empty propio de una columna tiene prioridad. La etiqueta integrada está en alemán, así que establece value para otros idiomas.
Tipo: boolean | ArcWidgetKanbanEmpty.
swimlanes
Columnas con items planos o sections con nombre, además de colores de cabecera, burbuja de recuento, slots en la cabecera (slotLeft, slotRight) y ancho mínimo. backgroundColorHeader: 'transparent' da una cabecera sin color.
Tipo: ArcWidgetKanbanSwimlane[].
scrollSettings
Desplazamiento de todo el tablero: scrollX y scrollY, cada uno con scrollbar: { enabled: boolean }. Ambos están desactivados por defecto. Una columna desplaza sus propias tarjetas verticalmente; desactívalo con el scrollSettings.scrollY de la columna.
Tipo: ArcWidgetKanbanScrollSettings.
styles
Medidas del tablero.
minWidth: ancho mínimo de todas las columnas, p. ej. '300px'. Las columnas se reparten el ancho libre por igual; si ya no caben, el tablero se desplaza hacia los lados (necesita scrollSettings.scrollX). El minWidth de una columna tiene prioridad. Por defecto: 150px.
Tipo: { minWidth?: string }.
scrollBar
Muestra y diseña las barras de scroll: la barra vertical dentro de cada columna y la barra horizontal del tablero bajo las columnas. Ambas están ocultas por defecto aunque el área sigue desplazándose. Los campos coinciden con el scrollBar de la tabla (showScrollBar, height, backgroundColor, handle), pero el track no tiene color por defecto. board y lanes cambian solo una de las dos barras.
Tipo: ArcWidgetKanbanScrollBar.
collapsible
Añade a la cabecera de cada columna un control para contraer la columna. true muestra el chevron integrado, que gira al contraer. Un objeto define además defaultCollapsed (empezar contraída) e iconos propios: iconExpand (mientras está contraída, un clic la expande) e iconCollapse (mientras está abierta, un clic la contrae). Los iconos también valen para los controles de los grupos. El estado se recuerda; la elección del usuario gana a defaultCollapsed.
Tipo: boolean | ArcWidgetKanbanCollapsible.
Comportamiento y límites
- Una columna contiene o bien
items planos o bien sections con nombre, cada una con sus propios items. Da a las secciones un id estable para que se recuerde si están abiertas o contraídas.
onItemClick entrega primero el evento del ratón, luego los índices de columna, sección y tarjeta. Estos índices se refieren a la estructura de datos pasada; las secciones ocultas por hideWhenEmpty no se cuentan.
- Las tarjetas se pueden arrastrar por defecto; establece
draggable: false para bloquear una tarjeta. Devuelve tu promise de guardado desde onItemDrop; si el promise se rechaza, la tarjeta vuelve a su posición anterior. Actualiza tu estado tras un guardado exitoso.
- La visualización de columna vacía se activa con
empty: true o una configuración propia.
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, ArcWidgetStyles 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 interface ArcWidgetKanbanItemClickPayload {
swimlane_index: number;
section_index: number;
item_index: number;
item_index_in_section: number;
}
export interface ArcWidgetKanbanItemDropPayload { source_swimlane_index: number; target_swimlane_index: number; item_index: number; source_section_index: number; target_section_index: number; item_index_in_section: number; target_index_in_section: number; }
export interface ArcWidgetKanbanItem { id?: string | number; title?: ArcWidgetSlot; subtitle?: ArcWidgetSlot; value?: ArcWidgetSlot; clickable?: boolean; draggable?: boolean; backgroundColor?: string; backgroundColorTop?: string; backgroundColorBottom?: string; fontColor?: string; paddingX?: string; paddingY?: string; borderRadius?: string; borderColor?: string; borderWidth?: string; borderPosition?: 'left' | 'right' | 'top' | 'bottom'; borderStroke?: 'solid' | 'dashed' | 'dotted'; insetBorder?: boolean | ArcWidgetKanbanInsetBorder; }
export interface ArcWidgetKanbanInsetSegment { color?: string; stroke?: 'solid' | 'dashed' | 'dotted'; label?: string; size?: 'fraction' | 'auto' | (string & {}); }
export interface ArcWidgetKanbanInsetBorder { enabled?: boolean; position?: 'left' | 'right' | 'top' | 'bottom'; width?: string; stroke?: 'solid' | 'dashed' | 'dotted'; color?: string; align?: 'start' | 'center' | 'end'; segments?: ArcWidgetKanbanInsetSegment[]; }
export interface ArcWidgetKanbanSection { id?: string | number; title?: ArcWidgetSlot; items?: ArcWidgetKanbanItem[]; hideWhenEmpty?: boolean; collapsed?: boolean; }
export interface ArcWidgetKanbanEmpty { enabled?: boolean; value?: ArcWidgetSlot; backgroundColor?: string; fontColor?: string; fontWeight?: string | number; }
export interface ArcWidgetKanbanScrollAxis { scrollbar?: { enabled?: boolean; }; }
export interface ArcWidgetKanbanScrollBarHandle { backgroundColor?: string; borderRadius?: string; }
export interface ArcWidgetKanbanScrollBarLook { showScrollBar?: boolean; height?: string; backgroundColor?: string; handle?: ArcWidgetKanbanScrollBarHandle; }
export interface ArcWidgetKanbanScrollBar extends ArcWidgetKanbanScrollBarLook { board?: ArcWidgetKanbanScrollBarLook; lanes?: ArcWidgetKanbanScrollBarLook; }
export interface ArcWidgetKanbanScrollSettings { scrollX?: ArcWidgetKanbanScrollAxis; scrollY?: ArcWidgetKanbanScrollAxis; }
export interface ArcWidgetKanbanSwimlaneScrollSettings { scrollY?: ArcWidgetKanbanScrollAxis; }
export interface ArcWidgetKanbanSwimlane { title?: ArcWidgetSlot; amount?: ArcWidgetSlot; showAmount?: boolean; slotLeft?: ArcWidgetSlot; slotRight?: ArcWidgetSlot; minWidth?: string; backgroundColorHeader?: string; backgroundColorBody?: string; fontColor?: string; empty?: boolean | ArcWidgetKanbanEmpty; items?: ArcWidgetKanbanItem[]; sections?: ArcWidgetKanbanSection[]; scrollSettings?: ArcWidgetKanbanSwimlaneScrollSettings; }
export interface ArcWidgetKanbanCollapsible { enabled?: boolean; defaultCollapsed?: boolean; iconExpand?: ArcWidgetSlot; iconCollapse?: ArcWidgetSlot; }
export interface ArcWidgetKanbanStyles { minWidth?: string; }
export interface ArcWidgetKanbanData { height?: string; empty?: boolean | ArcWidgetKanbanEmpty; swimlanes?: ArcWidgetKanbanSwimlane[]; styles?: ArcWidgetKanbanStyles; scrollSettings?: ArcWidgetKanbanScrollSettings; scrollBar?: ArcWidgetKanbanScrollBar; collapsible?: boolean | ArcWidgetKanbanCollapsible; insetBorder?: boolean | ArcWidgetKanbanInsetBorder; }
export interface ArcWidgetKanbanProps extends ArcReactWidgetProps<ArcWidgetKanbanData> { onItemClick?: (event: MouseEvent, payload: ArcWidgetKanbanItemClickPayload) => void; onItemDrop?: (payload: ArcWidgetKanbanItemDropPayload) => void | Promise<unknown>; }</code></pre>