아키텍처 및 수명 주기

Editor SDK는 브라우저에서 Office 편집기로 요청을 보내고 결과를 받는 연결 계층입니다. 문서는 Office open URL로 먼저 엽니다. SDK의 save()는 Office에 저장을 요청하며, 실제 파일 작성과 저장소 인증은 Office와 스토리지 어댑터가 담당합니다. 저장 결과를 확인할 때는 원본 파일을 다시 열어 변경 내용을 확인합니다.

요청 흐름

각 요청은 고유한 메시지 ID를 받습니다. SDK는 일치하는 결과가 도착하거나 제한 시간이 만료될 때까지 대기 중인 Promise를 보관합니다. 응답은 구성된 편집기 origin에서 와야 하며 Thinkfree envelope 형식을 따라야 합니다.

진입점

진입점	반환	사용 시점
Office.word(iframe, options?), Office.cell(…), Office.show(…)	WordApp / CellApp / ShowApp (OfficeApp<M>)	권장 - iframe 요소가 있을 때
createOffice(options)	Office<M>	옵션을 직접 제어하거나 targetWindow가 필요할 때

Office.*는 createOffice 위의 get-or-create facade입니다. 같은 iframe은 disconnect() 전까지 같은 핸들을 돌려주고, origin은 iframe.src에서 유도되며, 핸들은 getDocument(), getTools(), execute()에 whenReady()를 더해 제공합니다.

Office.* 옵션 (OfficeAppOptions)

옵션	필수	설명
frameworkOrigin	아니요	편집기 origin. 생략 시 iframe.src에서 유도. data:/blob: 또는 src가 없으면 필수
timeoutMs	아니요	요청당 제한 시간. 기본 5,000ms

createOffice() 옵션 (OfficeOptions)

옵션	필수	설명
module	예	word, cell, show 중 하나
frameworkOrigin	예	정확한 편집기 origin. *는 거부됨
iframeEl	둘 중 하나	contentWindow가 명령을 받는 iframe
targetWindow	둘 중 하나	iframe이 아닌 구성의 명시적 대상 창
timeoutMs	아니요	요청당 제한 시간. 기본 5,000ms

핸들 멤버

module, execute(method, params?), getDocument(), getTools(options?), registerTools(modelContext, options?), getToolSchemas(), getSystemPrompt(), disconnect(), 그리고 앱 핸들에만 있는 whenReady(limitMs?).

문서 핸들

getDocument()는 직렬화된 문서가 아니라 Proxy 핸들을 반환합니다. 핸들은 식별 정보 또는 네비게이션 정보를 보관하고, 메서드가 실행될 때 현재 Office 객체를 해석합니다.

• Word(word)와 Presentation(show)은 식별 기반 Proxy 핸들을 사용합니다. 모든 메서드가 1왕복입니다.
• Spreadsheet(cell)의 getTable().getRange() 같은 네비게이션은 로컬에서 경로를 쌓고, 종단 호출이 해석합니다. getWorksheet()는 여기에 속하지 않고 호출 시점에 시트를 확정합니다.
• 핸들 인자는 다른 메서드에 전달될 때 Proxy descriptor로 직렬화됩니다.
• 반환된 Proxy descriptor는 다시 핸들로 변환됩니다.

핸들을 애플리케이션 스토리지에 직렬화하거나 영구 ID로 취급하지 마십시오.

수명 주기 규칙

1. iframe에 Office open URL을 로드합니다.
2. 그 iframe과 모듈에 대해 앱 핸들 하나를 얻습니다(Office.word(iframe)).
3. 편집기가 SDK 명령에 응답할 수 있을 때까지 기다립니다(await app.whenReady()).
4. 문서 작업을 실행합니다.
5. 필요하면 Office를 통해 저장합니다(Word와 Presentation 문서의 save()).
6. iframe을 버리거나 src를 다른 문서/모듈로 바꾸기 전에 disconnect()를 호출합니다.

disconnect() 이후 핸들 메서드를 호출하면 코드 1003(DESTROYED)으로 실패합니다. 대기 중인 요청이 있는 상태에서 연결을 해제하면 그 요청들도 거부되어 호출자가 무기한 대기하지 않습니다. 연결을 해제하지 않고 같은 iframe을 다른 모듈에 바인딩하면 INVALID_ARGUMENT로 실패합니다.

보안 경계

• 편집기 origin은 iframe.src 또는 frameworkOrigin 옵션에서 가져옵니다. 임의의 사용자 입력에서 받지 마십시오.
• 호스트 애플리케이션과 편집기 구성에서 신뢰할 수 있는 Office origin만 허용하십시오.
• 문서 접근 권한을 부여하는 문서 open URL은 민감 정보로 취급하십시오.
• SDK는 모든 메시지의 event.origin을 검증하며 *로 전송하지 않습니다.
• API 키, 스토리지 자격 증명, Office 서명 키를 공개 런타임 구성에 두지 마십시오.

Editor SDK는 사용자를 인증하거나 문서 접근 권한을 부여하지 않습니다. 연결하기 전에 사용자를 인가하고 문서 open URL을 발급받으십시오.