Referencia de la API JavaScript (V3)

Esta referencia describe cada método, cada evento y cada ajuste que el motor de frontend V3 pone a disposición en window.Configento, con firma, valor devuelto, casos de error y un breve ejemplo. Está dirigida a desarrolladores de temas de tienda, plugins e integraciones propias. Cómo resolver tareas habituales y migrar desde código Legacy lo muestra la guía Interfaz JavaScript (V3).

Las firmas están escritas en notación TypeScript. Todo funciona también en JavaScript puro.

Ciclo de vida

1. La página carga https://cloud.configento.app/configento-v3/configento.js (con defer).
2. El script crea window.Configento, busca una sola vez todos los elementos con data-configento y registra una instancia para cada uno. Su id es el id del elemento o, si no lo tiene, configento-anon-<n>.
3. Para cada instancia empieza de inmediato la carga del componente (o se usa el componente incrustado, véase component).
4. En cuanto un componente se ha cargado, su instancia recibe los métodos de abajo. Antes, lanzan Configento instance not ready — await Configento.ready first.
5. Configento.ready se cumple cuando se han cargado todas las instancias de la página.

Los elementos que llegan a la página después del paso 2 no se reconocen. Una referencia a una instancia sigue siendo válida durante la carga: si obtiene Configento.instances.get(id) antes de ready, el mismo objeto recibe después los métodos reales.

Global: window.Configento

Propiedad / método	Tipo	Descripción
version	string	Versión del motor, p. ej. 3.1.0
frontendVersionTag	'v3'	Identificador de la generación del motor. Compruebe este valor, no version, si su código solo funciona con una generación.
ready	Promise<void>	Se cumple cuando se han cargado todas las instancias
instances	ReadonlyMap<string, ConfiguratorInstance>	Todas las instancias, con el id de la instancia como clave
first()	ConfiguratorInstance o null	La primera instancia de la página
forElement(el)	(el) => ConfiguratorInstance (o null); el es un HTMLElement o un string	La instancia de un elemento o selector CSS; también busca hacia fuera (closest('[data-configento]'))
loadAsset(id, opts?)	(id: string, opts?: { instance?: ConfiguratorInstance }) => Promise<AssetPayload>	Lee una configuración guardada; consulte Guardar y cargar
setModalAdapter(adapter?)	(adapter?: ModalAdapter) => void	Ventana propia para las vistas ampliadas de imágenes; consulte Adaptador de ventana modal
registerRenderer(name, renderer)	(name: string, renderer: CharacteristicRenderer) => () => void	Representación propia de características; consulte Representación propia. Devuelve una función para darlo de baja.
CloudError	Clase	Clase de error de storeAsset() y loadAsset(); consulte CloudError

window.addEventListener('DOMContentLoaded', async () => {
  await Configento.ready;
  const k = Configento.forElement('#product-form');
});

Instancia: ConfiguratorInstance

Propiedades (solo lectura):

Propiedad	Tipo	Descripción
id	string	id de la instancia
componentId	string o null	ID del componente
element	HTMLElement	El elemento con data-configento
config	WebshopConfig o null	Los ajustes al cargar, congelados; consulte Integración

Las características se indican por su nombre interno (string) o su ID numérico (CharacteristicRef), y los valores por el campo Valor (string) o su ID numérico (ValueRef). Un nombre desconocido, un valor desconocido o un tipo de dato inadecuado lanza un Error.

Leer

getValue(characteristic): unknown

Valor de una característica en la forma en que lo ven también las fórmulas:

Característica	Resultado	Vacío
Selección, botones de radio, lista con imágenes	Campo Valor de la entrada elegida (sin valor: su ID)	null
Selección múltiple, casilla de verificación	Lista de valores	[]
Campos de entrada	Texto, sin espacios al principio ni al final	''
Selección múltiple con cantidades	{ [ID de valor]: cantidad }	{}
Fórmula, lista de precios, combinación, atributo de producto, servicio web	Resultado del cálculo	null

Una característica que una regla oculta siempre devuelve «vacío».

k.getValue('anchura');     // → '120'
k.getValue('accesorios');  // → ['manivela', 'mando_a_distancia']

getSelections(): SelectionsMap

