FieldStart

FieldStart class

يمثل بداية حقل Word في مستند.

لمعرفة المزيد، قم بزيارةالعمل مع الحقول مقالة توثيقية.

public class FieldStart : FieldChar

الخصائص

اسموصف
CustomNodeId { get; set; }يحدد معرف العقدة المخصص.
virtual Document { get; }يحصل على المستند الذي تنتمي إليه هذه العقدة.
FieldData { get; }يحصل على بيانات الحقل المخصصة المرتبطة بالحقل.
FieldType { get; }يعيد نوع الحقل.
Font { get; }يوفر الوصول إلى تنسيق الخط لهذا الكائن.
virtual IsComposite { get; }إرجاعحقيقي إذا كانت هذه العقدة قادرة على احتواء عقد أخرى.
IsDeleteRevision { get; }يعود صحيحًا إذا تم حذف هذا الكائن في Microsoft Word أثناء تمكين تتبع التغييرات.
IsDirty { get; set; }يحصل على أو يعين ما إذا كانت النتيجة الحالية للحقل لم تعد صحيحة (قديمة) بسبب التعديلات الأخرى التي تم إجراؤها على المستند.
IsFormatRevision { get; }يعود صحيحًا إذا تم تغيير تنسيق الكائن في Microsoft Word أثناء تمكين تتبع التغييرات.
IsInsertRevision { get; }يعود صحيحًا إذا تم إدراج هذا الكائن في Microsoft Word أثناء تمكين تتبع التغييرات.
IsLocked { get; set; }يحصل على أو يحدد ما إذا كان الحقل الرئيسي مقفلاً (لا ينبغي إعادة حساب نتيجته).
IsMoveFromRevision { get; }إرجاعحقيقي إذا تم نقل هذا الكائن (حذفه) في Microsoft Word أثناء تمكين تتبع التغييرات.
IsMoveToRevision { get; }إرجاعحقيقي إذا تم نقل هذا الكائن (إدراجه) في Microsoft Word أثناء تمكين تتبع التغييرات.
NextSibling { get; }يحصل على العقدة التي تلي هذه العقدة مباشرة.
override NodeType { get; }إرجاعFieldStart .
ParentNode { get; }يحصل على الوالد المباشر لهذه العقدة.
ParentParagraph { get; }يسترد الأصلParagraph من هذه العقدة.
PreviousSibling { get; }يحصل على العقدة التي تسبق هذه العقدة مباشرةً.
Range { get; }يعيدRangeالكائن الذي يمثل الجزء من المستند الموجود في هذه العقدة.

طُرق

اسموصف
override Accept(DocumentVisitor)يقبل زائرًا.
Clone(bool)ينشئ نسخة مكررة من العقدة.
GetAncestor(NodeType)يحصل على السلف الأول للعنصر المحددNodeType .
GetAncestor(Type)يحصل على السلف الأول لنوع الكائن المحدد.
GetField()يعيد حقلًا لحقل char.
override GetText()يحصل على الحرف الخاص الذي تمثله هذه العقدة.
NextPreOrder(Node)يحصل على العقدة التالية وفقًا لخوارزمية عبور شجرة الترتيب المسبق.
PreviousPreOrder(Node)يحصل على العقدة السابقة وفقًا لخوارزمية عبور شجرة الترتيب المسبق.
Remove()يزيل نفسه من الأصل.
ToString(SaveFormat)يصدر محتوى العقدة إلى سلسلة بالتنسيق المحدد.
ToString(SaveOptions)يقوم بتصدير محتوى العقدة إلى سلسلة باستخدام خيارات الحفظ المحددة.

ملاحظات

FieldStart هي عقدة على مستوى الخط ويتم تمثيلها بواسطة FieldStartChar حرف التحكم في المستند.

FieldStart لا يمكن أن يكون إلا طفلاParagraph.

الحقل الكامل في مستند مايكروسوفت وورد هو بنية معقدة تتكون من حرف بداية الحقل، ورمز الحقل، وحرف فاصل الحقل، ونتيجة الحقل x000d، وحرف نهاية الحقل. بعض الحقول تحتوي فقط على بداية الحقل، ورمز الحقل، ونهاية الحقل.

