Встраивание документов
Встраивайте редактируемое содержимое в другой продукт Office, сохраняя его редактор.
Встраиваемые блоки размещают один продукт Univer внутри другого: бюджет и задачи в документе проекта, вычисляемую таблицу на слайде или планы и заметки на холсте. Дочернее содержимое сохраняет свою модель данных и собственный редактор; при активации переключаются фокус и меню.
Принцип: родительская и дочерняя Unit
Родительская Unit хранит положение, размер, ссылку на дочернюю Unit и начальное представление. Дочерняя Unit хранит сами ячейки, абзацы или записи. Embed разрешает ссылку, загружает дочернюю Unit и размещает её редактор внутри родителя. Unit — единица содержимого: книга, документ, презентация, реляционная таблица или холст.
Связь и содержимое сохраняются отдельно. Редактирование встроенной ячейки обновляет дочернюю Sheet; перемещение или изменение размера блока обновляет его привязку в родителе.
Поддерживаемые места вставки
| Родительский продукт | Место вставки | Типичное применение |
|---|---|---|
| Sheet | Плавающий объект или вкладка книги | Пояснение рядом с расчётной моделью или переход к базе задач. |
| Doc | Блок в основном тексте | Текст, бюджет и задачи на странице проекта. |
| Slide | Плавающий объект или отдельная страница | Редактируемые исходные данные рядом с выводами. |
| Relational Table | Элемент списка таблиц | Документация проекта внутри бизнес-базы. |
| Canvases | Плавающий объект на холсте | Данные, предложения и обсуждение на одном холсте. |
Пять примеров родительских продуктов
Эти примеры на английском созданы через Facade API и сняты в браузере. Для каждого случая используются отдельные дочерние Unit. Всё содержимое и числовые значения демонстрационные.
Sheet: расчёты и пояснительный документ
Слева показаны суммарные расходы, справа встроен полноценный Doc. Вкладка Launch tracker открывает Relational Table. Это подходит для ценовых, операционных и финансовых моделей с допущениями и пояснениями. Знакомый аналог — вставка документа в Excel.
Doc: страница проекта с бюджетом и задачами
В тексте последовательно расположены бюджетная Sheet и Relational Table, чтобы изучать модель и вести задачи в контексте проекта. Подход напоминает встроенные базы Notion; здесь бюджет сохраняет движок формул Sheet, а задачи — поля и представления Relational Table.
Slide: исходные данные на странице обзора
Бюджетная Sheet, Relational Table с задачами и вычисляемый показатель размещены на одном слайде. Как при встраивании Excel в PowerPoint, от вывода можно вернуться к редактируемой модели. На снимке бюджет обновлён до $62,100.
Relational Table: описание внутри базы
Doc Launch brief добавлен в список рядом с таблицей задач. Это позволяет переключаться между записями и пояснениями в CRM, базе проектов или операционной базе. Это пункт списка; документ для каждой записи автоматически не создаётся.
Canvases: общий холст планирования
Рядом расположены бюджетная Sheet, Doc с предложением и вычисляемая сумма расходов. Такой холст подходит для проектных комнат, обзоров и исследований, где нужны исходные данные и контекст обсуждения.
Как связаны формулы
Встраивание отвечает за отображение и редактирование, ссылки — за вычисления. Вставка блока сама по себе не создаёт итоговую формулу. При настроенных ссылках между Unit ячейки Sheet и фигуры с формулами в Doc, Slide и Canvases могут читать диапазоны Sheet и поля Relational Table. Поля-формулы Relational Table также могут ссылаться на Sheet. Когда доступны данные источника и уведомления об изменениях, соответствующие правки запускают пересчёт.
| Сценарий и формула | Проверенный результат |
|---|---|
Итог бюджета в Slide: =SUM('[Leadership Budget]Budget'!C5:C8) | Изменение C7 с 17,100 на 18,000 обновляет итог: 61,200 → 62,100. |
Сумма Relational Table в Sheet: =SUM([Control Tasks]!Launch_tasks[Cost]) | Изменение одного Cost с 4,000 на 4,500 обновляет итог: 18,000 → 18,500. |
Помимо читаемого имени необходимо сохранять стабильный ID Unit. Используйте getFormula().buildReference() для формирования ссылки и внешнего сопоставления в родителе. Для таблицы Relational Table используйте table.getFormulaName(), а не склеивайте отображаемое имя или ID. Фигуры с формулами используют shape.setFormula({ formula, externalReferences }); результат следует читать после вычисления. См. Formula Facade, Shape Facade и формулы Relational Table.
Создание и интеграция
Зарегистрируйте родительский и дочерний продукты и их интерфейсы в одном экземпляре Univer, затем Embed и Embed UI. Пример вставляет существующую Sheet в текст Doc; hostDocument и budgetWorkbook — соответствующие Facade.
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() создаёт связь и привязку в родителе, а loadAsync() загружает дочернюю Unit и возвращает её Facade. displayTarget выбирает начальный лист, страницу Slide или представление Relational Table. Настройка плагинов, стилей, языков и загрузчиков описана в руководстве, остальные позиции и методы — в Embed Facade.
Сохранение, совместная работа и ограничения
- Сохранение по отдельности: Snapshot родителя хранит ссылки, положение и настройки отображения, но не упаковывает автоматически актуальное дочернее содержимое. Удаление блока не удаляет дочерний документ.
- Совместная загрузка: Server SDK предоставляет дочерние снимки и сервисы совместной работы. С
@univerjs-pro/collaboration-embedбраузер загружает дочернюю Unit и подключается к её сеансу. Родитель и ребёнок сохраняют свои изменения и версии. - Доступ и права: приложение разрешает ссылки, загружает данные и проверяет доступ. Доступ к родителю автоматически не предоставляет права редактировать дочернее содержимое.
- Текущий охват: поддерживаются разные типы Sheet, Doc, Slide, Relational Table и Canvases. PDF, встраивание того же типа и дальнейшая вложенность исключены. В одной среде Univer дочерняя Unit может принадлежать только одному активному встраиванию.
Для управления собственными полями ввода, показателями и графиками приложения из таблицы используйте двустороннюю привязку. Если нужен редактор дочернего продукта, используйте Embed Block.
Насколько полезно это руководство?