Arc Rider Docs · Markdown

Mini Widgets

Custom Layout

Layout en React

Organiza widgets y páginas completas horizontal o verticalmente. Empieza las apps nuevas con Arc Layout; HTML puede seguir siendo el host y un límite semántico. Un host solo define la altura del viewport, sin tener que recrear el layout de la página con CSS Grid o Flexbox.

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>.

Widget-First-App-Shell: AI Defaults

Para una barra lateral, una cabecera y el contenido, usa la plantilla React completa, incluida también en el paquete como examples/blueprints/blueprint-app-shell.tsx.

  • Host: una altura definida, como 100dvh; layouts de shell anidados: height: '100%'.
  • Bloques verticales: cabecera height: 'auto', contenido restante height: 'fraction'.
  • Scroll: coloca un Layout con height: '100%' y scrollSettings: { scrollY: true } en el bloque restante.
  • Bloques horizontales: ancho de barra lateral fijo/automático, región principal width: 'fraction'.
  • Usa min-width:0;min-height:0; en los bloques limitados; cambia la dirección responsiva y los tamaños a la vez.
  • Usa fraction para la altura del bloque, no para la altura del Layout interior. La región padre debe tener una altura definida.

Ejemplo completo

import {
  ArcWidgetBadge,
  ArcWidgetInput,
  ArcWidgetLayout,
} from '@arcrider/arcwidgets-react';

const row = (number: string, title: string) =&gt; ({ value: ( &lt;ArcWidgetLayout data={{ direction: 'horizontal', gap: '12px', height: '48px', blocks: [ { width: '52px', value: ( &lt;ArcWidgetBadge data={{ value: number, singleColor: '#3f3f46', borderRadius: '6px', paddingX: '8px', paddingY: '4px', }} /&gt; ), }, { width: 'fraction', value: ( &lt;ArcWidgetInput data={{ type: 'number', labelSettings: { title }, numpad: { suffix: '€' }, }} /&gt; ), }, ], }} /&gt; ), });