La selección actual de todas las características como { [ID de característica]: selección }; consulte Selección. Faltan las características que una regla oculta; los valores bloqueados se eliminan.

getState(): ConfiguratorSnapshot

{
  selections: SelectionsMap;                     // como getSelections()
  evaluated: Record<number, number | string | null>;  // resultados de todos los cálculos por ID de característica
  hiddenCharacteristics: number[];               // características ocultadas por reglas
  blacklistedValues: number[];                   // valores bloqueados por reglas
  price: PriceSnapshot;                          // como getPriceBreakdown()
  characteristicPrices: Record<string, number>;  // recargo por característica según nombre interno
}

Simple consulta: puede llamarse tantas veces como se quiera. characteristicPrices indica lo que cada característica aporta a price.total, en la moneda y la base fiscal de la tienda. Faltan las características sin parte en el precio, sin nombre interno u ocultas por una regla.

getPriceBreakdown(): PriceSnapshot

{ total: number; currency: string; priceIncludesTax: boolean }

total ya está convertido al tipo impositivo y a la moneda de la tienda (data-configento-tax-rate, data-configento-currency).

getSummary(opts?): string

Opción	Predeterminado	Efecto
format	'text'	'html' devuelve <dl><dt>Característica</dt><dd>Valor</dd>…</dl>
includePrices	false	Recargo de la característica detrás del valor, como en characteristicPrices; las características sin recargo quedan sin él
separator	'; '	Separador en formato de texto

Contiene solo las características visibles. Si el componente muestra la referencia combinada en el resumen, aparece al final.

k.getSummary({ format: 'html', includePrices: true });

getCombinedSku(): string

Referencia del producto configurado a partir de los números de artículo de los valores elegidos, unidos con -, p. ej. CL-W-GR-TXT. Por cada característica, en el orden del componente: el número de artículo del valor elegido (en una selección múltiple, el primero disponible) o, si no, el de la característica. Las partes vacías se omiten y las características ocultas no cuentan. '' si nada lleva número de artículo. Si no está vacía, figura también como _combined_sku en cada payload de pedido.

getCharacteristics(): CharacteristicInfo[]

Describe todas las características del componente en su orden, independientemente de reglas y selección. Con ella lee la clase CSS y los campos personalizados de características y valores.

type CharacteristicInfo = {
  id: number;
  key: string | null;          // nombre interno, clave en getAssetPayload()
  groupId: number;
  groupKey: string | null;
  title: string;
  type: string;                // p. ej. 'radiobuttons', 'text'
  visibility: 'visible' | 'hidden' | 'shop' | 'backend';
  cssClass: string;            // campo «Clase CSS» tal como se introdujo, '' si está vacío
  customFields: { [númeroDeCampo]: CustomField };
  values: Array<{
    id: number;
    key: string | null;        // value del valor
    label: string;
    sku: string | null;
    customFields: { [númeroDeCampo]: CustomField };
  }>;                          // todos los valores, también los bloqueados; vacío en campos de entrada
};

CustomField se describe en Entrada de la payload. Encontrar un valor por el contenido de un campo:

const color = k.getCharacteristics().find((c) => c.key === 'color');
const valor = color.values.find((v) =>
  Object.values(v.customFields).some((f) => f.id === 'checkout-titel' && f.value === 'Rojo'));

La clase del campo Clase CSS también puede servir como valor de control para su propio script. Una representación propia solo se aplica si exactamente ese nombre está registrado con registerRenderer().

getAssetPayload(): AssetPayload | null

La configuración como JSON, ordenada por nombres internos: la misma forma que finalize().payload, pero sin comprobación. null mientras no haya nada seleccionado. Siempre contiene todos los grupos, no solo el mostrado, en el orden del componente. Los campos de cada característica se describen en Entrada de la payload. Además de las características contiene _component_title, _locale, si procede _combined_sku y, en componentes con Captcha, altcha.

getHeaderValue(opts?): string | null

La misma configuración codificada en Base64 (apta para UTF-8): la forma que los plugins de tienda pasan al carrito y que Legacy tenía en el campo configurator1-header. Con opts.assets (resultado de storeCombinedImage() como { type: 'imgData', id, url, file }) se añade la lista de imágenes de la que, por ejemplo, el plugin de Magento lee la imagen del carrito.

