Arc Rider Docs · Markdown

Premium Widgets

Custom Drawing

Drawing en React

Edita formas y dibujos en un lienzo. La aplicación asigna IDs, guarda los cambios y procesa las exportaciones.

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 { ArcWidgetDrawing } from '@arcrider/arcwidgets-react';

export default function Example() { // Only required fields are set; everything else is the widget default. return ( &lt;ArcWidgetDrawing config={{ height: '480px', artboard: { width: 600, height: 400 }, shapes: [ { id: 1, shapeDataValue: { type: 'rect', x: 60, y: 60, width: 200, height: 120, }, }, { id: 2, shapeDataValue: { type: 'circle', cx: 420, cy: 160, r: 70 }, }, { id: 3, shapeDataValue: { type: 'polyline', points: '80,300 200,340 320,280 460,330', }, }, { id: 4, shapeDataValue: { type: 'polygon', points: '380,240 470,260 500,330 420,370 360,320', fill: 'rgba(0, 120, 255, 0.2)', }, }, { id: 5, shapeDataValue: { type: 'text', x: 60, y: 200, text: 'Floor plan', fontSize: 20, fontWeight: 'bold', }, }, ], }} /&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 ArcWidgetDrawingData. 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>.

onShapeCreate

Se ha dibujado una forma o colocado un sticker. El segundo argumento es un objeto de completion: establece su promise con un promise que se resuelva con el nuevo ID.

onShapeCreate?: (payload: ArcWidgetDrawingShapeCreatePayload, completion: ArcWidgetDrawingShapeCreateCompletion) => void;

onShapeUpdate

Se ha soltado una forma guardada tras arrastrarla o pulsarla con la herramienta Mover. Entrega shape_id, la nueva geometría y, con dataBag, el bag completo.

onShapeUpdate?: (payload: ArcWidgetDrawingShapeUpdatePayload) => void;

onShapeActivate

Se ha pulsado una forma con clickable: true. Entrega su shape_id.

onShapeActivate?: (payload: ArcWidgetDrawingShapeActivatePayload) => void;

onExport

Ha terminado una exportación con destino field. Entrega el formato y el archivo como data URL.

onExport?: (payload: ArcWidgetDrawingExportPayload) => void;

Configuración

Los siguientes campos pertenecen a config. Los tamaños en objetos anidados son números en píxeles; los tamaños del widget son strings CSS.

artboard

Obligatorio. Área de dibujo y exportación en píxeles.

Tipo: ArcWidgetDrawingArtboard ({ width: number; height: number }).

shapes

Obligatorio. Formas con id estable y geometría en shapeDataValue (objeto o string JSON). Usa [] para un lienzo vacío. Opcional por forma: movable, resizable, rotate, scalable, clickable, stickerUID, label, placeholders, export, tooltip, sidebarItem.

Tipo: ArcWidgetDrawingShape[].

height

Altura del widget, p. ej. "700px". Los valores porcentuales necesitan un contenedor padre con altura fija.

Tipo: string.

width

Ancho del widget, p. ej. "100%".

Tipo: string.

canvas

Área de trabajo desplazable alrededor del artboard, en píxeles: width / height, u offsetX / offsetY como espacio adicional a cada lado. Sin este campo, la vista puede moverse aproximadamente un viewport más allá del artboard.

Tipo: ArcWidgetDrawingCanvas.

zooming

Zoom inicial (default, 1), límites (min 0.1, max sin límite), paso de los botones (step, 0.1) y velocidad con Ctrl + rueda (panSpeed, 0.002).

Tipo: ArcWidgetDrawingZooming.

drawingSettings

Trazo para nuevas líneas, rectángulos, círculos y polígonos: strokeColor (por defecto black) y strokeWidth en píxeles de pantalla (por defecto 1). polygon.fillColor fija el relleno de los nuevos polígonos (por defecto: sin relleno). text contiene los valores por defecto del texto nuevo: color (por defecto black), fontSize (por defecto 16), fontWeight (por defecto normal) y fontFamily (por defecto Arial, Helvetica, sans-serif).

Tipo: ArcWidgetDrawingSettings.

tools

Con rectángulo, círculo y trazo libre, arrastrar siempre crea una forma nueva, también sobre otras formas. Un toque selecciona la forma de debajo; arrastrar justo sobre la línea de una forma movible la mueve, y el cursor muestra ahí la cruz de mover. Los textos se cogen por toda su caja. Imágenes y stickers no tienen línea; con estas herramientas solo se mueven si están seleccionados. Los rectángulos, círculos, líneas y polígonos sin relleno se cogen por la línea, así su interior queda libre para dibujar. Los polígonos con relleno, imágenes, stickers y textos se cogen por toda su superficie. Los polígonos también se colocan sobre otras formas; con la herramienta de texto, un toque sobre un texto lo abre para editarlo.

useMoveTool: true hace que las formas solo se puedan seleccionar y coger con la herramienta Mover; en las demás herramientas, un toque sobre una forma crea contenido nuevo o anula la selección.

Los tiradores están activados por defecto (resize: false los desactiva). Aparecen en las esquinas y en el centro de cada lado de la forma seleccionada para agrandarla o reducirla. Los tiradores laterales cambian solo el ancho o el alto; las formas que mantienen sus proporciones escalan de forma uniforme desde el lado opuesto. resize: { stroke: true } hace lo mismo y además escala el trazo (strokeWidth) con el tamaño. Imágenes, stickers, círculos y texto mantienen sus proporciones; rectángulos, líneas y polígonos se estiran libremente. El nuevo tamaño llega por onShapeUpdate. Por forma, resizable lo sobrescribe (resizable: { stroke: true } solo para esa forma). Las formas con movable: false o scalable: false nunca tienen tiradores de tamaño.

Un tirador de rotación queda encima de la forma seleccionada (activado por defecto; rotate: false o { enabled: false } lo oculta). Al arrastrarlo se guarda rotation en grados, en sentido horario, en onShapeUpdate / shapeDataValue. { step: 15 } encaja al arrastrar (por defecto 15; 0 es libre). Por forma, rotate lo sobrescribe (rotate: false o { step: 45 }). Las formas con movable: false no tienen el tirador; los círculos no lo muestran. Los stickers se pueden rotar aunque scalable: false. También puedes fijar rotation en los datos sin usar el tirador.

selection: { color: '#2563EB' } define el color del marco de selección, de los tiradores y de la fila activa en la lista de formas (cualquier color CSS, por defecto rosa #EC4899). El marco va sobre el borde de la forma, por el centro de los tiradores, y gira con la forma.

Un clic en el lienzo vacío o en un fondo bloqueado (movable: false, sin acciones) anula la selección, con cualquier herramienta. Escape cambia primero a la herramienta Mover; un segundo Escape anula la selección. Con Mover, el cursor muestra la cruz de mover sobre la línea de una forma, donde se puede coger. Un toque con rectángulo, círculo o trazo libre ya no deja una forma de 1 px.

Tipo: ArcWidgetDrawingTools.

create

enabled: false desactiva las herramientas de dibujo y los stickers. Desplazar, hacer zoom, mover y pulsar siguen funcionando. Valor por defecto: true.

Tipo: ArcWidgetDrawingCreate.

stickerTypes

Stickers que los usuarios pueden colocar: uid, image, width, height y, opcionalmente, icon, label, originX / originY, default, labelPlaceholder, defaultLabel, defaultPlaceholders.

Tipo: ArcWidgetDrawingStickerType[].

toolbarSettings

Orden y agrupación de los botones de la barra de herramientas en top y bottom. Las entradas son IDs de herramienta ("move", "draw", "rect", "circle", "polygon", "text", "image", "export"), "stickers", { tool, icon }, { sticker, icon } o, en top, un grupo { group, label, icon, items }. Los botones que no aparecen en la lista no se muestran.

Tipo: ArcWidgetDrawingToolbarSettings.

exportSettings

Botón y formatos de exportación. allowedTypes es obligatorio y enumera "jpg", "png", "svg" o ajustes por formato. target: "field" pasa el archivo a onExport; "file" (por defecto) lo descarga.

Tipo: ArcWidgetDrawingExportSettings.

dataBag

Lee la geometría de una key de un bag JSON en shapeDataValue, de modo que tus demás claves se conservan. onShapeUpdate devuelve el bag completo como bag.

Tipo: ArcWidgetDrawingDataBag.

rightSideContent

Barra lateral a la derecha del lienzo con header, content (showShapeLayers o value) y footer. Oculta si se omite; show: false la oculta.

Tipo: ArcWidgetDrawingSidebar.

Comportamiento y límites

  • Cada forma necesita un id estable y shapeDataValue como objeto o string JSON serializado; las formas sin shapeDataValue no se dibujan.
  • Al crear obtienes un segundo parámetro: establece completion.promise con un promise que se resuelva con el nuevo ID. Adopta la misma forma con este ID en tu estado.
  • onShapeUpdate entrega shape_id y la nueva geometría en shape_data_value. Reemplaza la forma correspondiente de manera inmutable en tu estado.
  • onExport requiere exportSettings.allowedTypes: [{ format: "png", target: "field" }]. target: "field" pasa la imagen como data URL a onExport; target: "file" inicia la descarga en el navegador.

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 type ArcWidgetDrawingShapeType = 'rect' | 'circle' | 'polyline' | 'polygon' | 'text' | 'image' | 'sticker';

export interface ArcWidgetDrawingShapeData { type: ArcWidgetDrawingShapeType; x?: number; y?: number; width?: number; height?: number; cx?: number; cy?: number; r?: number; points?: string; href?: string; stickerUID?: string; stroke?: string; strokeWidth?: number; rotation?: number; fill?: string; text?: string; fontSize?: number; fontWeight?: string | number; fontFamily?: string; [key: string]: unknown; }

export type ArcWidgetDrawingTooltipStyles = ArcWidgetCssProperties;

export interface ArcWidgetDrawingTooltip { content?: ArcWidgetSlot; width?: number | string; height?: number | string; alignX?: 'left' | 'center' | 'right'; alignY?: 'top' | 'center' | 'bottom'; offsetX?: number; offsetY?: number; styles?: ArcWidgetDrawingTooltipStyles; }

export interface ArcWidgetDrawingSidebarItem { header?: ArcWidgetSlot; content?: ArcWidgetSlot; hide?: boolean; }

export interface ArcWidgetDrawingShapeMovable { requireSelection?: boolean; }

export interface ArcWidgetDrawingShapeResizable { stroke?: boolean; }

export interface ArcWidgetDrawingShapeRotate { enabled?: boolean; step?: number; }

export interface ArcWidgetDrawingShape { id: string | number; shapeDataValue?: ArcWidgetDrawingShapeData | string; movable?: boolean | ArcWidgetDrawingShapeMovable; resizable?: boolean | ArcWidgetDrawingShapeResizable; rotate?: boolean | ArcWidgetDrawingShapeRotate; scalable?: boolean; clickable?: boolean; stickerUID?: string; label?: string | number; placeholders?: Record&lt;string, string | number&gt;; export?: boolean; tooltip?: ArcWidgetDrawingTooltip; sidebarItem?: ArcWidgetDrawingSidebarItem; }

export type ArcWidgetDrawingIcon = string | ArcNestedWidgetDescriptor;

export interface ArcWidgetDrawingStickerLabel { value: string; visible?: boolean; fontColor?: string; fontSize?: number | string; maxWidth?: number | string; }

export interface ArcWidgetDrawingStickerType { uid: string; image: string; icon?: ArcWidgetDrawingIcon; label?: string | ArcWidgetDrawingStickerLabel; width: number; height: number; originX?: number; originY?: number; default?: boolean; labelPlaceholder?: string; defaultLabel?: string | number; defaultPlaceholders?: Record&lt;string, string | number&gt;; }

export type ArcWidgetDrawingTool = 'move' | 'draw' | 'rect' | 'circle' | 'polygon' | 'text' | 'image' | 'export';

export type ArcWidgetDrawingToolbarItem = | ArcWidgetDrawingTool | 'stickers' | { tool: ArcWidgetDrawingTool; icon?: ArcWidgetDrawingIcon; } | { sticker: string; icon?: ArcWidgetDrawingIcon; };

export interface ArcWidgetDrawingToolbarGroup { group: string; label?: string; icon?: ArcWidgetDrawingIcon; items: ArcWidgetDrawingToolbarItem[]; }

export interface ArcWidgetDrawingToolbarSettings { top?: (ArcWidgetDrawingToolbarItem | ArcWidgetDrawingToolbarGroup)[]; bottom?: ArcWidgetDrawingToolbarItem[]; }

export type ArcWidgetDrawingExportFormat = 'jpg' | 'png' | 'svg' | 'pdf';

export type ArcWidgetDrawingExportTarget = 'file' | 'field';

export interface ArcWidgetDrawingExportType { format: ArcWidgetDrawingExportFormat; target?: ArcWidgetDrawingExportTarget; mergeFile?: boolean; apiKey?: string; autoExport?: boolean; autoExportDelay?: number; }

export interface ArcWidgetDrawingExportSettings { allowedTypes: (ArcWidgetDrawingExportFormat | ArcWidgetDrawingExportType)[]; target?: ArcWidgetDrawingExportTarget; apiKey?: string; mergeFile?: string; iconColor?: string; }

export interface ArcWidgetDrawingArtboard { width: number; height: number; }

export interface ArcWidgetDrawingCanvas { width?: number; height?: number; offsetX?: number; offsetY?: number; }

export interface ArcWidgetDrawingZooming { default?: number; min?: number; max?: number; step?: number; panSpeed?: number; }

export interface ArcWidgetDrawingPolygonSettings { fillColor?: string; }

export interface ArcWidgetDrawingTextSettings { color?: string; fontSize?: number; fontWeight?: string | number; fontFamily?: string; }

export interface ArcWidgetDrawingSettings { strokeColor?: string; strokeWidth?: number; polygon?: ArcWidgetDrawingPolygonSettings; text?: ArcWidgetDrawingTextSettings; }

export interface ArcWidgetDrawingTools { useMoveTool?: boolean; resize?: boolean | ArcWidgetDrawingShapeResizable; rotate?: boolean | ArcWidgetDrawingShapeRotate; selection?: ArcWidgetDrawingSelection; }

export interface ArcWidgetDrawingSelection { color?: string; }

export interface ArcWidgetDrawingCreate { enabled?: boolean; }

export interface ArcWidgetDrawingDataBag { key: string; encoding?: 'raw' | 'urlEncoded'; }

export interface ArcWidgetDrawingSidebarContent { showShapeLayers?: boolean; value?: ArcWidgetSlot; }

export interface ArcWidgetDrawingSidebar { show?: boolean; width?: string; header?: ArcWidgetSlot; content?: ArcWidgetDrawingSidebarContent; footer?: ArcWidgetSlot; }

export interface ArcWidgetDrawingData { artboard: ArcWidgetDrawingArtboard; shapes: ArcWidgetDrawingShape[]; height?: string; width?: string; canvas?: ArcWidgetDrawingCanvas; zooming?: ArcWidgetDrawingZooming; drawingSettings?: ArcWidgetDrawingSettings; tools?: ArcWidgetDrawingTools; create?: ArcWidgetDrawingCreate; stickerTypes?: ArcWidgetDrawingStickerType[]; toolbarSettings?: ArcWidgetDrawingToolbarSettings; exportSettings?: ArcWidgetDrawingExportSettings; dataBag?: ArcWidgetDrawingDataBag; rightSideContent?: ArcWidgetDrawingSidebar; }

export interface ArcWidgetDrawingShapeCreatePayload { shape_data_value: ArcWidgetDrawingShapeData; sticker_uid: string | null; }

export interface ArcWidgetDrawingShapeCreateCompletion { promise?: Promise&lt;string | number&gt;; }

export interface ArcWidgetDrawingShapeUpdatePayload { shape_id: string | number; shape_data_value: ArcWidgetDrawingShapeData; bag?: Record&lt;string, unknown&gt;; }

export interface ArcWidgetDrawingShapeActivatePayload { shape_id: string | number; }

export interface ArcWidgetDrawingExportPayload { format: ArcWidgetDrawingExportFormat; base64: string; }

export interface ArcWidgetDrawingProps extends ArcReactWidgetProps&lt;ArcWidgetDrawingData&gt; { onShapeCreate?: (payload: ArcWidgetDrawingShapeCreatePayload, completion: ArcWidgetDrawingShapeCreateCompletion) =&gt; void; onShapeUpdate?: (payload: ArcWidgetDrawingShapeUpdatePayload) =&gt; void; onShapeActivate?: (payload: ArcWidgetDrawingShapeActivatePayload) =&gt; void; onExport?: (payload: ArcWidgetDrawingExportPayload) =&gt; void; }</code></pre>