문서 간 임베드

다른 Office 제품 안에 편집 가능한 콘텐츠를 원래 편집기와 함께 넣습니다.

임베드 블록은 한 Univer 제품 안에 다른 제품을 배치합니다. 프로젝트 문서에서 예산과 작업을 관리하고, 슬라이드에서 계산 가능한 표를 검토하거나, 캔버스에 계획과 설명을 함께 놓을 수 있습니다. 하위 콘텐츠는 자체 데이터 모델과 기본 편집기를 유지하며 활성화하면 포커스와 메뉴가 전환됩니다.

원리: 호스트와 하위 Unit

호스트 Unit은 위치, 크기, 하위 Unit 참조와 기본 보기를 저장합니다. 하위 Unit은 실제 셀, 문단 또는 레코드를 저장합니다. Embed는 참조를 확인해 하위 Unit을 불러오고 호스트에 편집기를 배치합니다. Unit은 통합 문서, 문서, 프레젠테이션, 관계형 테이블 또는 캔버스 같은 콘텐츠 단위입니다.

100%

임베드 관계와 실제 콘텐츠는 별도로 저장합니다. 삽입된 표의 셀을 편집하면 하위 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와 수식 기반 지표를 배치합니다. PowerPoint에 Excel을 삽입하는 방식처럼 결론에서 편집 가능한 모델로 돌아갈 수 있습니다. 화면의 예산은 $62,100으로 업데이트되었습니다.

Relational Table: 데이터베이스 안의 설명 문서

테이블 목록에 Launch brief Doc을 추가해 작업 테이블과 설명을 전환합니다. CRM, 프로젝트 관리, 운영 데이터베이스에 적합합니다. 목록 항목을 추가하는 기능이며 레코드마다 문서를 자동 생성하지 않습니다.

Canvases: 함께 논의하는 데이터 캔버스

예산 Sheet와 제안 Doc을 나란히 두고 아래에 수식 기반 지출 합계를 표시합니다. 프로젝트 룸, 검토 및 리서치 캔버스에서 원본 데이터와 맥락을 유지하며 논의할 수 있습니다.

임베드는 표시와 편집을, 수식 참조는 계산을 담당합니다. 블록 삽입만으로 합계 수식이 만들어지지는 않습니다. Unit 간 참조를 구성하면 Sheet 셀과 Doc·Slide·Canvases의 수식 Shape에서 Sheet 범위 또는 Relational Table 필드를 읽을 수 있습니다. Relational Table 수식 필드도 Sheet를 참조할 수 있습니다. 원본 데이터와 변경 알림을 사용할 수 있으면 관련 변경이 재계산을 트리거합니다.

100%

시나리오 및 수식	검증 결과
Slide 예산 합계: `=SUM('[Leadership Budget]Budget'!C5:C8)`	`C7`을 17,100에서 18,000으로 변경하면 61,200 → 62,100으로 업데이트됩니다.
Sheet에서 Relational Table 비용 합계: `=SUM([Control Tasks]!Launch_tasks[Cost])`	Cost 하나를 4,000에서 4,500으로 변경하면 18,000 → 18,500으로 업데이트됩니다.

수식 이름과 함께 대응하는 안정적인 Unit ID를 저장해야 합니다. getFormula().buildReference()로 참조와 호스트의 외부 참조 매핑을 생성합니다. Relational Table 테이블은 표시 이름이나 ID를 직접 조합하지 말고 table.getFormulaName()을 사용합니다. 수식 Shape는 shape.setFormula({ formula, externalReferences })로 설정하고 계산 완료 후 결과를 읽습니다. Formula Facade, Shape Facade, Relational Table 수식을 참고하세요.

생성 및 통합

같은 Univer 인스턴스에 호스트와 하위 제품 및 UI를 등록한 뒤 Embed와 Embed UI를 등록합니다. 다음은 기존 Sheet를 Doc 본문에 넣는 예입니다. hostDocument와 budgetWorkbook은 해당 Facade입니다.

TypeScript

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을 사용합니다.

기능 목록으로 돌아가기

이 가이드는 어떠셨나요?