العمل مع الإشارات المرجعية

تحدد الإشارات المرجعية في مستند Microsoft Word المواقع أو الأجزاء التي تقوم بتسميتها وتحديدها للرجوع إليها مستقبلاً. على سبيل المثال، يمكنك استخدام إشارة مرجعية لتحديد النص الذي تريد مراجعته لاحقًا. بدلاً من التمرير عبر المستند لتحديد موقع النص، يمكنك الانتقال إليه باستخدام مربع الحوار “إشارة مرجعية”.

الإجراءات التي يمكن تنفيذها باستخدام الإشارات المرجعية باستخدام Aspose.Words هي نفس الإجراءات التي يمكنك تنفيذها باستخدام Microsoft Word. يمكنك إدراج إشارة مرجعية جديدة، أو حذفها، أو الانتقال إليها، أو الحصول على اسم إشارة مرجعية أو تعيينه، أو الحصول على نص محاط بها أو تعيينه.

أدخل إشارة مرجعية

استخدم StartBookmark وEndBookmark لإنشاء إشارة مرجعية عن طريق تحديد بدايتها ونهايتها، على التوالي. لا تنس تمرير نفس اسم الإشارة المرجعية إلى كلا الطريقتين. يمكن أن تتداخل الإشارات المرجعية الموجودة في المستند وتمتد إلى أي نطاق. سيتم تجاهل الإشارات المرجعية التي تم تكوينها بشكل سيئ أو الإشارات المرجعية ذات الأسماء المكررة عند حفظ المستند.

تم استبدال جميع المسافات البيضاء في الإشارات المرجعية بشرطات سفلية. جاء هذا التقييد من تنسيقات Microsoft Word، نظرًا لأن الإشارات المرجعية بتنسيقات Word مثل DOCX أو DOC لا يمكن أن تحتوي على مسافات بيضاء. ومع ذلك، يسمح PDF بمثل هذه الإشارات المرجعية. والآن، إذا كنت بحاجة إلى استخدام الإشارات المرجعية في مخططات PDF أو XPS، فيمكنك استخدامها مع المسافات البيضاء.

يوضح مثال التعليمات البرمجية التالي كيفية إنشاء إشارة مرجعية جديدة:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithBookmarks();

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

builder.StartBookmark("My Bookmark");
builder.Writeln("Text inside a bookmark.");

builder.StartBookmark("Nested Bookmark");
builder.Writeln("Text inside a NestedBookmark.");
builder.EndBookmark("Nested Bookmark");

builder.Writeln("Text after Nested Bookmark.");
builder.EndBookmark("My Bookmark");


PdfSaveOptions options = new PdfSaveOptions();
options.OutlineOptions.BookmarksOutlineLevels.Add("My Bookmark", 1);
options.OutlineOptions.BookmarksOutlineLevels.Add("Nested Bookmark", 2);

dataDir = dataDir + "Create.Bookmark_out.pdf";
doc.Save(dataDir, options);

الحصول على الإشارات المرجعية

في بعض الأحيان يكون من الضروري الحصول على مجموعة إشارات مرجعية للتكرار من خلال الإشارات المرجعية أو لأغراض أخرى. استخدم خاصية Node.Range التي تم الكشف عنها بواسطة أي عقدة مستند تقوم بإرجاع كائن Range يمثل جزء المستند الموجود في هذه العقدة. استخدم هذا الكائن لاسترداد BookmarkCollection ثم استخدم مفهرس المجموعة للحصول على إشارة مرجعية محددة.

يوضح مثال التعليمات البرمجية التالي كيفية الحصول على الإشارات المرجعية من مجموعة الإشارات المرجعية:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithBookmarks();

Document doc = new Document(dataDir + "Bookmarks.doc");

// By index.
Bookmark bookmark1 = doc.Range.Bookmarks[0];
           
// By name.
Bookmark bookmark2 = doc.Range.Bookmarks["Bookmark2"];

يمكنك تنزيل الملف النموذجي لهذا المثال من Aspose.Words GitHub.

يوضح مثال التعليمات البرمجية التالي كيفية الحصول على اسم ونص الإشارة المرجعية أو تعيينهما:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithBookmarks();

Document doc = new Document(dataDir + "Bookmark.doc");

// Use the indexer of the Bookmarks collection to obtain the desired bookmark.
Bookmark bookmark = doc.Range.Bookmarks["MyBookmark"];

// Get the name and text of the bookmark.
string name = bookmark.Name;
string text = bookmark.Text;

// Set the name and text of the bookmark.
bookmark.Name = "RenamedBookmark";
bookmark.Text = "This is a new bookmarked text.";

يمكنك تنزيل الملف النموذجي لهذا المثال من Aspose.Words GitHub.

يوضح مثال التعليمات البرمجية التالي كيفية وضع إشارة مرجعية على جدول:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// Create empty document
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Table table = builder.StartTable();

// Insert a cell
builder.InsertCell();

// Start bookmark here after calling InsertCell
builder.StartBookmark("MyBookmark");

