내 웹 앱에 문서 편집기 임베드하기

기본 로컬 편집의 경우: 편집기는 OnlyOffice 의 WebAssembly 엔진으로 브라우저 안에서만 동작하므로 문서는 클라이언트에서 렌더링되고 편집됩니다 — 문서 서버를 세울 필요가 없습니다. 권장 구성은 경계를 깔끔하게 유지합니다: 부모 앱이 인증·가져오기·저장을 담당하고, iframe 은 편집만 담당합니다. 토큰, 쿠키, 업무 API 는 내 앱 안에 남습니다.

iframe 하나로 추가하기

<iframe
  id="documentEditor"
  src="https://edit.chaxus.com/editor?embed=1&embedOrigin=https://your-app.example.com"
  style="width: 100%; height: 720px; border: 0"
></iframe>

그다음에는 postMessage로 통신합니다. 각 명령은 응답과 짝지을 id를 가지며, 편집기의 모든 이벤트는 document:* 메시지입니다:

// 내 앱이 이미 가져온 파일 열기 (인증은 내 앱에 남습니다)
iframe.contentWindow.postMessage(
  { id, type: 'document:open-buffer', payload: { fileName: 'report.xlsx', buffer } },
  'https://edit.chaxus.com',
);

// 편집된 파일을 돌려받고 직접 업로드
iframe.contentWindow.postMessage({ id, type: 'document:save', payload: { targetExt: 'XLSX' } }, editorOrigin);
// → 편집기가 다음으로 응답합니다 { type: 'document:saved', payload: { fileName, file } }

무엇을 얻나요

• iframe 하나와 작은 postMessage 명령/응답 API — 설치할 SDK 가 없습니다
• 내 앱이 자체 자격 증명으로 가져온 URL·File·ArrayBuffer에서 열기
• XLSX·DOCX·PPTX·CSV로 저장하고 File로 돌려받아 내 앱이 업로드
• 읽기 전용 모드, 메시지 단위 오리진 제한 (embedOrigin), 상태 조회
• 기본 로컬 편집의 경우: 운영할 문서 서버 없음 — 편집은 100% 클라이언트의 WebAssembly
• 오픈 소스 (AGPL-3.0) 이며 자체 호스팅 가능 — 내 도메인 아래에 임베드

동작 방식

1. 레이아웃에 맞춘 크기로 /editor?embed=1을 가리키는 iframe 을 추가합니다.
2. document:ready 이벤트를 기다린 뒤 document:open-url, open-file, open-buffer를 보냅니다.
3. 사용자가 그 자리에서 편집합니다. 내 앱이 어딘가로 보내지 않는 한 파일은 브라우저를 벗어나지 않습니다.
4. document:save를 보내면 편집기가 document:saved로 편집된 파일을 돌려주고, 내 앱이 자체 인증으로 업로드합니다.

읽기 전용과 미리보기 모드

뷰어, 검토 단계, 잠긴 레코드처럼 읽기 전용으로 열려면 open 명령에 readonly: true를 전달하고, 언제든 document:set-readonly로 전환하세요 — 다시 불러오지 않으며 사용자가 보던 위치도 유지됩니다. 읽기 전용 동안에는 편집이 비활성화되지만, document:save는 document:saved로 현재 바이트를 반환합니다 (내보내기는 가능하고 잠기는 것은 편집뿐입니다). document:get-state는 현재 readonly 값을 알려 줍니다.

// 잠긴 상태로 열고 나중에 해제
send('document:open-url', { url, readonly: true });
send('document:set-readonly', { readonly: false });

자주 묻는 질문