Mini Widgets
Custom Grid
Grid en React
Organiza el contenido en filas y columnas a la vez: tarjetas, mosaicos de KPI y dashboards. Sin un número de columnas, el Grid llena la fila con tantas columnas como permita el ancho, así que se adapta a la pantalla sin breakpoints. Usa Arc Layout para una sola dirección (una fila o una columna) y para el marco de la página; usa el Grid cuando el contenido necesita ambas dimensiones.
Referencia para @arcrider/arcwidgets-react@0.1.0-alpha.7. <a href="/docs/react/intro/setup-react">Instalación</a> · <a href="/docs/react/intro/react-components">Todos los componentes</a>.
AI Defaults
Ejemplo completo
import { useState } from 'react';
import {
ArcWidgetBadge,
ArcWidgetGrid,
ArcWidgetText,
} from '@arcrider/arcwidgets-react';
export default function Example() { const [selected, setSelected] = useState('none'); const ids = ['revenue', 'orders', 'chart', 'inbox'];
// columnSpan and rowSpan make a block wider or taller than one cell. // The chart block takes two columns and two rows; the neighbours flow around it. return ( <ArcWidgetGrid onBlockClick={(index) => setSelected(ids[index] ?? 'none')} data={{ columns: 4, gap: '12px', paddingX: '16px', paddingY: '16px', backgroundColor: '#F4F4F5', blockDefaults: { clickable: true, paddingX: '16px', paddingY: '16px', backgroundColor: '#FFFFFF', border: { color: '#D4D4D8', radius: '12px' }, }, blocks: [ { blockId: 'revenue', value: <ArcWidgetText data={{ value: 'Revenue EUR 24,300', fontWeight: '700' }} />, }, { blockId: 'orders', value: <ArcWidgetText data={{ value: 'Orders 128', fontWeight: '700' }} />, }, { blockId: 'chart', columnSpan: 2, rowSpan: 2, alignX: 'center', alignY: 'center', value: 'Chart area (2 x 2)', }, { blockId: 'inbox', columnSpan: 2, value: ( <ArcWidgetBadge data={{ value: Selected: ${selected}, singleColor: '#3f3f46', borderRadius: '6px', paddingX: '8px', paddingY: '4px', }} /> ), }, ], }} /> ); }</code></pre>
Props del componente
id
DOM id opcional. No hace falta en el uso normal; se genera automáticamente si falta.
data
Configuración de tipo ArcWidgetGridData. Pasa los cambios como objetos nuevos; mantén los datos de negocio y la selección en el estado de React.
onAction
Fallback opcional (type: string, ...args: unknown[]) => unknown. El callback específico tiene prioridad. Detalles: <a href="/docs/react/patterns/react-state-events">Estado y eventos</a>.
onBlockClick
Se dispara al hacer clic en un bloque clickable. blockIndex es el índice de base cero en data.blocks.
onBlockClick?: (blockIndex: number) => void;
Configuración
Los siguientes campos van en data. Los tamaños se indican como cadenas.
columns
Número de columnas, p. ej. 3. Si se omite (o 'auto-fill'), se usan tantas columnas como permita el ancho. 'auto-fit' también se ajusta al ancho, pero estira las celdas cuando hay pocos bloques. Por defecto: 'auto-fill'.
Tipo: number | 'auto-fill' | 'auto-fit' | (string & {}).
columnWidth
Ancho mínimo de una columna, p. ej. "280px". Las columnas crecen por igual hasta llenar la fila. Por defecto: 200px. Con un columns fijo y sin columnWidth, las columnas se reparten el ancho y se estrechan libremente en pantallas estrechas.
Tipo: string.
gap
Espacio entre bloques, igual para filas y columnas. Por defecto: 10px.
Tipo: string.
width
Ancho del Grid como CSS. Por defecto: 100%.
Tipo: string.
height
Altura del Grid como CSS. Usa un valor definido cuando el Grid llena un marco y 'auto' para grids del tamaño de su contenido. Por defecto: auto.
Tipo: string.
paddingX
Espaciado interior a izquierda y derecha.
Tipo: string.
paddingY
Espaciado interior arriba y abajo.
Tipo: string.
backgroundColor
Color de fondo del Grid.
Tipo: string.
border
Línea y radio de esquina del contenedor del Grid: color, width, style, radius y sides. La línea se dibuja en cuanto se define color, width, style o sides; radius por sí solo solo redondea las esquinas. Los bloques usan el mismo objeto border.
Tipo: ArcWidgetGridBorder.
blockDefaults
Valores que cada bloque toma mientras no defina uno propio, p. ej. { paddingX: '16px', backgroundColor: '#FFFFFF', border: { radius: '12px' } }. Un valor definido en el bloque sustituye al predeterminado por completo, también en border. value y blockId nunca se toman de los valores predeterminados.
Tipo: Omit<ArcWidgetGridBlock, 'value' | 'blockId'>.
styles
Declaraciones CSS en bruto que se aplican al final al contenedor del Grid, p. ej. 'padding: 8px; color: #333'.
Tipo: string.
blocks
Celdas en orden de lectura. Cada bloque tiene su propio tamaño, extensiones, alineación (alignX, alignY), colores, styles y contenido en value; consulta ArcWidgetGridBlock.
Tipo: ArcWidgetGridBlock[].
Comportamiento y límites
- Las filas miden lo que mide su bloque más alto.
rowSpan hace que un bloque ocupe varias filas y columnSpan varias columnas. Los bloques siguientes fluyen alrededor de los bloques con extensión.
- Con
columns fijo, un columnSpan mayor que el número de columnas se limita para que no aparezcan columnas adicionales. En modo auto-fill no hay un número fijo, así que la extensión se aplica tal como se indica.
- Cada bloque es un contenedor flex horizontal. Posiciona su contenido con
blocks[].alignX (left, center, right; por defecto left) y blocks[].alignY (top, center, bottom, stretch; por defecto center). text-align en blocks[].styles no puede centrar el contenido.
blocks[].width y blocks[].height fijan el tamaño del contenido dentro de su área. 'fraction' llena el área.
blocks[].value admite JSX. Enlaza los eventos de los componentes anidados directamente a sus props de callback.
- Los Grids se pueden anidar. Cada Grid aplica solo sus propios ajustes, nunca los del Grid que lo rodea.
- Para los clics en bloques,
clickable: true debe estar definido en el bloque. El Grid en sí no tiene callback de clic.
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 interface ArcWidgetGridBorder {
color?: string;
width?: string;
style?: 'solid' | 'dashed' | 'dotted' | 'double';
radius?: string;
sides?: Array<'top' | 'right' | 'bottom' | 'left'>;
}
export interface ArcWidgetGridBlock { value?: ArcWidgetSlot; columnSpan?: number; rowSpan?: number; width?: string; height?: string; alignX?: 'left' | 'center' | 'right'; alignY?: 'top' | 'center' | 'bottom' | 'stretch'; paddingX?: string; paddingY?: string; backgroundColor?: string; border?: ArcWidgetGridBorder; color?: string; backgroundImage?: string; backgroundSize?: string; backgroundPosition?: string; lineHeight?: string; styles?: string; clickable?: boolean; blockId?: string; }
export interface ArcWidgetGridData { columns?: number | 'auto-fill' | 'auto-fit' | (string & {}); columnWidth?: string; gap?: string; width?: string; height?: string; paddingX?: string; paddingY?: string; backgroundColor?: string; border?: ArcWidgetGridBorder; styles?: string; blockDefaults?: Omit<ArcWidgetGridBlock, 'value' | 'blockId'>; blocks?: ArcWidgetGridBlock[]; }
export interface ArcWidgetGridProps extends ArcReactWidgetProps<ArcWidgetGridData> { onBlockClick?: (blockIndex: number) => void; }</code></pre>