لإدراج حقل جديد بسهولة في مستند، استخدمInsertField طريقة .

أمثلة

يوضح كيفية العمل مع مجموعة من الحقول.

public void FieldCollection()
{
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    builder.InsertField(" DATE \\@ \"dddd, d MMMM yyyy\" ");
    builder.InsertField(" TIME ");
    builder.InsertField(" REVNUM ");
    builder.InsertField(" AUTHOR  \"John Doe\" ");
    builder.InsertField(" SUBJECT \"My Subject\" ");
    builder.InsertField(" QUOTE \"Hello world!\" ");
    doc.UpdateFields();

    FieldCollection fields = doc.Range.Fields;

    Assert.AreEqual(6, fields.Count);

    // قم بالتكرار على مجموعة الحقول، ثم اطبع المحتويات والنوع
    // لكل حقل باستخدام تنفيذ زائر مخصص.
    FieldVisitor fieldVisitor = new FieldVisitor();

    using (IEnumerator<Field> fieldEnumerator = fields.GetEnumerator())
    {
        while (fieldEnumerator.MoveNext())
        {
            if (fieldEnumerator.Current != null)
            {
                fieldEnumerator.Current.Start.Accept(fieldVisitor);
                fieldEnumerator.Current.Separator?.Accept(fieldVisitor);
                fieldEnumerator.Current.End.Accept(fieldVisitor);
            }
            else
            {
                Console.WriteLine("There are no fields in the document.");
            }
        }
    }

    Console.WriteLine(fieldVisitor.GetText());
}

/// <summary>
/// تنفيذ زائر المستند الذي يطبع معلومات الحقل.
/// </summary>
public class FieldVisitor : DocumentVisitor
{
    public FieldVisitor()
    {
        mBuilder = new StringBuilder();
    }

    /// <summary>
    /// يحصل على النص العادي للمستند الذي جمعه الزائر.
    /// </summary>
    public string GetText()
    {
        return mBuilder.ToString();
    }

    /// <summary>
    /// يتم استدعاؤها عند مواجهة عقدة FieldStart في المستند.
    /// </summary>
    public override VisitorAction VisitFieldStart(FieldStart fieldStart)
    {
        mBuilder.AppendLine("Found field: " + fieldStart.FieldType);
        mBuilder.AppendLine("\tField code: " + fieldStart.GetField().GetFieldCode());
        mBuilder.AppendLine("\tDisplayed as: " + fieldStart.GetField().Result);

        return VisitorAction.Continue;
    }

    /// <summary>
    /// يتم استدعاؤها عند مواجهة عقدة FieldSeparator في المستند.
    /// </summary>
    public override VisitorAction VisitFieldSeparator(FieldSeparator fieldSeparator)
    {
        mBuilder.AppendLine("\tFound separator: " + fieldSeparator.GetText());

        return VisitorAction.Continue;
    }

    /// <summary>
    /// يتم استدعاؤها عند مواجهة عقدة FieldEnd في المستند.
    /// </summary>
    public override VisitorAction VisitFieldEnd(FieldEnd fieldEnd)
    {
        mBuilder.AppendLine("End of field: " + fieldEnd.FieldType);

        return VisitorAction.Continue;
    }

    private readonly StringBuilder mBuilder;
}

يوضح كيفية العثور على جميع الارتباطات التشعبية في مستند Word، ثم تغيير عناوين URL وأسماء العرض الخاصة بها.

using System;
using System.Linq;
using System.Text;
using System.Text.RegularExpressions;
using Aspose.Words;
using Aspose.Words.Fields;
using NUnit.Framework;