Modificar

Método	Firma	Para
selectValue	(characteristic, value) => void; value puede ser null	Selección, botones de radio, lista con imágenes. null vacía la selección.
toggleValue	(characteristic, value) => void	Casilla de verificación, selección múltiple, lista con imágenes con selección múltiple
setText	(characteristic, text: string) => void	Campos de entrada
setQuantity	(characteristic, value, quantity: number) => void	Selección múltiple con cantidades; las cantidades negativas pasan a 0
resetSelection	(characteristic) => void	Todos los tipos de datos; después, las reglas pueden volver a preseleccionar la característica
setProductAttributes	(attributes: Record<string, string>) => void	Sustituye los valores de los atributos de producto, p. ej. tras un cambio de variante. También se puede llamar antes de ready.
showLanguageSelect	() => void	Vuelve a mostrar la selección de idioma (solo con languageSelect y varios idiomas); la selección se conserva

Cada cambio actúa como una entrada del cliente: reglas, fórmulas y precio se recalculan; después siguen change y, si el precio cambia, price.

Finalizar

finalize(): Promise<FinalizeResult>

Comprueba toda la configuración como un clic en el botón de acción y muestra los errores en la característica.

{
  ok: boolean;
  validationErrors: ValidationError[];
  payload?: AssetPayload;        // solo con ok
  priceTotal: number;
  summary: string;               // texto, 1024 caracteres como máximo
  combinedImage?: string;        // PNG como URL de datos si el componente tiene una imagen combinada
}

finalize() no envía nada y después dispara el evento finalize.

Guardar y cargar

Método	Firma	Descripción
storeAsset	() => Promise<{ id: string; url: string }>	Guarda la configuración. id es la clave del enlace profundo y url, la dirección del archivo JSON guardado.
Configento.loadAsset	(id, { instance? }) => Promise<AssetPayload>	Lee una configuración guardada. Sin instance, se usa la primera.
restoreFromAssetJson	(payload) => void	Traslada a la instancia una configuración leída
storeCombinedImage	() => Promise<{ id: string; url: string }> (o null)	Guarda la imagen de producto combinada para el carrito o el pedido; null si el componente no tiene ninguna

Si alguien abre la página de producto con ?dl=<id> (o ?configento_asset=<id>), V3 restaura por sí mismo la configuración en el primer configurador. Para otros parámetros u otro configurador, llame usted mismo a loadAsset() y restoreFromAssetJson().

const { id } = await k.storeAsset();
const enlace = new URL(location.href);
enlace.searchParams.set('dl', id);

storeAsset() y loadAsset() necesitan los ajustes de la tienda (ID de cliente, token). Por eso, en la vista previa del admin lanzan CONFIG_MISSING. El configurador no repite por sí mismo las subidas fallidas; de lo contrario se crearían entradas duplicadas.

Grupos y asistente

Método	Firma	Descripción
getGroups	() => GroupInfo[]	Grupos mostrados, en orden; faltan los ocultados por reglas
getActiveGroup	() => ActiveGroup (o null)	Grupo mostrado; null con Sin grupos o con un solo grupo
setActiveGroup	(ref, opts?: { validate?: boolean }) => Promise<boolean>; ref es number o string	Cambia por ID o nombre interno. Hacia delante comprueba cada paso del camino (validate: false lo omite) y consulta el step guard. true si ha cambiado de paso.
nextGroup	() => Promise<boolean>	Como Siguiente
prevGroup	() => Promise<boolean>	Como Atrás, sin comprobación
setStepGuard	(guard, opts?: { backward?: boolean }) => void; guard es StepGuard o null	Comprobación propia antes del cambio

type GroupRef   = { id: number; key: string | null; index: number };
type GroupInfo  = GroupRef & { title: string; characteristics: string[] };
type ActiveGroup = GroupRef & { total: number };

type StepGuard = (step: { from: GroupRef; to: GroupRef; direction: 'forward' | 'back' | 'jump' })
  => boolean | void | Array<{ characteristic: number | string; message: string }>
   | Promise<boolean | void | Array<{ characteristic: number | string; message: string }>>;