builder.Write("This is row 1 cell 1");

// Insert a cell
builder.InsertCell();
builder.Write("This is row 1 cell 2");

builder.EndRow();

// Insert a cell
builder.InsertCell();
builder.Writeln("This is row 2 cell 1");

// Insert a cell
builder.InsertCell();
builder.Writeln("This is row 2 cell 2");

builder.EndRow();

builder.EndTable();
// End of bookmark
builder.EndBookmark("MyBookmark");

dataDir = dataDir + "Bookmark.Table_out.doc";
doc.Save(dataDir);

إذا قمت بتغيير اسم الإشارة المرجعية إلى اسم موجود بالفعل في المستند، فلن يتم إنشاء أي خطأ وسيتم تخزين الإشارة المرجعية الأولى فقط عند حفظ المستند.

لاحظ أنه تم تعيين بعض الإشارات المرجعية في المستند لحقول النموذج. يؤدي الانتقال إلى هذه الإشارة المرجعية وإدراج النص هناك إلى إدراج النص في رمز حقل النموذج. على الرغم من أن هذا لن يؤدي إلى إبطال حقل النموذج، إلا أن النص المدرج لن يكون مرئيًا لأنه يصبح جزءًا من رمز الحقل.

يوضح مثال التعليمات البرمجية التالي كيفية الوصول إلى أعمدة الجدول الذي تم وضع إشارة مرجعية عليه:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// Create empty document
Document doc = new Document(dataDir + "Bookmark.Table_out.doc");
foreach (Bookmark bookmark in doc.Range.Bookmarks)
{
    Console.WriteLine("Bookmark: {0}{1}", bookmark.Name, bookmark.IsColumn ? " (Column)" : "");
    if (bookmark.IsColumn)
    {
        Row row = bookmark.BookmarkStart.GetAncestor(NodeType.Row) as Row;
        if (row != null && bookmark.FirstColumn < row.Cells.Count)
            Console.WriteLine(row.Cells[bookmark.FirstColumn].GetText().TrimEnd(ControlChar.CellChar));
    }
}

الانتقال إلى إشارة مرجعية

إذا كنت بحاجة إلى إدراج محتوى منسق (وليس مجرد نص عادي) في إشارة مرجعية، فيجب عليك استخدام MoveToBookmark لتحريك المؤشر إلى الإشارة المرجعية ثم استخدام أساليب وخصائص DocumentBuilder’s لإدراج المحتوى.

إظهار إخفاء محتوى الإشارة المرجعية

يمكن تغليف الإشارة المرجعية بأكملها (بما في ذلك المحتوى الذي تم وضع إشارة مرجعية) داخل الجزء الحقيقي من حقل IF باستخدام Aspose.Words. يمكن أن يحتوي حقل IF على حقل دمج متداخل في التعبير (يسار المشغل) واعتمادًا على قيمة حقل الدمج، يعرض حقل IF محتوى الإشارة المرجعية في مستند Word أو يخفيها.

يوضح مثال الكود التالي كيفية إظهار/إخفاء الإشارات المرجعية:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithBookmarks();

Document doc = new Document(dataDir + "Bookmarks.doc");
ShowHideBookmarkedContent(doc, "Bookmark2", false);
doc.Save(dataDir + "Updated_Document.doc");

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
public static void ShowHideBookmarkedContent(Document doc, String bookmarkName, bool showHide)
{
    DocumentBuilder builder = new DocumentBuilder(doc);
    Bookmark bm = doc.Range.Bookmarks[bookmarkName];

    builder.MoveToDocumentEnd();
    // {IF "{MERGEFIELD bookmark}" = "true" "" ""}
    Field field = builder.InsertField("IF \"", null);
    builder.MoveTo(field.Start.NextSibling);
    builder.InsertField("MERGEFIELD " + bookmarkName + "", null);
    builder.Write("\" = \"true\" ");
    builder.Write("\"");
    builder.Write("\"");
    builder.Write(" \"\"");

    Node currentNode = field.Start;
    bool flag = true;
    while (currentNode != null && flag)
    {
        if (currentNode.NodeType == NodeType.Run)
            if (currentNode.ToString(SaveFormat.Text).Trim().Equals("\""))
                flag = false;

        Node nextNode = currentNode.NextSibling;

        bm.BookmarkStart.ParentNode.InsertBefore(currentNode, bm.BookmarkStart);
        currentNode = nextNode;
    }

    Node endNode = bm.BookmarkEnd;
    flag = true;
    while (currentNode != null && flag)
    {
        if (currentNode.NodeType == NodeType.FieldEnd)
            flag = false;

        Node nextNode = currentNode.NextSibling;

        bm.BookmarkEnd.ParentNode.InsertAfter(currentNode, endNode);
        endNode = currentNode;
        currentNode = nextNode;
    }

    doc.MailMerge.Execute(new String[] { bookmarkName }, new Object[] { showHide });

    //MailMerge can be avoided by using the following
    //builder.MoveToMergeField(bookmarkName);
    //builder.Write(showHide ? "true" : "false");
}