namespace ApiExamples
{
    public class ExReplaceHyperlinks : ApiExampleBase
    {
        public void Fields()
        {
            Document doc = new Document(MyDir + "Hyperlinks.docx");

            // الروابط التشعبية في مستندات Word هي حقول. للبدء بالبحث عن الروابط التشعبية، يجب أولاً العثور على جميع الحقول.
            //استخدم طريقة "SelectNodes" للعثور على جميع الحقول في المستند عبر XPath.
            NodeList fieldStarts = doc.SelectNodes("//بدء الحقل");

            foreach (FieldStart fieldStart in fieldStarts.OfType<FieldStart>())
            {
                if (fieldStart.FieldType == FieldType.FieldHyperlink)
                {
                    Hyperlink hyperlink = new Hyperlink(fieldStart);

                    //الروابط التشعبية التي ترتبط بالإشارات المرجعية لا تحتوي على عناوين URL.
                    if (hyperlink.IsLocal)
                        continue;

                    // أعط كل رابط تشعبي لـ URL عنوان URL جديدًا واسمًا.
                    hyperlink.Target = NewUrl;
                    hyperlink.Name = NewName;
                }
            }

            doc.Save(ArtifactsDir + "ReplaceHyperlinks.Fields.docx");
        }

        private const string NewUrl = @"http://www.aspose.com";
        private const string NewName = "Aspose - The .NET & Java Component Publisher";
    }

     ///<summary>
      ///تحتوي حقول الارتباط التشعبي على روابط تشعبية وتعرضها في نص المستند. حقل في Aspose.Words
      ///يتكون من عدة عقد، وقد يكون من الصعب العمل مع كل هذه العقد بشكل مباشر.
     ///سيعمل هذا التنفيذ فقط إذا كان كود الارتباط التشعبي واسم كل منهما يتكون من عقدة تشغيل واحدة فقط.
    ///
     ///هيكل العقدة للحقول هو كما يلي:
     ///
     ///[FieldStart][Run - field code][FieldSeparator][Run - field result][FieldEnd]
     ///
     ///Below are two example field codes of HYPERLINK fields:
     ///HYPERLINK "url"
     ///HYPERLINK \l "bookmark name"
     ///
     ///A field's "Result" property contains text that the field displays in the document body to the user.
     ///</summary>
    internal class Hyperlink
    {
        internal Hyperlink(FieldStart fieldStart)
        {
            if (fieldStart == null)
                throw new ArgumentNullException("fieldStart");
            if (fieldStart.FieldType != FieldType.FieldHyperlink)
                throw new ArgumentException("Field start type must be FieldHyperlink.");

            mFieldStart = fieldStart;

            // ابحث عن عقدة فاصل الحقل.
            mFieldSeparator = FindNextSibling(mFieldStart, NodeType.FieldSeparator);
            if (mFieldSeparator == null)
                throw new InvalidOperationException("Cannot find field separator.");

             // عادةً، يمكننا دائمًا العثور على عقدة نهاية الحقل، ولكن مستند المثال
             // يحتوي على فاصل فقرة داخل ارتباط تشعبي، مما يضع نهاية الحقل
             // في الفقرة التالية. سيكون التعامل مع الحقول التي تمتد على عدة
            // الفقرات بشكل صحيح. في هذه الحالة، يكفي أن تكون نهاية الحقل فارغة.
            mFieldEnd = FindNextSibling(mFieldSeparator, NodeType.FieldEnd);

            // يبدو رمز الحقل مثل "HYPERLINK "http:\\www.myurl.com""، ولكنه قد يتكون من عدة عمليات تشغيل.
            string fieldCode = GetTextSameParent(mFieldStart.NextSibling, mFieldSeparator);
            Match match = gRegex.Match(fieldCode.Trim());

            // يكون الارتباط التشعبي محليًا إذا كان \l موجودًا في رمز الحقل.
            mIsLocal = match.Groups[1].Length > 0; 
            mTarget = match.Groups[2].Value;
        }