key es el nombre interno del grupo definido en el editor, e index, la posición entre los grupos mostrados. characteristics enumera los nombres internos de las características del grupo en el orden de visualización: las claves con las que aparecen en getAssetPayload(). Las características ocultas por reglas siguen en la lista; las que no tienen nombre interno faltan. Así puede estructurar su propio resumen por pasos sin mantener la asignación en su código:

const payload = k.getAssetPayload() ?? {};
for (const group of k.getGroups()) {
  const rows = group.characteristics
    .map((name) => payload[name])
    .filter((entry) => entry && entry.visibility !== 0);
  // group.title como encabezado, rows como líneas
}

El step guard se ejecuta después de la comprobación integrada, de forma predeterminada solo hacia delante. false retiene el paso sin mensaje; una lista lo retiene y muestra cada mensaje en la característica (código de error guard). Mientras haya una promesa pendiente, Siguiente y Atrás quedan bloqueados. Si el guard lanza un error, el paso cambia de todos modos.

Además, una regla de error con «Ejecutar cuando» asistente y Tipo de error Error retiene el paso al que pertenece.

Eventos

on(event, callback) devuelve una función para darse de baja. Los listeners siguen suscritos aunque la instancia se vuelva a conectar internamente (por ejemplo, cuando llegan más tarde valores de un servicio web).

Evento	Cuándo	Contenido
change	Tras cada cambio de la selección	{ selections: SelectionsMap }, como getSelections()
price	Cuando cambian el precio total, la moneda o la base impositiva; una vez justo después de cargar	{ total, currency, priceIncludesTax, delta }; delta respecto al precio anterior
finalize	Cuando finalize() ha terminado	FinalizeResult
error	Cuando aparecen errores en la característica	{ errors: ValidationError[] }
group	Tras cada cambio del grupo mostrado, no al mostrarlo por primera vez	{ from, to, direction }; to es un GroupRef, from un GroupRef o null
action	Cuando ha terminado la petición de un botón de acción, también con un estado de error o un error de red; no cuando la comprobación de las entradas detiene el clic (entonces error); con la acción Entregar a la página (event), en cambio, en cuanto se han comprobado las entradas, antes del envío	ActionEvent, véase abajo

onChange(callback) es la forma antigua de on('change', …) sin contenido y se eliminará.

ActionEvent

Campo	Significado
ok	true con un estado HTTP 2xx. Con event, siempre true
status	Estado HTTP de la respuesta, 0 sin respuesta (error de red). Con event, 0
body	Respuesta del endpoint: como objeto si es JSON, si no como texto; null con un PDF o sin respuesta. Con event, null
characteristic	Nombre interno del botón de acción
action	custom_url, pdf, email o event (acción Entregar a la página)
payload	Solo con event: la configuración para enviar, con la solución del Captcha como altcha
preventDefault()	El botón ya no muestra ni su línea de éxito ni su línea de error y no redirige. Una descarga de PDF se inicia igualmente.
defaultPrevented	true si un listener ha llamado a preventDefault()

Con event, el botón espera a la promesa que devuelve su listener: { ok: true, message } muestra éxito (con su mensaje, si lo indica), { ok: false, message } muestra su mensaje como error y una promesa rechazada, su texto de error. Si el listener no devuelve nada, cuenta como éxito. Desde la versión 3.2.0.

Desde la versión 3.1.0.

Tipos de datos

Selección

SelectionsMap es { [ID de característica]: selección }; según el tipo de dato, una selección es:

kind	Campos	Características
single	valueId (number o null), qty?: number	Selección, botones de radio, lista con imágenes
multi	valueIds: number[], qtys?: { [ID de valor]: number }	Casilla de verificación, selección múltiple
text	value: string	Campos de entrada
quantities	quantities: { [ID de valor]: number }	Selección múltiple con cantidades
files	files: Array<{ id, folder, type, … }>	Subida de archivos
captcha	payload: string	Captcha

Entrada de la payload

Cada característica aparece en getAssetPayload() y finalize().payload con su nombre interno. Estos campos están garantizados:

