문서 작업
문서 작업
Aspose.Words FOSS for .NET은 모든 Word 파일을 Document 클래스에 루트된 메모리 내 객체 모델로 나타내며, DocumentBuilder은 콘텐츠 저작을 위한 고수준 커서 기반 API을 제공합니다. 이 가이드는 문서 생성 및 로드, DocumentBuilder를 사용한 저작, 섹션/본문 구조, 노드 트리 탐색, 문서 결합 및 보호에 대해 다룹니다.
문서 생성 및 로드
new Document()으로 빈 문서를 만들거나, 경로 또는 Stream을 Document(fileName) 또는 Document(stream) 생성자에 전달하여 기존 파일을 엽니다. LoadOptions 인수를 받는 오버로드를 사용하면 암호화된 파일에 대한 비밀번호 제공과 같이 로드 동작을 제어할 수 있습니다.
알 수 없거나 신뢰할 수 없는 출처의 파일을 로드하기 전에, FileFormatUtil.DetectFileFormat(fileName)(또는 Stream 오버로드)는 감지된 LoadFormat을 설명하는 FileFormatInfo와 파일이 IsEncrypted, HasDigitalSignature, 혹은 HasMacros인지 여부를 반환합니다.
DocumentBuilder를 사용한 저작
DocumentBuilder은 Document을 래핑하고, 콘텐츠를 삽입하면서 문서 내를 이동하는 커서를 노출합니다. Write(text)와 Writeln(text)은 커서 위치에 텍스트를 삽입하고; InsertParagraph()는 새 단락을 시작합니다. 빌더의 서식 속성 — Font, ParagraphFormat, ListFormat, PageSetup — 은 다음에 작성되는 모든 내용에 적용됩니다.
커서를 MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) 또는 MoveToParagraph(paragraphIndex, characterIndex) 로 이동합니다. 빌더의 CurrentNode, CurrentParagraph, CurrentSection 속성은 트리에서 현재 위치를 보고합니다.
문서 구조: 섹션 및 본문
Document는 SectionCollection(Document.Sections와 FirstSection / LastSection 포함)을 보유합니다; 각 Section는 하나의 Body, 선택적인 머리글/바닥글 컬렉션 및 자체 PageSetup을 가집니다. Section.AppendContent(sourceSection)와 PrependContent(sourceSection)는 섹션 간에 내용을 복사하고, ClearContent()은 문서에서 섹션을 제거하지 않고 재설정합니다.
Body 내부에서는 내용이 Body.Paragraphs( ParagraphCollection )와 Body.Tables을 통해 노출됩니다. Range는 Document, Section, Paragraph 및 기타 노드에서 사용할 수 있으며 트리의 연속된 영역을 나타냅니다; Range.Text는 해당 영역의 순수 텍스트를 읽고 Range.Replace(pattern, replacement)는 그 영역만을 대상으로 찾기 및 바꾸기를 수행합니다.
DocumentVisitor를 사용한 노드 트리 순회
문서의 모든 부분 — 섹션, 단락, 실행, 표, 필드, 도형, 댓글, 각주 — 은 Document을 루트로 하는 복합 트리에서 Node입니다. 특정 유형의 모든 노드를 수동으로 재귀 호출하지 않고 처리하려면 추상 DocumentVisitor를 서브클래스화하고 필요한 Visit*Start/Visit*End 콜백(예: VisitParagraphStart(paragraph) 또는 VisitRun(run))을 재정의한 뒤 document.Accept(visitor)을 호출하십시오. 각 콜백은 트래버설 진행 방식을 제어하기 위해 VisitorAction(Continue, SkipThisNode, 또는 Stop)를 반환할 수 있습니다.
복제, 가져오기 및 내용 추가
Document.Clone()은 전체 문서의 깊은 복사본을 생성합니다. 두 개의 서로 다른 Document 인스턴스 간에 내용을 이동하려면 대상 문서에서 ImportNode(srcNode, isImportChildren)를 호출하여 외부 트리의 노드를 가져오거나, 선택한 ImportFormatMode — KeepSourceFormatting, UseDestinationStyles 또는 KeepDifferentStyles — 를 사용하여 한 문서의 섹션을 다른 문서에 추가하려면 Document.AppendDocument(srcDoc, importFormatMode)을 호출하십시오. DocumentBuilder.InsertDocument(srcDoc, importFormatMode)은 대상 문서 끝이 아니라 빌더의 커서 위치에 소스 문서의 내용을 삽입합니다.
문서 보호
Document.Protect(type, password)은(는) ProtectionType 값에 따라 편집을 제한합니다 — 보호를 해제하려면 ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields 또는 NoProtection 중 하나를 사용합니다. Unprotect()(비밀번호 유무에 관계없이)는 이를 되돌립니다. 이것은 Word에서 적용하는 편집 제한이며, 파일을 저장할 때 OoxmlSaveOptions.Password이 적용하는 OOXML 비밀번호 암호화와는 별개입니다.
팁 및 모범 사례
- 새 콘텐츠를 만들 때는
DocumentBuilder을(를) 선호하고, 기존 트리에 대해 세밀한 제어가 필요할 경우 직접 노드 조작(AppendChild,InsertAfter,Clone)으로 전환하세요. - 신뢰할 수 없거나 사용자가 제공한 소스에서 파일을 로드하기 전에
FileFormatUtil.DetectFileFormat을 호출하여LoadFormat을 확인하고 지원되지 않거나 암호화된 입력을 조기에 거부할 수 있습니다. AppendDocument또는InsertDocument을(를) 사용해 문서를 결합할 때는ImportFormatMode를 신중히 선택하세요 —KeepSourceFormatting은 원본의 외관을 유지하고,UseDestinationStyles는 대상 문서의 스타일 세트에 맞춥니다.- 노드 타입의 모든 인스턴스를 일관되게 처리해야 할 경우 수동 재귀 트리 탐색 대신
DocumentVisitor서브클래스를 사용하세요. Document.Protect은 편집 제한이며 암호화가 아닙니다 — 저장된 파일 자체가 열 때 비밀번호가 필요하다면OoxmlSaveOptions.Password과 함께 사용하세요.
일반 문제
| 문제 | 원인 | 해결 방법 |
|---|---|---|
Document(fileName)은(는) Word에서 정상적으로 열리는 파일에 대해 예외를 발생시킵니다 | 파일 형식이 이 버전에서 로드하도록 지원되지 않습니다 | 먼저 FileFormatUtil.DetectFileFormat을(를) 호출하고 로드하기 전에 반환된 LoadFormat을 확인하십시오 |
| 추가된 콘텐츠가 잘못된 글꼴이나 스타일을 적용합니다 | ImportFormatMode 원본 및 대상 스타일 세트 간 불일치 | Pass KeepSourceFormatting or UseDestinationStyles explicitly instead of relying on a default |
DocumentVisitor traversal stops early or skips content | A Visit*Start / Visit*End override returns SkipThisNode or Stop unintentionally | Return VisitorAction.Continue from every override unless you specifically intend to skip or stop |
Unprotect() has no effect | The document wasn’t protected with a password, or the wrong password was supplied | Call Unprotect() with no arguments if Protect was called without a password, otherwise pass the matching password |
FAQ
Document.Clone()와 ImportNode의 차이점은 무엇인가요?
Clone()는 전체 문서를 새로운 Document 인스턴스로 복사합니다. ImportNode(srcNode, isImportChildren)는 하나의 문서 트리에서 단일 노드(및 선택적으로 그 자식)를 다른 문서로 가져오며, 이는 전체 문서가 아니라 특정 콘텐츠를 결합할 때 사용합니다.
어떤 파일 형식을 Document(fileName)가 로드할 수 있나요?
Document(fileName)는 DOCX, DOCM, DOTX, DOTM, Flat OPC(매크로 사용 가능 버전 및 템플릿 변형 포함), Markdown, 그리고 일반 텍스트를 로드합니다. 오래된 워드 프로세싱 및 웹 형식은 이 버전의 로더에서 제외되었습니다.
현재 DocumentBuilder가 위치한 곳을 어떻게 찾나요?
빌더 인스턴스에서 CurrentNode, CurrentParagraph 또는 CurrentSection를 읽으세요.
저장된 파일을 Document.Protect가 암호화합니까?
아니요 — 파일이 열릴 때 Word에서 적용하는 편집 제한입니다. 파일을 열 때 비밀번호가 필요하도록 하려면 저장할 때 OoxmlSaveOptions.Password를 설정하십시오.
문서 본문에서 단락만 읽으려면 어떻게 해야 하나요?
Body.Paragraphs 컬렉션을 사용하거나, 다른 노드 유형의 경우 Body.GetChildNodes(nodeType, isDeep)을(를) 사용하십시오.
API Reference 요약
| Class/Method | 설명 |
|---|---|
Document | 문서 객체 모델의 루트; 생성자는 파일이나 스트림에서 로드하거나 빈 문서를 생성합니다. |
Document.Save | 선택한 형식으로 문서를 파일, 스트림 또는 HTTP 응답에 기록합니다. |
Document.Clone() | 전체 문서의 깊은 복사본을 생성합니다. |
Document.Protect(type, password) / Unprotect() | 편집 제한을 적용하거나 제거합니다. |
Document.AppendDocument(srcDoc, importFormatMode) | 다른 문서의 섹션을 이 문서에 추가합니다. |
DocumentBuilder | 문서에 텍스트를 쓰고 내용을 삽입하기 위한 커서 기반 API. |
DocumentBuilder.InsertDocument(srcDoc, importFormatMode) | 커서 위치에 원본 문서의 내용을 삽입합니다. |
Section / SectionCollection | 문서의 단일 섹션과 모든 섹션의 모음. |
Body | 섹션의 주요 텍스트(단락 및 표)를 담는 컨테이너. |
Range | 문서 트리의 연속적인 영역; Text와 Replace을 지원합니다. |
DocumentVisitor | 문서 트리의 모든 노드를 순회하기 위한 추상 기본 클래스. |
ProtectionType | 문서 수준 편집 제한을 정의한 열거형. |
FileFormatUtil.DetectFileFormat | 로드하기 전에 파일이나 스트림의 형식을 감지합니다. |
