Skip to content
Office Oxide

Office 문서 편집

EditableDocument는 Document의 읽기-수정-저장 버전입니다. 변경되지 않은 모든 OPC 파트——이미지, 차트, 스타일, 테마, 관계——를 그대로 유지하기 때문에, 편집이 주변 콘텐츠의 레이아웃을 바꾸거나 다운스트림 소비자를 무효화하지 않습니다.

편집은 DOCX, XLSX, PPTX에서 지원됩니다. 레거시 DOC, XLS, PPT는 읽기 전용입니다——편집이 필요하다면 먼저 save_as로 변환하세요.

할 수 있는 것

작업 DOCX XLSX PPTX 메서드
본문/플레이스홀더 텍스트 치환 ✓ — ✓ replace_text
셀 값 설정 (string / number / bool / empty) — ✓ — set_cell
디스크에 저장 ✓ ✓ ✓ save
바이트로 저장 ✓ ✓ ✓ save_to_bytes

XLSX에서 replace_text를 호출하면 0을 반환합니다 (<w:t>나 <a:t> 요소가 없기 때문입니다); 스프레드시트에는 set_cell을 사용하세요.

열기, 편집, 저장

Rust

use office_oxide::edit::EditableDocument;

let mut ed = EditableDocument::open("template.docx")?;
ed.replace_text("{{name}}", "Alice");
ed.replace_text("{{date}}", "2026-04-19");
ed.save("filled.docx")?;

Python

from office_oxide import EditableDocument

with EditableDocument.open("template.docx") as ed:
    ed.replace_text("{{name}}", "Alice")
    ed.replace_text("{{date}}", "2026-04-19")
    ed.save("filled.docx")

JavaScript

import { EditableDocument } from 'office-oxide';

using ed = EditableDocument.open('template.docx');
ed.replaceText('{{name}}', 'Alice');
ed.replaceText('{{date}}', '2026-04-19');
ed.save('filled.docx');

Go

ed, err := officeoxide.OpenEditable("template.docx")
defer ed.Close()
ed.ReplaceText("{{name}}", "Alice")
ed.ReplaceText("{{date}}", "2026-04-19")
ed.Save("filled.docx")

C#

using var ed = EditableDocument.Open("template.docx");
ed.ReplaceText("{{name}}", "Alice");
ed.ReplaceText("{{date}}", "2026-04-19");
ed.Save("filled.docx");

C

int err = 0;
OfficeEditableHandle *ed = office_editable_open("template.docx", &err);
office_editable_replace_text(ed, "{{name}}", "Alice", &err);
office_editable_replace_text(ed, "{{date}}", "2026-04-19", &err);
office_editable_save(ed, "filled.docx", &err);
office_editable_free(ed);

바이트로 저장 (업로드 / 스트리밍용)

Rust

let mut ed = EditableDocument::open("template.docx")?;
ed.replace_text("{{name}}", "Alice");

let mut buf = std::io::Cursor::new(Vec::new());
ed.write_to(&mut buf)?;
let bytes: Vec<u8> = buf.into_inner();

Python

with EditableDocument.open("template.docx") as ed:
    ed.replace_text("{{name}}", "Alice")
    bytes_out = ed.save_to_bytes()
    # upload bytes_out to S3 / send over HTTP / etc.

JavaScript

using ed = EditableDocument.open('template.docx');
ed.replaceText('{{name}}', 'Alice');
const bytes = ed.saveToBytes();   // Uint8Array

C

int err = 0;
OfficeEditableHandle *ed = office_editable_open("template.docx", &err);
office_editable_replace_text(ed, "{{name}}", "Alice", &err);

size_t out_len = 0;
uint8_t *buf = office_editable_save_to_bytes(ed, &out_len, &err);
/* stream buf[0..out_len], then: */
office_oxide_free_bytes(buf, out_len);
office_editable_free(ed);

"OPC 파트 보존"이 실제로 의미하는 것

OOXML 파일은 수십 개의 XML 파트와 바이너리 파트(이미지, 글꼴, 임베드 객체)를 담은 ZIP 아카이브입니다. 단순한 편집기는 저장할 때 모든 파트를 다시 직렬화하는데, 이로 인해 다음과 같은 문제가 발생할 수 있습니다.

  • 관계가 재정렬되어 링크가 깨집니다
  • 편집기가 이해하지 못하는 확장 파트가 제거됩니다 (custom XML, AlternateContent 폴백)
  • XML이 재포맷되어 다운스트림 diff와 서명이 깨집니다

EditableDocument는 수정한 파트만 다시 씁니다. 나머지는 바이트 단위로 그대로 복사됩니다. 그 결과 입력과 출력 사이의 최소한의 diff가 생성되어 버전 관리, 서명 검증, 다른 도구와의 왕복 처리에 유리합니다.

형식 전용 API를 사용해야 할 때

EditableDocument는 80% 사례(템플릿 처리, 일괄 입력, 셀 쓰기)를 커버합니다. 단락 추가, 표 삽입, 스타일 조정, 처음부터 슬라이드 구성 등 더 복잡한 편집이 필요하다면 형식 전용 API를 사용하세요.

use office_oxide::docx::edit::DocxEditor;

let mut docx = DocxEditor::open("report.docx")?;
docx.append_paragraph("New section", Some("Heading2"));
docx.save("report.docx")?;

형식 전용 편집기는 각 바인딩의 레퍼런스에 문서화되어 있습니다 (Rust: docx::edit, xlsx::edit, pptx::edit).

관련 항목

  • 텍스트 치환 — replace_text API 상세 설명
  • XLSX 셀 설정 — 셀 타입, 형식, 엣지 케이스
  • 변환 — 레거시 DOC/XLS/PPT를 편집 가능한 OOXML로 먼저 변환