Arc Rider Docs · Markdown

Mini Widgets

Button

Button en React

Dispara una acción y muestra un estado de carga durante un proceso asíncrono.

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 define title; todo lo demás es el valor por defecto: fondo negro, texto blanco en negrita, esquinas redondeadas y un hover más claro.

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

export default function Example() { // Only required fields are set on the button; everything else is the widget default. // The Layout fills its surroundings and centers the button. return ( &lt;ArcWidgetLayout data={{ direction: 'vertical', alignX: 'center', alignY: 'center', width: '100%', height: '100%', backgroundColor: '#F8FAFC', border: { radius: '12px' }, blocks: [ { width: 'auto', value: &lt;ArcWidgetButton data={{ title: 'Save' }} /&gt; }, ], }} /&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 ArcWidgetButtonData. 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. Devuelve una promesa para que loading siga visible hasta que se resuelva.

onClick?: () => void | Promise<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.

title

Etiqueta en negrita; como slot también es posible con JSX. Usa '' para botones solo con icono.

Tipo: ArcWidgetSlot.

subtitle

Segunda etiqueta más pequeña junto al título.

Tipo: ArcWidgetSlot.

icon

Icono junto al título, p. ej. un ArcWidgetIcon.

Tipo: ArcWidgetSlot.

prefix

Contenido fijado al borde inicial, antes del icono y el título.

Tipo: ArcWidgetSlot.

suffix

Contenido fijado al borde final; necesita un width mayor que el contenido.

Tipo: ArcWidgetSlot.

alignX

Alineación horizontal del icono y el título. Con prefix o suffix se aplica al espacio entre ambos. Valor por defecto: center.

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

alignY

Alineación vertical del contenido cuando height es mayor que el contenido. Valor por defecto: center.

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

iconPosition

Posición del icono en relación con el título. Valor por defecto: left.

Tipo: 'left' | 'right' | 'top' | 'bottom'.

gap

Espacio entre prefix, icono, título, badge y suffix. Valor por defecto: 0 entre slots, 5px entre icono y título.

Tipo: string.

paddingX

Espaciado interno a izquierda y derecha. Valor por defecto: 0.8em.

Tipo: string.

paddingY

Espaciado interno arriba y abajo. Valor por defecto: 0.5em.

Tipo: string.

width

Ancho del botón. Valor por defecto: fit-content.

Tipo: string.

height

Alto del botón; 'auto' mantiene la altura del contenido. Valor por defecto: auto.

Tipo: string.

borderRadius

Redondeo de las esquinas. Valor por defecto: 0.6em.

Tipo: string.

borderColor

Color del borde de 1px. Valor por defecto: transparente, así el borde toma el color de fondo.

Tipo: string.

backgroundColor

Color de fondo. Valor por defecto: #18181B. Con un color claro, define también fontColor.

Tipo: string.

fontColor

Color del texto; el indicador de carga lo sigue. Valor por defecto: #ffffff.

Tipo: string.

fontSize

Tamaño de fuente como valor CSS; el subtítulo usa el 80 % de este valor. Valor por defecto: 13px.

Tipo: string.

hoverActions

Colores mientras el puntero está sobre el botón (fontColor, iconColor, backgroundColor, borderColor), más la duración de la transición (animation, p. ej. "0.2s"). Sin ellos, solo el aspecto por defecto se aclara en hover; un backgroundColor propio mantiene su color.

Tipo: ArcWidgetButtonHoverActions.

showBadge

Muestra el badge. Valor por defecto: false.

Tipo: boolean.

badgeTitle

Contenido del badge, p. ej. un contador.

Tipo: ArcWidgetSlot.

badgeColor

Color del texto del badge. Valor por defecto: #ffffff.

Tipo: string.

badgeBackground

Fondo del badge. Valor por defecto: #e9595d.

Tipo: string.

badgeBorderColor

Color del borde del badge. Valor por defecto: #ffffff.

Tipo: string.

badgePosition

inside coloca el badge después del título; outside lo fija en la esquina superior derecha. Valor por defecto: inside.

Tipo: 'inside' | 'outside'.

badgeGap

Espacio antes de un badge interior. Valor por defecto: 6px si gap no está establecido; si no, gap.

Tipo: string.

loading

Estado de carga mientras la promesa de onClick está pendiente, activado con show: true. Muestra un indicador en el botón o, con overlay, una tarjeta centrada. Oculta contenidos concretos con hide (icon también admite 'auto'). El indicador toma el color del texto y crece con el tamaño de fuente.

Tipo: ArcWidgetButtonLoading.

Navigation: AI Defaults

Para la navegación y las acciones con etiqueta, usa alignX: 'left', iconPosition: 'left' y gap: '8px'. Los valores por defecto existentes del runtime no cambian. alignY controla la alineación vertical; paddingX/paddingY, el espaciado interno.

Usa ArcWidgetIcon con iconSet: 'phosphor' en el slot del icono. Envuelve los iconos decorativos con aria-hidden y pointerEvents: 'none' para que no intercepten los clics del botón. La plantilla React muestra el patrón completo.

Comportamiento y límites

  • onClick puede devolver una promesa. Con loading.show: true, el estado de carga permanece activo hasta el final de este proceso.
  • Captura los errores de guardado en tu callback y muéstralos en tu propio estado. Un indicador de carga no sustituye un mensaje de éxito o error.

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 ArcWidgetButtonHoverActions {
	fontColor?: string;
	iconColor?: string;
	backgroundColor?: string;
	borderColor?: string;
	animation?: string;
}

export interface ArcWidgetButtonLoadingIndicator { type?: 'dots' | 'spinner' | 'pulse'; color?: string; width?: string; height?: string; }

export interface ArcWidgetButtonLoadingHide { icon?: boolean | 'auto'; title?: boolean; subtitle?: boolean; badge?: boolean; prefix?: boolean; suffix?: boolean; }

export interface ArcWidgetButtonLoadingStyles { fontColor?: string; iconColor?: string; backgroundColor?: string; borderColor?: string; }

export interface ArcWidgetButtonOverlayText { value: string; styles?: string; }

export interface ArcWidgetButtonOverlaySequence { after?: number; when?: boolean; priority?: number; title?: string | ArcWidgetButtonOverlayText; message?: string | ArcWidgetButtonOverlayText; indicator?: ArcWidgetButtonLoadingIndicator; }

export interface ArcWidgetButtonOverlay { title?: string | ArcWidgetButtonOverlayText; message?: string | ArcWidgetButtonOverlayText; sequences?: ArcWidgetButtonOverlaySequence[]; indicator?: ArcWidgetButtonLoadingIndicator; width?: string; height?: string; backgroundColor?: string; }

export interface ArcWidgetButtonLoading { show?: boolean; indicator?: ArcWidgetButtonLoadingIndicator; hideOnFinish?: boolean; minDuration?: number; position?: 'left' | 'right' | 'prefix' | 'suffix'; hideTitle?: boolean; hide?: ArcWidgetButtonLoadingHide; styles?: 'hover' | 'default' | ArcWidgetButtonLoadingStyles; overlay?: true | ArcWidgetButtonOverlay; }

export interface ArcWidgetButtonData { title?: ArcWidgetSlot; subtitle?: ArcWidgetSlot; icon?: ArcWidgetSlot; prefix?: ArcWidgetSlot; suffix?: ArcWidgetSlot; alignX?: 'left' | 'center' | 'right'; alignY?: 'top' | 'center' | 'bottom'; iconPosition?: 'left' | 'right' | 'top' | 'bottom'; gap?: string; paddingX?: string; paddingY?: string; width?: string; height?: string; borderRadius?: string; borderColor?: string; backgroundColor?: string; fontColor?: string; fontSize?: string; hoverActions?: ArcWidgetButtonHoverActions; showBadge?: boolean; badgeTitle?: ArcWidgetSlot; badgeColor?: string; badgeBackground?: string; badgeBorderColor?: string; badgePosition?: 'inside' | 'outside'; badgeGap?: string; loading?: ArcWidgetButtonLoading; }

export interface ArcWidgetButtonProps extends ArcReactWidgetProps&lt;ArcWidgetButtonData&gt; { onClick?: () =&gt; void | Promise&lt;void&gt;; }</code></pre>