ایجاد یک فهرست قابل پیمایش برای گزارش‌ها یا کتابچه‌های بزرگ Word که کاربران نیاز به مرور سریع دارند، ضروری است. Conholdate.Total for Java یک SDK قدرتمند فراهم می‌کند که کار با فایل‌های DOCX را مستقیماً از برنامه‌های Java ساده می‌سازد. در این راهنمای گام‑به‑گام، خواهید آموخت که چگونه یک فهرست مطالب را به یک سند Word در Java اضافه کنید، شامل تنظیمات، توضیح کد و بهترین شیوه‌ها.

مثال کامل کارآمد برای افزودن فهرست مطالب به سند Word در Java

مثال زیر نشان می‌دهد که چگونه می‌توان فهرست مطالب را در یک فایل DOCX با استفاده از Conholdate.Total for Java وارد کرد.

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");
    }
}

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه‌تان، مطمئن شوید که مسیر خروجی (dataDir) را به مکان واقعی فایل خود به‌روزرسانی کنید، اطمینان حاصل کنید که تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند، و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه کنید.

درک افزودن فهرست مطالب به سند Word در کد Java

در زیر تجزیه و تحلیل مراحل اصلی که توسط کد نمونه انجام می‌شود آورده شده است:

  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");
  1. شروع محتوا در صفحه جدید - insertBreak(BreakType.PAGE_BREAK) بدنه واقعی سند را پس از فهرست مطالب (TOC) به صفحه بعد می‌برد، به‌طوری که فهرست مطالب صفحهٔ خود را داشته باشد.
builder.insertBreak(BreakType.PAGE_BREAK);
  1. افزودن محتوای با سبک عنوان - تنظیم setStyleIdentifier در قالب پاراگراف سازنده به HEADING_1، HEADING_2 یا HEADING_3 قبل از فراخوانی writeln پاراگراف‌هایی با سبک عنوان داخلی متناظر تولید می‌کند که فیلد TOC برای یافتن ورودی‌ها اسکن می‌کند.
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
builder.writeln("Heading 1");

مرجع دقیق API در صفحه API Reference موجود است.

  1. به‌روزرسانی فیلدها و ذخیره - doc.updateFields() فهرست مطالب (TOC) را با ورودی‌ها و شماره صفحات پر می‌کند حالا که عناوین وجود دارند، و doc.save سند را بر روی دیسک می‌نویسد.
doc.updateFields();
doc.save(dataDir + "TableOfContents.docx");

نصب و پیکربندی Conholdate.Total for Java

مخزن Maven Conholdate و وابستگی 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 استانداردی اجرا می‌شود. هیچ مؤلفه زمان اجرای اضافی مورد نیاز نیست.

بهترین روش‌ها برای تولید فهرست مطالب Word با Java

  • از سبک‌های یکسان برای عناوین استفاده کنید - فهرست مطالب (TOC) پاراگراف‌هایی را که با سطوح پیش‌فرض عناوین (Heading 1، Heading 2 و غیره) قالب‌بندی شده‌اند، شناسایی می‌کند. اطمینان حاصل کنید که سند منبع شما از این سبک‌ها برای تولید ورودی‌های قابل اعتماد استفاده می‌کند.
  • عمق عناوین را محدود کنید - افزودن سطوح بیش از حد می‌تواند فهرست مطالب را دشوار کند. گزارش‌های معمولی از سطوح 1‑3 استفاده می‌کنند، همان‌طور که در سوئیچ \o "1-3" مثال نشان داده شده است.
  • پیوندهای فراگیر را فعال کنید - افزودن سوئیچ \h ورودی‌های قابل کلیک ایجاد می‌کند و ناوبری در سند نهایی را بهبود می‌بخشد.
  • همیشه پس از افزودن، متد updateFields را فراخوانی کنید - فیلد فهرست مطالب تازه‌وارده تا زمانی که doc.updateFields() اجرا شود، خالی است، بنابراین پس از افزودن تمام محتوای عناوین آن را صدا بزنید.
  • پس از افزودن، صحت‌سنجی کنید - فایل DOCX تولید شده را باز کنید و فیلدها را به‌روزرسانی کنید (Ctrl +A، F9) تا اطمینان حاصل شود که شماره‌های صفحه اعداد صحیح هستند، به‌ویژه پس از ویرایش‌های بیشتر.
  • رشته سوئیچ را مجدداً استفاده کنید - اگر در یک دسته چندین سند تولید می‌کنید، رشته سوئیچ را یک‌بار بسازید و در فراخوانی‌های بعدی باز استفاده کنید تا قالب‌بندی یکسان باقی بماند.

نتیجه‌گیری

افزودن فهرست مطالب به یک سند Word در Java به سادگی انجام می‌شود با Conholdate.Total for Java. با ایجاد یک سند، درج فیلد TOC با سوئیچ‌های مناسب، افزودن محتوای دارای سبک عنوان، و فراخوانی updateFields می‌توانید فرآیند ایجاد گزارش‌ها و راهنماهای حرفه‌ای را خودکار کنید. به یاد داشته باشید SDK را نصب کنید، توصیه‌های بهترین روش‌ها را دنبال کنید و فهرست مطالب تولید شده را در محیط هدف خود تست کنید. برای استقرارهای تولیدی به یک نسخه دارای لایسنس نیاز خواهید داشت؛ جزئیات قیمت‌گذاری در صفحه قیمت‌گذاری موجود است و می‌توانید یک لایسنس موقت را از صفحه لایسنس موقت دریافت کنید.

سوالات متداول

  • ساده‌ترین روش برای افزودن فهرست مطالب به یک سند Word در Java چیست؟ متد builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u") را فراخوانی کنید، پاراگراف‌های با سبک عنوان را اضافه کنید، سپس قبل از ذخیره‌سازی متد doc.updateFields() را صدا بزنید، همان‌طور که در مثال کد نشان داده شده است.

  • چگونه می‌توانم کنترل کنم که کدام سطوح عنوان در فهرست مطالب ظاهر شوند؟ محدوده سطح را داخل سوئیچ \o رشته‌ای که به insertTableOfContents پاس داده می‌شود، تغییر دهید، برای مثال \o "1-2" تا فقط سطوح 1 و 2 را شامل شود.

  • آیا امکان تولید فهرست مطالب (TOC) برای یک قالب Word وجود دارد که بعداً پر شود؟ بله. فیلد TOC را قبل از پر کردن محتوای پویا در فایل قالب وارد کنید؛ فراخوانی updateFields() پس از افزودن عناوین، فهرست مطالب را به‌صورت خودکار پر خواهد کرد.

  • آیا برای استفاده از این SDK به اتصال اینترنت نیاز دارم؟ خیر. Conholdate.Total for Java یک کتابخانه محلی است که بر روی سرور یا دسکتاپ شما بدون هیچ تماس سرویس خارجی اجرا می‌شود.

بیشتر بخوانید