export default function Example() { return ( &lt;ArcWidgetLayout data={{ direction: 'vertical', gap: '8px', width: '420px', blocks: [row('1.1', 'Inspection'), row('1.2', 'Travel')], }} /&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 ArcWidgetLayoutData. 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>.

onClick

Se dispara al hacer clic en un layout clickable fuera de sus bloques. Los clics en los bloques nunca llegan a él.

onClick?: () => void;

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 pertenecen a data. Los tamaños se indican como strings, los números y valores de tiempo según su tipo respectivo.

direction

Dirección en la que se apilan los bloques. Establécela siempre de forma explícita. Valor por defecto: vertical.

Tipo: 'horizontal' | 'vertical'.

alignX

Colocación horizontal de los bloques. between solo funciona con direction: 'horizontal', stretch solo con 'vertical'. Valor por defecto: center.

Tipo: 'left' | 'center' | 'right' | 'between' | 'stretch'.

alignY

Colocación vertical de los bloques. between solo funciona con direction: 'vertical', stretch solo con 'horizontal'. Valor por defecto: center.

Tipo: 'top' | 'center' | 'bottom' | 'between' | 'stretch'.

width

Ancho del layout. 'fraction' ocupa el ancho restante del bloque circundante; cualquier otro valor es CSS. Valor por defecto: 100%.

Tipo: 'fraction' | (string & {}).

height

Altura del layout como CSS, p. ej. "320px". Usa un valor definido para shells con scroll y 'auto' para layouts que se ajustan al contenido. Los valores porcentuales necesitan un contenedor padre con altura fija. Valor por defecto: 100%.

Tipo: string.

gap

Espacio entre bloques. Valor por defecto: 2px. Un valor negativo, por ejemplo '-8px', superpone los bloques en esa medida. Los bloques con width: 'fraction' (o height: 'fraction' en una columna) se estiran sobre la superposición, por eso los bloques superpuestos necesitan un tamaño propio.

Tipo: string.

overlapOrder

Qué bloque queda encima cuando gap es negativo: 'end' el último bloque, 'start' el primero (izquierda en una fila, arriba en una columna). El bloque bajo el puntero siempre pasa al frente. Valor por defecto: end.

Tipo: 'start' | 'end'.

backgroundColor

Color de fondo.

Tipo: string.

minWidth

Ancho mínimo del layout como CSS, p. ej. "320px". El layout nunca se hace más estrecho; el área circundante se desplaza o recorta. Los bloques también aceptan minWidth.

Tipo: string.

maxWidth

Ancho máximo del layout como CSS, p. ej. "1000px". Un layout con maxWidth se centra horizontalmente en su contenedor, así obtienes una columna de página sin CSS adicional. Los bloques también aceptan maxWidth (p. ej. "100%" para mantener un hijo ancho dentro del bloque); un bloque se posiciona con el alignX de su layout.

Tipo: string.

border

Borde y radio de esquina del contenedor del layout: 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. El radio no recorta a los hijos, así que da el mismo radio a un bloque interior con color. Los bloques aceptan el mismo objeto border.

Tipo: ArcWidgetLayoutBorder.

paddingX

Espaciado interno a izquierda y derecha.

Tipo: string.

paddingY

Espaciado interno arriba y abajo.

Tipo: string.

lineHeight

Altura de línea que heredan los bloques.

Tipo: string.

scrollSettings

Scroll del contenedor del layout (scrollX, scrollY). Las barras de desplazamiento permanecen ocultas; scrollY necesita una height definida.

Tipo: ArcWidgetLayoutScrollSettings.

styles

Declaraciones CSS en bruto que se aplican al final al contenedor del layout, p. ej. 'padding: 8px; color: #333'.

Tipo: string.

clickable

true muestra un cursor de puntero y dispara onClick para clics fuera de los bloques. Valor por defecto: false.

Tipo: boolean.

blocks

Filas (vertical) o columnas (horizontal) del layout. Cada bloque tiene su propio tamaño, alineación (alignX, alignY), colores, styles y contenido en value; consulta ArcWidgetLayoutBlock.

Tipo: ArcWidgetLayoutBlock[].

Comportamiento y límites

  • Establece direction de forma explícita. fraction distribuye el espacio restante en el eje correspondiente; una altura de 100% necesita un contenedor padre con límite definido.
  • 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[].value admite JSX. Vincula los eventos de componentes anidados directamente a sus props de callback.
  • Para clics en el layout o en un bloque debe establecerse clickable: true en el objeto correspondiente. onBlockClick recibe el índice en blocks.
  • Para layouts de página completa, da al elemento de la app circundante una altura definida, como 100dvh.

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 ArcWidgetLayoutBorder {
	color?: string;
	width?: string;
	style?: 'solid' | 'dashed' | 'dotted' | 'double';
	radius?: string;
	sides?: Array<'top' | 'right' | 'bottom' | 'left'>;
}

export interface ArcWidgetLayoutBlock { value?: ArcWidgetSlot; width?: 'fraction' | (string &amp; {}); minWidth?: string; maxWidth?: string; height?: 'fraction' | (string &amp; {}); alignX?: 'left' | 'center' | 'right'; alignY?: 'top' | 'center' | 'bottom' | 'stretch'; paddingX?: string; paddingY?: string; backgroundColor?: string; border?: ArcWidgetLayoutBorder; color?: string; backgroundImage?: string; backgroundSize?: string; backgroundPosition?: string; lineHeight?: string; styles?: string; clickable?: boolean; blockId?: string; }

export interface ArcWidgetLayoutScrollSettings { scrollX?: boolean; scrollY?: boolean; }

export interface ArcWidgetLayoutData { direction?: 'horizontal' | 'vertical'; alignX?: 'left' | 'center' | 'right' | 'between' | 'stretch'; alignY?: 'top' | 'center' | 'bottom' | 'between' | 'stretch'; width?: 'fraction' | (string &amp; {}); minWidth?: string; maxWidth?: string; height?: string; gap?: string; overlapOrder?: 'start' | 'end'; paddingX?: string; paddingY?: string; backgroundColor?: string; border?: ArcWidgetLayoutBorder; lineHeight?: string; scrollSettings?: ArcWidgetLayoutScrollSettings; styles?: string; clickable?: boolean; blocks?: ArcWidgetLayoutBlock[]; }

export interface ArcWidgetLayoutProps extends ArcReactWidgetProps&lt;ArcWidgetLayoutData&gt; { onClick?: () =&gt; void; onBlockClick?: (blockIndex: number) =&gt; void; }</code></pre>