Bloques incrustados
Inserta contenido editable en otro producto Office conservando su editor nativo.
Los bloques incrustados sitúan un producto Univer dentro de otro: presupuestos y tareas en un documento de proyecto, hojas calculables en una diapositiva o planes y notas en un lienzo. El contenido hijo conserva su modelo de datos y editor nativo; al activarlo, cambian el foco y los menús.
Principio: Unit anfitriona y Unit hija
La Unit anfitriona guarda posición, tamaño, referencia a la hija y vista inicial. La Unit hija guarda las celdas, párrafos o registros reales. Embed resuelve la referencia, carga la Unit hija y coloca su editor en el anfitrión. Una Unit puede ser un libro, documento, presentación, tabla relacional o lienzo.
La relación y el contenido se guardan por separado. Editar una celda incrustada actualiza la Sheet hija; mover o redimensionar el bloque actualiza su anclaje en el anfitrión.
Ubicaciones compatibles
| Producto anfitrión | Ubicación | Uso habitual |
|---|---|---|
| Sheet | Objeto flotante o pestaña del libro | Añadir un informe junto al modelo de cálculo o abrir una base de tareas. |
| Doc | Bloque del cuerpo | Reunir texto, presupuestos y tareas en una página de proyecto. |
| Slide | Objeto flotante o página independiente | Revisar datos fuente editables junto a las conclusiones. |
| Relational Table | Entrada de la lista de tablas | Acceder a la documentación desde la base de negocio. |
| Canvases | Objeto flotante en el lienzo | Reunir datos, propuestas y debate en un lienzo. |
Cinco ejemplos de anfitrión
Estos ejemplos en inglés se crearon con la API Facade y se capturaron en el navegador. Cada caso utiliza Units hijas independientes. Todo el contenido y las cifras son datos de muestra.
Sheet: cálculos y un informe de decisión
El panel resume el gasto a la izquierda e incrusta un Doc completo a la derecha. La pestaña Launch tracker abre una Relational Table. Sirve para presupuestos comerciales, análisis operativo y modelos financieros con supuestos y explicaciones. La interacción recuerda a insertar un documento en Excel.
Doc: una página de proyecto con presupuesto y tareas
El cuerpo combina una Sheet de presupuesto y una Relational Table, para revisar el modelo y gestionar tareas en contexto. Se asemeja a las bases de datos en línea de Notion; aquí se conservan el motor de fórmulas de Sheet y los campos y vistas de Relational Table.
Slide: datos fuente durante la revisión
Una Sheet de presupuesto y una Relational Table de tareas comparten diapositiva con una métrica calculada. Es comparable a incrustar Excel en PowerPoint: permite volver de la conclusión al modelo editable. El presupuesto mostrado se ha actualizado a $62,100.
Relational Table: documentación dentro de la base
Launch brief aparece como Doc junto a la tabla de tareas. Permite alternar entre registros y explicación en un CRM, seguimiento de proyectos o base operativa. Es una entrada de la lista; no crea automáticamente un documento por registro.
Canvases: un espacio de planificación compartido
El lienzo reúne una Sheet de presupuesto, un Doc de propuesta y un total calculado. Es útil en salas de proyecto, revisiones e investigación para mantener los datos fuente y su contexto durante el debate.
Cómo se conectan las fórmulas
La incrustación aporta visualización y edición; las referencias aportan cálculo. Insertar un bloque no crea una fórmula de resumen. Con referencias entre Units, las celdas de Sheet y las Shapes con fórmula de Doc, Slide y Canvases pueden leer rangos de Sheet o campos de Relational Table. Los campos de fórmula de Relational Table también pueden referenciar Sheet. Si los datos fuente y las notificaciones están disponibles, los cambios pertinentes disparan el recálculo.
| Escenario y fórmula | Resultado verificado |
|---|---|
Presupuesto en Slide: =SUM('[Leadership Budget]Budget'!C5:C8) | Cambiar C7 de 17,100 a 18,000 actualiza el total de 61,200 → 62,100. |
Total de Relational Table en Sheet: =SUM([Control Tasks]!Launch_tasks[Cost]) | Cambiar un Cost de 4,000 a 4,500 actualiza el total de 18,000 → 18,500. |
Además del nombre legible, persista el ID estable de la Unit. Use getFormula().buildReference() para generar la referencia y su asociación externa en el anfitrión. Para una tabla Relational Table, use table.getFormulaName() en vez de concatenar su nombre visible o ID. Las Shapes calculadas usan shape.setFormula({ formula, externalReferences }); lea los resultados tras completar el cálculo. Consulte Formula Facade, Shape Facade y fórmulas de Relational Table.
Creación e integración
Registre los productos anfitrión e hijo y sus interfaces en la misma instancia Univer; añada Embed y Embed UI. El ejemplo inserta una Sheet existente en un Doc; hostDocument y budgetWorkbook son sus Facades.
import '@univerjs-pro/embed/facade'const block = univerAPI.createEmbed({ host: { unitId: hostDocument.getId(), surface: univerAPI.Enum.FEmbedHostSurface.DocBlock, }, content: { unitType: univerAPI.Enum.UniverInstanceType.UNIVER_SHEET, ref: `#unit=${encodeURIComponent(budgetWorkbook.getId())}&type=sheet`, },})const embeddedWorkbook = await block.loadAsync()createEmbed() crea la relación y el anclaje; loadAsync() carga la Unit hija y devuelve su Facade. Use displayTarget para elegir la hoja, página de Slide o vista de Relational Table inicial. Consulte la guía de incrustación para plugins, estilos, idiomas y cargadores, y Embed Facade para otras ubicaciones y métodos.
Persistencia, colaboración y alcance
- Guardar por separado: el Snapshot anfitrión conserva referencias, posición y ajustes de visualización; no empaqueta automáticamente el contenido hijo actualizado. Eliminar el bloque no elimina el documento hijo.
- Carga colaborativa: Server SDK proporciona los snapshots y servicios de colaboración de la hija. Con
@univerjs-pro/collaboration-embed, el navegador la carga y se une a su sesión. Ambas Units conservan sus propios cambios y versiones. - Acceso y permisos: la aplicación resuelve referencias, carga datos y autoriza el acceso. Poder acceder al anfitrión no concede automáticamente edición sobre la hija.
- Alcance actual: admite tipos distintos de Sheet, Doc, Slide, Relational Table y Canvases. No incluye PDF, incrustación del mismo tipo ni anidación adicional. En un entorno Univer, cada Unit hija solo puede pertenecer a una incrustación activa.
Use enlace bidireccional para controlar entradas, métricas y gráficos propios de su aplicación desde una hoja. Use Embed Block cuando necesite conservar el editor del producto hijo.
¿Cómo es esta guía?