עבודה עם סימון מותאם אישית של XML

עבודה עם סימון מותאם אישית XML

מדריך זה מראה כיצד לקרוא ולנהל את נתוני ה-XML המותאמים אישית שמסמך Word יכול לשאת לצד התוכן הנראה שלו — נתונים המשמשים לקישור בקרי תוכן, לאחסון מטא-נתונים ספציפיים ליישום, או לשילוב חלקים ארגזיים שרירותיים. Document.CustomXmlParts חושף נתוני XML מותאמים אישית ברמת המסמך, ו-Document.PackageCustomParts חושף חלקים מותאמים אישית ברמת החבילה שאינם XML מותאמים במיוחד.

חלקי XML מותאמים אישית

CustomXmlPart מייצג אי-האי של נתוני XML מותאם אישית המחובר למסמך — אותו מנגנון שבו Word משתמש לתמיכה בבקרי תוכן ממופים XML. לכל חלק יש Id, מערך בתים Data שמחזיק את ה-XML הגולמי, DataChecksum, ו-תכונת Schemas (‏CustomXmlSchemaCollection) שמפרטת את סכמות ה-XML המשוייכות אליו. Document.CustomXmlParts מחזיר CustomXmlPartCollection: Add(part) מצרף CustomXmlPart קיים, Add(id, xml) יוצר אחד ישירות ממזהה ומחרוזת XML, GetById(id) מאחזר חלק ספציפי, ו-RemoveAt(index)/Clear() מסירים חלקים. גם CustomXmlPart וגם CustomXmlPartCollection חושפים Clone() לשכפול נתוני XML מותאמים אישית, לדוגמה בעת העתקת תוכן בין מסמכים.

סכמות XML מותאמות אישית

CustomXmlSchemaCollection, המגיע דרך CustomXmlPart.Schemas, מציג את כתובות ה-URI של הסכמות המשוייכות לחלק XML מותאם אישית. הוא תומך ב-Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() ו-Clone(), לצד תכונת Count — כתובות URI של הסכמות מתועדות כמחרוזות פשוטות במקום כאובייקטים של סכמות מפורשות.

מאפייני XML מותאמים אישית

באופן נפרד מ-CustomXmlPart, CustomXmlProperty מייצג תכונה יחידה של שם/ערך XML, שנבנית עם CustomXmlProperty(name, uri, value) ומחשיפה את Name, Uri ו-Value. CustomXmlPropertyCollection מנהל קבוצה של כאלה: Add(property) מוסיף אחד, המפתח (למשל properties["MyProp"]) מחפש אחד לפי שם ו-Contains(name) בודק אם הוא קיים, IndexOfKey(name) מחזיר את המיקום שלו, ו-Remove(name)/RemoveAt(index)/Clear() מסירים ערכים. SmartTag.Properties מחזיר CustomXmlPropertyCollection, שהיא הדרך שבה הנתונים המובנים של תג חכם מדור קודם מיוצגים (ראו למטה).

חלקים מותאמים ברמת החבילה

Document.PackageCustomParts מחזיר CustomPartCollection של עצמים CustomPart — חלקים שרירותיים שנשמרים בחבילת OOXML שאינם נתוני XML מותאמים, כגון חלקים שנוספו על ידי יישומים אחרים שנגעו בקובץ. לכל CustomPart יש Name, ContentType, RelationshipType, מערך בתים Data, וסמן IsExternal המציין האם החלק הוא הפניה חיצונית במקום תוכן משובץ. האוסף תומך ב-Add(part), RemoveAt(index), Clear() ו-Clone(), לצד Count.

תגי חכם מדור קודם

SmartTag הוא סוג צומת (NodeType.SmartTag) המייצג תג חכם של Word מדור קודם המקיף טקסט מזוהה. SmartTag נבנה עם SmartTag(doc), ומחשוף את Element (שם אלמנט המזוהה) ואת Uri (מרחב השם של המזוהה), לצד Properties — CustomXmlPropertyCollection המכיל את הנתונים המובנים שהמזוהה צירף לטקסט המסומן. מכיוון ש-SmartTag הוא צומת, הוא גם משתתף בעץ המסמך כמו צמתים אחרים, ותומך ב-Accept(visitor), AcceptStart(visitor) ו-AcceptEnd(visitor) לניווט מבוסס DocumentVisitor.

MarkupLevel

MarkupLevel הוא enum — Unknown, Inline, Block, Row, Cell — המתאר את רמת המבנה בעץ המסמך שבה יכול להופיע אלמנט סימון כגון תג מסמך מובנה.

טיפים ושיטות מומלצות

• השתמש ב-CustomXmlPartCollection.GetById(id) במקום לעבור על האוסף ידנית כאשר אתה יודע את המזהה של החלק שאתה צריך.
• קרא CustomXmlPart.DataChecksum כדי לגלות האם הנתונים XML הבסיסיים השתנו ללא צורך בביצוע השוואת בתים מלאה.
• הבחין בין Document.CustomXmlParts (נתוני XML מותאמים, לעיתים קשורים לבקרי תוכן) לבין Document.PackageCustomParts (חלקי חבילה שרירותיים שאינם XML) — הם משמשים למטרות שונות ונשמרים בנפרד.
• בעת עבודה עם מסמכים ישנים שמשתמשים בתגיות חכמות, בדוק את SmartTag.Element ו-Uri יחד כדי לזהות איזה מזוהה יצר את התג לפני שאתה נשען על ה-Properties שלו.
• שכפל חלקי XML מותאמים עם CustomXmlPart.Clone() (או עם Clone() של האוסף) בעת העתקת נתונים בין מסמכים במקום לקרוא מחדש ולהוסיף את ה-XML הגולמי.

בעיות נפוצות

FAQ

מה ההבדל בין CustomXmlPart ל-CustomXmlProperty?

CustomXmlPart הוא אי נתונים שלם של XML (עם מטען של מערך בתים וסקימות משויכות), שנגיש דרך Document.CustomXmlParts. CustomXmlProperty הוא זוג שם/ערך יחיד, שבדרך כלל נגיש דרך SmartTag.Properties ולא ישירות מהמסמך.

איך אני מוסיף נתוני XML מותאמים למסמך?

קרא ל-Document.CustomXmlParts.Add(id, xml) עם מחרוזת מזהה ותוכן ה-XML, או בנה CustomXmlPart בנפרד והעבר אותה ל-Add(part).

מה הם חלקים מותאמים של החבילה, וכיצד הם שונים מחלקים מותאמים של XML?

Document.PackageCustomParts (‏CustomPartCollection של עצמים CustomPart) מכיל חלקי חבילה של OOXML שרירותיים שאינם XML מותאמים — כל אחד עם ContentType, RelationshipType, ו-Data גולמי. Document.CustomXmlParts מיועד במיוחד לאיי נתונים של XML מותאמים.

מהו SmartTag?

SmartTag הוא תכונה ישנה של Word המייצגת טקסט שזוהה והוצמד על ידי מזוהה תג חכם. זהו צומת מסמך (NodeType.SmartTag) עם Element ו-Uri המזהים את המזהה, וכן אוסף Properties של ערכי CustomXmlProperty שהמזהה צירף.

איך אני מעתיק נתוני XML מותאמים בין מסמכים?

השתמש בCustomXmlPart.Clone() בחלק המקור, ואז הוסף את השכפול לDocument.CustomXmlParts של מסמך היעד עם Add(part).

API Reference סיכום

ראה גם

• Aspose.Words for .NET — Enterprise Documentation