Campo	Tipo	Presente
label	string	Siempre. Título de la característica en el idioma del configurador.
value	véase abajo	Siempre.
valueLabel	véase abajo	Siempre. Denominación del valor o la entrada.
visibility	number	Siempre. Sigue la Visibilidad de la característica: 1 Sí (visible), 3 Solo backend, 0 No (oculto) u oculta por una regla.
valueId	number, null o number[]	En características con valores.
choiceSku	string o string[]	En características con valores. En selección simple solo si el valor elegido tiene número de artículo; en los arrays, '' representa valores sin él.
valueQty	number o number[]	Siempre en selección múltiple con cantidades; en otros casos solo si la característica tiene una cantidad configurada.
sku	string	Si la propia característica tiene número de artículo.
files	Array<{ id, folder, type, … }>	En la subida de archivos.
customFields	{ [número de campo]: CustomField }	Si la característica tiene campos personalizados.
choiceCustomFields	{ [número de campo]: CustomField }	En selección, botones de radio y Paquete, si el valor elegido tiene campos personalizados.

Según el tipo de dato:

Características	value	valueLabel	valueId
Selección, botones de radio, Paquete	string: value del valor, '' sin selección	string	number, null sin selección
Casilla de verificación, selección múltiple, lista con imágenes	string[]	string[]	number[]
Selección múltiple con cantidades	string[]	string[]	number[], más valueQty: number[] en la misma posición
Campos de entrada	string	string (igual que value)	–
Fórmula, Combinación simple, Atributo de producto, Servicio web	string: el resultado, '' sin él	string	–
Subida de archivos	string: nombres de archivo separados por comas	string[]	–

Una lista con imágenes devuelve siempre arrays, aunque solo se pueda elegir un valor. Una característica oculta por una regla conserva su clave, pero vacía: value y valueLabel son '', visibility es 0 y faltan los demás campos salvo sku y customFields.

CustomField es { value: string; title: string; id: string }: value es el texto introducido (también ''), title el nombre del campo en los ajustes del componente e id se deriva de él, sin espacios ni caracteres especiales y en minúsculas, p. ej. Checkout-Titel → checkout-titel. La clave es el número del campo. Es la misma forma que en Legacy; el plugin de Magento pasa ambos campos al pedido.

No están en la payload: las características con visibilidad Solo tienda, las que no tienen nombre interno y los campos estáticos, gráficos, botones de acción y Captchas. Los precios por característica no están en la payload: los proporciona getState().characteristicPrices.

ValidationError

{ characteristicId: number; altTitle: string; code: string; message: string }

message ya está traducido al idioma del configurador. code es uno de: required, pattern, range, length, numeric, integer, gt-zero, gte-zero, email, url, zip, phone, iban, bic, vat, code, alpha, alphanum, data, lowercase, uppercase, rule (regla de error), guard (step guard).

CloudError

storeAsset() y loadAsset() se rechazan con un Configento.CloudError: code, retryable y, en los errores HTTP, status.

code	Significado	retryable
NO_SELECTIONS	Todavía no se ha seleccionado nada	no
CONFIG_MISSING	Sin ajustes de tienda (vista previa del admin) o sin instancia	no
HTTP_4XX	Rechazado, p. ej. por el token o el dominio	no
HTTP_5XX	Error del servidor	sí
BAD_RESPONSE	Respuesta inesperada	no
NETWORK	Sin conexión, CORS, certificado	sí
NOT_FOUND	La configuración guardada no existe	no

try {
  await k.storeAsset();
} catch (err) {
  if (!(err instanceof Configento.CloudError)) throw err;
  if (err.retryable) programarNuevoIntento();
}

Integración: atributos y JSON

Cada ajuste se indica como atributo en el elemento con data-configento o como clave en el atributo JSON data-configento-config. Si están ambos, prevalece el JSON.

