대규모 Word 보고서나 매뉴얼을 만들 때, 사용자가 빠르게 훑어볼 수 있도록 탐색 가능한 목차를 생성하는 것이 필수적입니다. Conholdate.Total for Java는 Java 애플리케이션에서 직접 DOCX 파일을 다루는 작업을 간소화하는 강력한 SDK를 제공합니다. 이 단계별 가이드에서는 설정, 코드 설명 및 모범 사례를 다루며 Java에서 Word 문서에 목차를 추가하는 방법을 배웁니다.

Java에서 Word 문서에 목차를 추가하는 전체 작업 예제

다음 예제는 Conholdate.Total for Java를 사용하여 DOCX 파일에 목차를 삽입하는 방법을 보여줍니다.

import com.aspose.words.Document;
import com.aspose.words.DocumentBuilder;
import com.aspose.words.BreakType;
import com.aspose.words.StyleIdentifier;

public class AddTableOfContentsExample {
    public static void main(String[] args) throws Exception {
        // Directory where the output document will be saved
        String dataDir = "output/";

// Create a new document and a builder to work with it
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a table of contents field at the current cursor position.
        // "\o \"1-3\" \h \z \u" includes heading levels 1-3, makes entries
        // clickable hyperlinks, hides tab leaders in Web layout, and uses
        // outline levels applied to non-heading styles.
        builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");

// Start the actual document content on the second page.
        builder.insertBreak(BreakType.PAGE_BREAK);

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        builder.writeln("Heading 1");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
        builder.writeln("Heading 1.1");
        builder.writeln("Heading 1.2");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        builder.writeln("Heading 2");
        builder.writeln("Heading 3");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
        builder.writeln("Heading 3.1");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_3);
        builder.writeln("Heading 3.1.1");
        builder.writeln("Heading 3.1.2");
        builder.writeln("Heading 3.1.3");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
        builder.writeln("Heading 3.2");
        builder.writeln("Heading 3.3");

// The newly inserted table of contents is initially empty.
        // It needs to be populated by updating the fields in the document.
        doc.updateFields();

doc.save(dataDir + "TableOfContents.docx");
    }
}

Note: 이 코드 예제는 핵심 기능을 보여줍니다. 프로젝트에서 사용하기 전에 출력 디렉터리(dataDir)를 실제 파일 위치에 맞게 업데이트하고, 모든 필수 종속성이 올바르게 설치되었는지 확인하며, 개발 환경에서 충분히 테스트하십시오. 문제가 발생하면 공식 문서를 참조하거나 지원 팀에게 문의하십시오.

Java 코드에서 Word 문서에 목차 추가 이해하기

아래는 샘플 코드가 수행하는 주요 단계의 개요입니다:

  1. 문서와 빌더 생성 - Document는 메모리 내 Word 파일을 나타내며, DocumentBuilder는 콘텐츠와 필드를 삽입하는 메서드를 제공합니다.

    Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

  2. 목차 필드 삽입 - insertTableOfContents는 커서 위치에 목차 필드를 삽입합니다. 스위치 문자열은 동작을 제어합니다: \o "1-3"는 1~3 수준의 헤딩을 포함하고, \h는 항목을 클릭 가능한 하이퍼링크로 만들며, \z는 웹 레이아웃 보기에서 탭 리더와 페이지 번호를 숨기고, \u는 단락에 적용된 개요 수준을 사용합니다.

    builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");

  3. 새 페이지에서 내용 시작 - insertBreak(BreakType.PAGE_BREAK)는 실제 문서 본문을 목차 뒤의 페이지로 이동시켜, 목차가 자체 페이지를 갖게 합니다.

    builder.insertBreak(BreakType.PAGE_BREAK);

  4. 헤딩 스타일 콘텐츠 추가 - setStyleIdentifier를 빌더의 단락 형식에 HEADING_1, HEADING_2 또는 HEADING_3으로 설정한 후 writeln을 호출하면 해당 내장 헤딩 스타일이 적용된 단락이 생성되며, TOC 필드가 항목을 검색합니다.

    builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
builder.writeln("Heading 1");

    자세한 API 참조는 API Reference 페이지에서 확인할 수 있습니다.

  5. 필드 업데이트 및 저장 - doc.updateFields()는 이제 제목이 존재하므로 TOC에 항목과 페이지 번호를 채우고, doc.save는 문서를 디스크에 저장합니다.

    doc.updateFields();