         ///<summary>
         ///Gets or sets the display name of the hyperlink.
         ///</summary>
        internal string Name
        {
            get
            {
                return GetTextSameParent(mFieldSeparator, mFieldEnd);
            }
            set
            {
                 // يتم تخزين اسم عرض الارتباط التشعبي في حقل النتيجة، وهو عبارة عن تشغيل
                //عقدة بين فاصل الحقل ونهاية الحقل.
                Run fieldResult = (Run) mFieldSeparator.NextSibling;
                fieldResult.Text = value;

                // إذا كانت نتيجة الحقل تتكون من أكثر من تشغيل واحد، فاحذف هذه التشغيلات.
                RemoveSameParent(fieldResult.NextSibling, mFieldEnd);
            }
        }

         ///<summary>
         ///Gets or sets the target URL or bookmark name of the hyperlink.
         ///</summary>
        internal string Target
        {
            get
            {
                return mTarget;
            }
            set
            {
                mTarget = value;
                UpdateFieldCode();
            }
        }

         ///<summary>
         ///True if the hyperlinks target is a bookmark inside the document. False if the hyperlink is a URL.
         ///</summary>
        internal bool IsLocal
        {
            get
            {
                return mIsLocal;
            }
            set
            {
                mIsLocal = value;
                UpdateFieldCode();
            }
        }

        private void UpdateFieldCode()
        {
            // يوجد رمز حقل الحقل في عقدة التشغيل بين عقدة بداية الحقل وفاصل الحقل.
            Run fieldCode = (Run) mFieldStart.NextSibling;
            fieldCode.Text = string.Format("HYPERLINK {0}\"{1}\"", ((mIsLocal) ? "\\l " : ""), mTarget);

            // إذا كان رمز الحقل يتكون من أكثر من تشغيل واحد، فاحذف هذه التشغيلات.
            RemoveSameParent(fieldCode.NextSibling, mFieldSeparator);
        }

         ///<summary>
         ///Goes through siblings starting from the start node until it finds a node of the specified type or null.
         ///</summary>
        private static Node FindNextSibling(Node startNode, NodeType nodeType)
        {
            for (Node node = startNode; node != null; node = node.NextSibling)
            {
                if (node.NodeType == nodeType)
                    return node;
            }

            return null;
        }

         ///<summary>
         ///Retrieves text from start up to but not including the end node.
         ///</summary>
        private static string GetTextSameParent(Node startNode, Node endNode)
        {
            if ((endNode != null) && (startNode.ParentNode != endNode.ParentNode))
                throw new ArgumentException("Start and end nodes are expected to have the same parent.");

            StringBuilder builder = new StringBuilder();
            for (Node child = startNode; !child.Equals(endNode); child = child.NextSibling)
                builder.Append(child.GetText());

            return builder.ToString();
        }

         ///<summary>
         ///Removes nodes from start up to but not including the end node.
         ///Assumes that the start and end nodes have the same parent.
         ///</summary>
        private static void RemoveSameParent(Node startNode, Node endNode)
        {
            if (endNode != null && startNode.ParentNode != endNode.ParentNode)
                throw new ArgumentException("Start and end nodes are expected to have the same parent.");

            Node curChild = startNode;
            while ((curChild != null) && (curChild != endNode))
            {
                Node nextChild = curChild.NextSibling;
                curChild.Remove();
                curChild = nextChild;
            }
        }

        private readonly Node mFieldStart;
        private readonly Node mFieldSeparator;
        private readonly Node mFieldEnd;
        private bool mIsLocal;
        private string mTarget;

        private static readonly Regex gRegex = new Regex(
            "\\S+" + // كلمة واحدة أو أكثر بدون مسافات HYPERLINK أو كلمة أخرى في لغات أخرى.
            "\\s+" + // مسافة واحدة أو أكثر.
            "(?:\"\"\\s+)?" + // اختياري غير قابل للالتقاط "" ومسافة واحدة أو أكثر.
            "(\\\\l\\s+)?" + // علامة اختيارية \l متبوعة بمسافة واحدة أو أكثر.
            "\"" +  //علامة اقتباس واحدة.
            "([^\"]+)" + // حرف واحد أو أكثر، باستثناء علامة الاقتباس العليا (هدف الارتباط التشعبي).
            "\"" //علامة ختامية واحدة.
        );
    }
}

أنظر أيضا