Atributo	Clave JSON	Valor
data-component-id	componentId	ID del componente; obligatorio
data-configento-customer	customer	ID de cliente
data-configento-token	token	Token de la tarjeta HTML5 (V3)
data-configento-token-endpoint	tokenEndpoint	Dirección que emite tokens de corta duración (plugins de tienda). Si falta el ID del componente (?id=) en la dirección, el configurador lo añade él mismo.
data-configento-cloud-base-url	cloudBaseUrl	cloud.configento.app
data-configento-asset-base-url	assetBaseUrl	Host de las configuraciones guardadas (plugins de tienda)
data-configento-tax-rate	taxRate	Tipo impositivo de la tienda en porcentaje
data-configento-currency	currency	Código de moneda, p. ej. EUR
data-configento-currency-rates	currencyRates	Tipos de cambio como JSON, p. ej. {"CHF": 0.94}
data-configento-locale	uiLocale	Idioma, p. ej. de_DE
data-configento-content-locale	contentLocale	Idioma distinto solo para los textos del componente
data-configento-embed-mode	embedMode	storefront (predeterminado con atributos) o admin-preview
data-configento-price-mount	priceMount	Selector CSS para el precio total
data-configento-summary-mount	summaryMount	Selector CSS para el resumen
data-configento-summary-open	summaryOpen	Resumen desplegado o plegado al principio
data-configento-combined-image-mount	combinedImageMount	Selector CSS para la imagen de producto combinada
data-configento-language-select	languageSelect	Selección de idioma antes del configurador
data-configento-language-select-title	languageSelectTitle	Texto sobre la selección de idioma
data-configento-languages	languages	Idiomas ofrecidos, separados por comas (JSON: lista)
data-configento-min-height	minHeight	Altura reservada durante la carga, p. ej. 640px
data-configento-min-height-keep	minHeightKeep	Mantener la altura también después de la carga
data-configento-wizard-nav	wizardNav	full, buttons o none
data-configento-component-json	component	El propio componente, tal como lo devuelve GET /api/v3/components/{id}
–	productAttributes	Valores de los atributos de producto, p. ej. {"anchura": "120"}

Los atributos de sí/no aceptan true/false, 1/0, yes/no o el atributo sin valor para «sí». Los valores desconocidos dejan el valor predeterminado y generan una advertencia en la consola.

Visualización al integrar mediante atributos: en el modo storefront, el configurador no muestra ni el precio total ni el resumen, porque la tienda tiene los suyos. Con price-mount y summary-mount los coloca donde quiera. Si un selector no encuentra ningún elemento, esa parte no aparece en ningún sitio, en lugar de duplicarse en el configurador. summary-open solo funciona junto con summary-mount; allí el resumen empieza desplegado de forma predeterminada.

Solicitar el token antes: con tokenEndpoint, el configurador solo pide su token una vez cargado. Es más rápido si la página inicia esta solicitud ya en el <head> y guarda la promesa en window.ConfigentoTokenPrefetch, con exactamente la URL de tokenEndpoint como clave. El configurador toma este resultado una vez. Si la promesa devuelve null, un error o ningún token, lo pide él mismo. Así, en la página solo figura la URL, nunca un token, lo que es compatible con las cachés de página. El plugin de Magento lo hace por sí solo a partir de la versión 5.0.0-beta22.

<script>
  (window.ConfigentoTokenPrefetch ||= {})['https://shop.example/configento/v3/token/id/42/'] =
    fetch('https://shop.example/configento/v3/token/id/42/', { method: 'POST', credentials: 'omit' })
      .then((r) => (r.ok ? r.json() : null))
      .catch(() => null);
</script>

Adaptador de ventana modal

interface ModalAdapter {
  openOverlay(args: { title: string; container: HTMLElement; onClose: () => void }): { close(): void };
}

El configurador rellena container después de que openOverlay retorne. Su adaptador lo inserta en una ventana propia y llama a onClose() cuando el cliente la cierra. El configurador llama a close() cuando cierra la ventana por sí mismo (p. ej. tras la selección). Establezca el adaptador en cuanto exista window.Configento y antes de que se abra una ventana; setModalAdapter() sin argumento restablece la ventana integrada.

Script de compatibilidad

https://cloud.configento.app/configento-v3/configento-compat.js, cargado antes de configento.js, traslada los objetos globales del motor Legacy (Justselling_Configento_App_*, CONFIGENTO_PRODUCT.setPrice, los eventos configentoUpdate…InDom…) a esta interfaz. Qué asume en detalle y cómo reescribir el código antiguo se explica en la guía, en Migrar desde Legacy.

Representación propia

Con Configento.registerRenderer(name, renderer), su código dibuja una característica por sí mismo. Si name figura en el campo Clase CSS de una característica, el configurador muestra en lugar del elemento de entrada un contenedor vacío (div.cfg-custom con data-configento-renderer="<name>"). El configurador nunca toca su contenido. Su código establece los valores mediante ctx: reglas, precio, comprobación, asistente, resumen y pedido funcionan como con una entrada del cliente.

