Incrustar un widget en una página existente

Pon un widget Beyond en una página que no fue construida con Beyond, desde otro origen, con los mismos estilos de dependencias y compartidos que tiene en su propia aplicación: el import map, el registro, dos instancias y qué pasa al quitarlo e insertarlo de nuevo.

  • Disponibilidad: Experimental
  • Evidencia: Ejecución registrada
  • Guía práctica

Conserva la página que tienes

La página anfitriona conserva su marcado, sus estilos y el framework que use. El widget aporta un elemento personalizado, su controlador, sus dependencias, su estado y sus estilos, dentro del shadow root del elemento. Nada de la página tiene que convertirse en un proyecto Beyond, y no existe un modo especial de incrustación: el widget se comporta como en su propia aplicación.

Obtén el import map del origen que entrega el widget

Un widget es un módulo público con una identidad versionada. El origen que lo entrega publica, para ese módulo, el import map del módulo y de todo lo que necesita: sus dependencias, el runtime de Widgets, el adaptador, el framework y el runtime de desarrollo. En desarrollo es el entry.json de la vista previa:

Shellimportmap.sh
# The import map of the widget and its dependencies, as the development service publishes it for the
# widget module. Every address is relative to <endpoint>/preview/; a page on another origin makes them absolute.
curl -s "<endpoint>/preview/entry.json?entry=@testbed/widget-app/hello"

La respuesta lista cada módulo con su source (environment para lo que sirve el servicio), su versión y su dirección relativa a <endpoint>/preview/. Para una página en otro origen, haz absoluta cada dirección contra esa base; la aceptación hace exactamente eso.

Escribe la página anfitriona

HTMLindex.html
<!doctype html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<link rel="icon" href="data:,">
	<title>An existing page that embeds a Beyond widget</title>
	<style>
		/* The styles of the host page: they must not reach the widget, and the widget's must not reach here */
		body { font-family: Georgia, serif; }
		h1 { color: rgb(200, 30, 30); }
		.host-title { margin-bottom: 16px; }
	</style>
	<!--
		The import map of the widget and its dependencies. It is what the delivery source publishes for the
		widget module: in development, GET /preview/entry.json?entry=@testbed/widget-app/hello of the service.
		Every address below is absolute, because this page is on another origin than the service.
	-->
	<script type="importmap" id="beyond-importmap">
	{ "imports": {} }
	</script>
</head>
<body>
	<h1 class="host-title">This page was not built with Beyond</h1>
	<p>The widget below is the same one the application shows. Two instances keep their own state.</p>
	<hello-widget subject="Host page"></hello-widget>
	<hello-widget subject="Second instance"></hello-widget>
	<script type="module">
		// Importing the module registers the element; the instances above mount when their module arrives.
		// The development coordinator is optional: with it, edits reach the page without a reload.
		const importmap = JSON.parse(document.getElementById('beyond-importmap').textContent);
		if (importmap.imports['@beyond-js/local-2026/main'] && importmap.service) {
			const { local } = await import('@beyond-js/local-2026/main');
			await local.register({ origin: importmap.service, options: importmap.options, session: importmap.session });
		}
		await import('@testbed/widget-app/hello');
	</script>
</body>
</html>

En el script de módulo pasan tres cosas: se lee el import map, se registra el runtime de desarrollo para que las ediciones lleguen a la página (opcional, y ausente en producción), y se importa el módulo del widget, que registra <hello-widget>. Las instancias que ya están en el marcado se montan cuando llega su módulo.

Qué obtienes

  • Dos instancias se renderizan con los mismos estilos que en la aplicación: la hoja del widget (encabezado azul text-brand, no la regla roja h1 de la anfitriona), la hoja transitiva de la insignia y la hoja global compartida del paquete, todas cargadas desde el origen del widget, no desde la página anfitriona. BeyondWidget.host es el prefijo de identidad del paquete tal como se cargó su módulo, así que una hoja compartida se direcciona desde el origen que sirve el código.
  • La página anfitriona conserva sus propios estilos: ninguna regla del widget llega al documento.
  • Cada instancia mantiene su propio estado: hacer clic en un contador deja el otro en cero.
  • Quitar un elemento e insertarlo de nuevo monta el mismo controlador en la misma raíz, sin enlaces a hojas duplicados y sin errores.

Producción

La misma página funciona contra un origen de producción con las opciones de producción de los módulos: minificados, sin runtime de desarrollo y sin el registro en el script de módulo. Beyond CDN es la fuente de entrega para eso: la base de un release responde el import map del release en <base>/importmap.json?target=browser&format=esm, con direcciones relativas a esa URL, así que una página anfitriona en otro origen las vuelve absolutas respecto de la base antes de incluirlas en línea. El CDN no está alojado, así que esta página registra solo el origen de desarrollo; consulta Estrategias por entorno.

Siguiente

Renderiza el widget en un servidor antes de que la página lo cargue: Crear un entorno de ejecución modular.