doc.save(dataDir + "TableOfContents.docx");

설치 및 구성 Conholdate.Total for Java

Conholdate Maven 저장소와 SDK 종속성을 pom.xml에 추가하십시오:

<repositories>
    <repository>
        <id>conholdate-repo</id>
        <name>Conholdate Maven Repository</name>
        <url>https://repository.conholdate.com/repo/</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.conholdate</groupId>
    <artifactId>conholdate-total</artifactId>
    <version>24.9</version>
    <type>pom</type>
</dependency>

최신 SDK 패키지를 다운로드 페이지에서 다운로드하십시오. SDK는 Java 8 이상이 필요하며 표준 JVM에서 실행됩니다. 추가 런타임 구성 요소는 필요하지 않습니다.

Java로 Word TOC 생성 모범 사례

  • 일관된 제목 스타일 사용 - TOC는 기본 제공 제목 수준(Heading 1, Heading 2 등)으로 스타일링된 단락을 감지합니다. 신뢰할 수 있는 항목 생성을 위해 원본 문서가 이러한 스타일을 사용하도록 하세요.
  • 제목 깊이 제한 - 너무 많은 수준을 포함하면 TOC가 복잡해질 수 있습니다. 일반 보고서는 예제의 \o "1-3" 스위치에 표시된 대로 1‑3 수준을 사용합니다.
  • 하이퍼링크 활성화 - \h 스위치를 포함하면 클릭 가능한 항목이 생성되어 최종 문서의 탐색이 향상됩니다.
  • 삽입 후 항상 updateFields 호출 - 새로 삽입된 TOC 필드는 doc.updateFields()가 실행될 때까지 비어 있으므로 모든 제목 내용이 추가된 후에 호출하세요.
  • 삽입 후 검증 - 생성된 DOCX를 열고 필드를 업데이트(Ctrl +A, F9)하여 페이지 numbers가 정확한지 확인하세요. 특히 추가 편집 후에 중요합니다.
  • 스위치 문자열 재사용 - 배치에서 여러 문서를 생성하는 경우 스위치 문자열을 한 번 만든 뒤 호출마다 재사용하여 형식이 일관되게 유지되도록 하세요.

결론

Java에서 Word 문서에 목차를 추가하는 작업은 Conholdate.Total for Java을 사용하면 간단해집니다. 문서를 생성하고, 적절한 스위치를 사용하여 TOC 필드를 삽입하고, 제목 스타일이 적용된 내용을 추가한 뒤 updateFields를 호출하면 전문적인 보고서와 매뉴얼을 자동으로 만들 수 있습니다. SDK를 설치하고, 모범 사례 권장 사항을 따르며, 대상 환경에서 생성된 목차를 테스트하는 것을 잊지 마세요. 실제 배포를 위해서는 라이선스가 필요하며, 가격 정보는 pricing page에서 확인할 수 있고, 임시 라이선스는 temporary license page에서 얻을 수 있습니다.

자주 묻는 질문

  • Java에서 Word 문서에 목차를 추가하는 가장 간단한 방법은 무엇인가요? 코드를 예제에 표시된 대로 builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u")를 호출하고, 제목 스타일 단락을 추가한 다음, 저장하기 전에 doc.updateFields()를 호출합니다.

  • 목차에 표시되는 제목 수준을 어떻게 제어할 수 있나요? insertTableOfContents에 전달되는 문자열의 \o 스위치 안의 수준 범위를 변경하십시오. 예를 들어 \o "1-2"는 1과 2 수준만 포함합니다.

  • 워드 템플릿에 나중에 채워질 TOC를 생성할 수 있나요? 예. 동적 콘텐츠를 채우기 전에 템플릿 파일에 TOC 필드를 삽입하십시오; 헤딩이 추가된 후 updateFields()를 호출하면 TOC가 자동으로 채워집니다.

  • 이 SDK를 사용하려면 인터넷 연결이 필요합니까? 아니요. Conholdate.Total for Java는 서버나 데스크톱에서 외부 서비스 호출 없이 실행되는 로컬 라이브러리입니다.

더 읽기