interface CharacteristicRenderer {
  replace?: 'body' | 'all';     // por defecto 'body'
  combine?: boolean;            // por defecto false
  mount(el: HTMLElement, ctx: RendererContext): void;
  update?(ctx: RendererContext, el: HTMLElement): void;
  destroy?(el: HTMLElement): void;
}

Elemento	Significado
name	Nombre de clase con minúsculas, dígitos y -. Basta con una de varias clases en el campo Clase CSS. Un segundo registerRenderer con el mismo nombre sustituye al primero.
replace: 'body'	El configurador sigue mostrando el título, el asterisco de obligatorio, el texto informativo y los mensajes de error; el contenedor se sitúa en .cfg-char__body.
replace: 'all'	El contenedor es el único hijo de .cfg-char. El título y los errores los muestra usted mismo a partir de ctx.
combine: true	Todas las características visibles del mismo grupo con esta clase se convierten en un solo widget, en la posición de la primera. Las demás no muestran nada, pero siguen contando en reglas, comprobación, precio y pedido. Sus errores aparecen agrupados en el widget.
mount	Una vez, en cuanto el contenedor está en el DOM
update	Cuando cambia algo en ctx: selección, errores, valores permitidos, precios, idioma. No con cambios en otras características.
destroy	Antes de que desaparezca el contenedor: cambio de paso en el asistente, una regla lo oculta, baja del renderer. Después, los métodos de este ctx ya no tienen efecto. Si la característica vuelve, sigue un nuevo mount.

ctx:

Propiedad / método	Contenido
characteristic	La característica; con combine, la primera
characteristics	Todas las características del widget; si no, solo characteristic
locale	Idioma del configurador, p. ej. es_ES
instance	La instancia, véase más arriba. Sus métodos solo funcionan después de Configento.ready.
selectValue(valor, caracteristica?), toggleValue(valor, caracteristica?), setText(texto, caracteristica?), setQuantity(valor, cantidad, caracteristica?), reset(caracteristica?)	Como los métodos homónimos de la instancia. Sin caracteristica se aplica characteristic; si no, solo una característica de characteristics.

Cada característica de ctx tiene: id, key (nombre interno), type, title, info (HTML), required, selection (como getValue()), errors (ValidationError[]), values y, en los campos de entrada, textConstraints (minLength, maxLength, validator). values contiene solo los valores permitidos; faltan los bloqueados por reglas. Cada valor tiene id, key (campo Valor), label, info, image, price (recargo en la moneda y la base impositiva de la tienda), priceLabel (con el formato del configurador; vacío si no se muestra ninguno) y selected.

Registrar antes del bundle: si su script se ejecuta antes de configento.js, deposite el renderer en (window.ConfigentoRenderers ||= {})[name] = renderer. Los renderers registrados más tarde también funcionan: las características ya mostradas cambian de inmediato.

Alternativa: si no hay ningún renderer registrado (por ejemplo, en la vista previa del admin), la característica muestra la representación integrada. Si mount o update lanza un error, el configurador lo escribe en la consola y vuelve a mostrar el elemento de entrada integrado para esa característica. Solo se aplica a V3.

Diseño con CSS

Los colores, la fuente y las esquinas se adaptan mediante variables como --configento-color-accent, y los elementos individuales mediante clases garantizadas como .cfg-toggle-item__label. Ambas cosas se describen en la página Personalizar el diseño (CSS).

Versiones y compromisos

Configento.version sigue el Semantic Versioning. Las correcciones de errores cambian la última cifra, las nuevas funciones la del medio, y solo una nueva primera cifra rompe el código existente, con instrucciones de migración.

Confíe en los métodos, eventos y tipos de datos de esta página (incluidos los campos de Entrada de la payload) y en las variables y clases de Personalizar el diseño (CSS), no en otras clases ni en el resto de la estructura DOM del configurador. También son estables los atributos data-configento-group-id y data-configento-group-key.

Próximos pasos

• Interfaz JavaScript (V3): guía con ejemplos
• Integración fragmento HTML
• Subidas y enlaces profundos
• Motor de frontend: Legacy o V3