إضافة جدول محتويات إلى مستند Word في Java

إن إنشاء جدول محتويات قابل للتنقل أمر أساسي عند إنشاء تقارير Word الكبيرة أو الأدلة التي يحتاج المستخدمون إلى تصفحها بسرعة. Conholdate.Total for Java يقدم مجموعة تطوير برمجيات قوية تُبسّط العمل مع ملفات 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

فيما يلي تفصيل للخطوات الرئيسية التي ينفذها كود العينة:

إنشاء المستند والباني - Document يمثل ملف Word الموجود في الذاكرة، وDocumentBuilder يزودك بطرق لإدراج المحتوى والحقول فيه.
```
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
```
إدراج حقل الفهرس - insertTableOfContents يكتب حقل فهرس في موضع المؤشر. تتحكم سلسلة المفاتيح في سلوكه: \o "1-3" تشمل مستويات العناوين من 1 إلى 3، \h تجعل الإدخالات روابط قابلة للنقر، \z تخفي خطوط التبويب وأرقام الصفحات في عرض تخطيط الويب، و \u يستخدم مستوى المخطط المطبق على الفقرات.
```
builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");
```
ابدأ المحتوى في صفحة جديدة - insertBreak(BreakType.PAGE_BREAK) يدفع جسم المستند الفعلي إلى الصفحة بعد جدول المحتويات، بحيث يكون لجدول المحتويات صفحته الخاصة.
```
builder.insertBreak(BreakType.PAGE_BREAK);
```
إضافة محتوى بنمط العناوين - ضبط setStyleIdentifier على تنسيق الفقرة الخاص بالبناء إلى HEADING_1 أو HEADING_2 أو HEADING_3 قبل استدعاء writeln ينتج فقرات مُنسقة بالنمط المدمج المناسب للعنوان، والذي يقوم حقل الفهرس (TOC) بمسحه للعثور على الإدخالات.

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

يتوفر مرجع API التفصيلي في صفحة API Reference.

تحديث الحقول وحفظها - doc.updateFields() يملأ جدول المحتويات بالمدخلات وأرقام الصفحات الآن بعد وجود العناوين، و 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 فقط.
هل من الممكن إنشاء جدول محتويات لقالب Word سيتم ملؤه لاحقًا؟ نعم. قم بإدراج حقل جدول المحتويات في ملف القالب قبل ملء المحتوى الديناميكي؛ استدعاء updateFields() بعد إضافة العناوين سيملأ جدول المحتويات تلقائيًا.
هل أحتاج إلى اتصال بالإنترنت لاستخدام هذا SDK? لا. Conholdate.Total for Java هي مكتبة محلية تعمل على الخادم أو سطح المكتب الخاص بك دون أي استدعاءات خدمة خارجية.

مثال عملي كامل لإضافة جدول محتويات إلى مستند Word في Java#

فهم إضافة جدول المحتويات إلى مستند Word في كود Java#

تثبيت وتكوين Conholdate.Total for Java#

أفضل الممارسات لإنشاء فهرس Word باستخدام Java#

الخلاصة#

الأسئلة المتكررة#

المزيد#