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';
import { useState } from 'react';
import type { ArcWidgetDrawingShape } from '@arcrider/arcwidgets-react';
const lang = document.documentElement.lang.startsWith('en') ? 'en' : document.documentElement.lang.startsWith('es') ? 'es' : 'de'; const requested = new URLSearchParams(location.search).get('data'); const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo'; const t = (de: string, en: string, es: string) => lang === 'en' ? en : lang === 'es' ? es : de;
const demoShapes: ArcWidgetDrawingShape[] = [ { id: 'mark-1', clickable: true, shapeDataValue: { type: 'circle', cx: 140, cy: 120, r: 36, stroke: '#059669', strokeWidth: 3, fill: 'rgba(16,185,129,0.18)', }, }, { id: 'mark-2', clickable: true, shapeDataValue: { type: 'rect', x: 240, y: 80, width: 170, height: 100, rx: 12, stroke: '#d97706', strokeWidth: 3, fill: 'rgba(245,158,11,0.2)', }, }, ];
const busyShapes: ArcWidgetDrawingShape[] = [ ...demoShapes, { id: 'mark-3', clickable: true, shapeDataValue: { type: 'circle', cx: 460, cy: 250, r: 48, stroke: '#e11d48', strokeWidth: 3, fill: 'rgba(244,63,94,0.16)', }, }, { id: 'mark-4', clickable: true, shapeDataValue: { type: 'rect', x: 80, y: 230, width: 120, height: 70, rx: 10, stroke: '#7c3aed', strokeWidth: 3, fill: 'rgba(139,92,246,0.16)', }, }, ];
export default function Example() { const [shapes, setShapes] = useState<ArcWidgetDrawingShape[]>( pack === 'empty' ? [] : pack === 'busy' ? busyShapes : demoShapes, ); const [selected, setSelected] = useState( t( 'Form ziehen oder skalieren', 'Drag or resize a shape', 'Arrastra o escala una forma', ), ); return ( <> <ArcWidgetDrawing id="drawing" data={{ height: '420px', canvas: { width: 1000, height: 800 }, artboard: { width: 600, height: 400 }, create: { enabled: true }, shapes, }} onShapeActivate={({ shape_id }) => setSelected(String(shape_id))} onShapeCreate={(payload, completion) => { const id = crypto.randomUUID(); setShapes((previous) => [ ...previous, { id, shapeDataValue: payload.shape_data_value }, ]); completion.promise = Promise.resolve(id); }} onShapeUpdate={(payload) => setShapes((previous) => previous.map((shape) => shape.id === payload.shape_id ? { ...shape, shapeDataValue: payload.shape_data_value } : shape, ), ) } /> <p aria-live="polite"> {t('Formen', 'Shapes', 'Formas')}: {shapes.length} ·{' '} {t('Auswahl', 'Selection', 'Selección')}: {selected} </p> </> ); }</code></pre>
Props del componente
id
ID opcional y estable de la instancia del widget. Sin especificarlo, React genera un ID.
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
Nueva forma y un objeto de completion mutable. Establece su promise con el ID asignado.
onShapeCreate?: (payload: ArcWidgetDrawingCreatePayload, completion: { promise?: Promise<string | number> }) => void;
onShapeUpdate
Forma modificada y su ID.
onShapeUpdate?: (payload: { shape_id: string | number; shape_data_value: Record<string, unknown>; bag?: unknown }) => void;
onShapeActivate
ID de la forma activada.
onShapeActivate?: (payload: { shape_id: string | number }) => void;
onExport
Formato de exportación e imagen como data URL.
onExport?: (payload: { format: string; base64: string }) => 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.
height
Altura del widget, p. ej. "320px". Los valores porcentuales necesitan un contenedor padre con altura definida.
Tipo: string.
canvas
Área de trabajo en píxeles.
Tipo: { width?: number; height?: number; [key: string]: unknown }.
artboard
Área de dibujo y exportación en píxeles.
Tipo: { width?: number; height?: number; [key: string]: unknown }.
shapes
Formas con id estable y geometría en shapeDataValue.
Tipo: ArcWidgetDrawingShape[].
exportSettings
Formatos de exportación y destino de salida. Para el callback, selecciona actualmente target: "field".
Tipo: Record<string, unknown>.
create
Permite o impide crear nuevas formas mediante enabled.
Tipo: { enabled?: boolean }.
tools
Herramientas de dibujo disponibles.
Tipo: Record<string, unknown>[].
stickerTypes
Stickers disponibles.
Tipo: Record<string, unknown>[].
drawingSettings
Ajustes para el dibujo.
Tipo: Record<string, unknown>.
zooming
Límites e incremento del zoom.
Tipo: { min?: number; max?: number; step?: number }.
Comportamiento y límites
- Cada forma necesita un
id estable y shapeDataValue como objeto o string JSON serializado. El widget React normaliza id para el núcleo de dibujo.
- Al crear obtienes un segundo parámetro: establece
completion.promise con un promise que contenga el nuevo ID. Adopta la misma forma con este ID en tu estado.
onShapeUpdate entrega shape_id y la nueva forma. Reemplaza la forma correspondiente de manera inmutable en tu estado.
- Para
onExport se necesita actualmente exportSettings.allowedTypes: [{ format: "png", target: "field" }]. El valor histórico field selecciona el callback de data URL; no se escribe ningún campo de base de datos. 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. Las firmas de índice permiten extensiones; no garantizan que el widget evalúe campos arbitrarios.
export interface ArcWidgetDrawingShape {
id: string | number;
shapeDataValue?: string | Record<string, unknown>;
shapeId?: string | number;
[key: string]: unknown;
}
export interface ArcWidgetDrawingData extends ArcWidgetBaseData { height?: string; canvas?: { width?: number; height?: number; [key: string]: unknown }; artboard?: { width?: number; height?: number; [key: string]: unknown }; shapes?: ArcWidgetDrawingShape[]; exportSettings?: Record<string, unknown>; create?: { enabled?: boolean }; tools?: Record<string, unknown>[]; stickerTypes?: Record<string, unknown>[]; drawingSettings?: Record<string, unknown>; zooming?: { min?: number; max?: number; step?: number }; }
export interface ArcWidgetDrawingCreatePayload { shape_data_value: Record<string, unknown>; sticker_uid?: string | null; } export interface ArcWidgetDrawingProps extends ArcReactWidgetProps<ArcWidgetDrawingData> { onShapeCreate?: (payload: ArcWidgetDrawingCreatePayload, completion: { promise?: Promise<string | number> }) => void; onShapeUpdate?: (payload: { shape_id: string | number; shape_data_value: Record<string, unknown>; bag?: unknown }) => void; onShapeActivate?: (payload: { shape_id: string | number }) => void; onExport?: (payload: { format: string; base64: string }) => void; }</code></pre>