Aspose.Words FOSS
.NET
מדריך למפתחים
עבודה עם מסמכים

עבודה עם מסמכים

עבודה עם מסמכים

Aspose.Words FOSS for .NET מייצג כל קובץ Word כמודל אובייקטים בזיכרון שמושרש במחלקה Document, כאשר DocumentBuilder מספק API ברמה גבוהה, מבוסס-סמן, לכתיבת תוכן. מדריך זה מכסה יצירת וטעינת מסמכים, כתיבה עם DocumentBuilder, מבנה הסעיף/גוף, ניווט בעץ הצמתים, שילוב מסמכים והגנה עליהם.

יצירת וטעינת מסמכים

צור מסמך ריק עם new Document(), או פתח קובץ קיים על-ידי העברת נתיב או Stream ל-Document(fileName) או ל-Document(stream) בקונסטרוקטור. גרסאות עומס שמקבלות ארגומנט LoadOptions מאפשרות לך לשלוט בהתנהגות הטעינה, כגון אספקת סיסמה לקובץ מוצפן.

לפני טעינת קובץ ממקור לא ידוע או לא מהימן, FileFormatUtil.DetectFileFormat(fileName) (או גרסת העומס Stream) מחזיר FileFormatInfo המתאר את ה-LoadFormat שהתגלה, והאם הקובץ IsEncrypted, HasDigitalSignature או HasMacros.

כתיבה עם DocumentBuilder

DocumentBuilder עוטף Document ומחשוף סמן שאתה מזיז דרך המסמך תוך הוספת תוכן. Write(text) ו-Writeln(text) מוסיפים טקסט בסמן; InsertParagraph() מתחיל פסקה חדשה. תכונות העיצוב בבונה — Font, ParagraphFormat, ListFormat, PageSetup — חלות על כל מה שייכתב לאחר מכן.

הזז את הסמן עם MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), או MoveToParagraph(paragraphIndex, characterIndex). המאפיינים CurrentNode, CurrentParagraph ו-CurrentSection של הבונה מדווחים על המיקום הנוכחי שלו בעץ.

מבנה המסמך: מקטעים וגוף

Document מחזיק SectionCollection (Document.Sections, בנוסף FirstSection / LastSection); כל Section כולל Body אחד, אוסף ראשי/תחתונים אופציונלי, ואת PageSetup שלו. Section.AppendContent(sourceSection) ו-PrependContent(sourceSection) מעתיקים תוכן בין מקטעים, ו-ClearContent() מאפס מקטע מבלי להסירו מהמסמך.

בתוך Body, התוכן נחשף דרך Body.Paragraphs (‏ParagraphCollection) ו-Body.Tables. Range — זמין מ-Document, Section, Paragraph ומצמתים אחרים — מייצג אזור רציף בעץ; Range.Text קורא את הטקסט הפשוט שלו ו-Range.Replace(pattern, replacement) מבצע חיפוש והחלפה רק על אותו אזור.

ההליכה בעץ הצמתים עם DocumentVisitor

כל חלק של מסמך — מקטעים, פסקאות, רצפים, טבלאות, שדות, צורות, תגובות, הערות שוליים — הוא Node בעץ מורכב שמשורש ב-Document. כדי לעבד כל צומת מסוג מסוים ללא רקורסיה ידנית, יש ליצור מחלקה יורשת מ-DocumentVisitor המופשטת ולדרוס את קריאות המשוב Visit*Start/Visit*End הדרושות, כגון VisitParagraphStart(paragraph) או VisitRun(run), ואז לקרוא ל-document.Accept(visitor). כל קריאת משוב יכולה להחזיר VisitorAction (Continue, SkipThisNode או Stop) כדי לשלוט באופן שבו ההליכה מתבצעת.

שיבוט, ייבוא והוספת תוכן

Document.Clone() מייצר העתק עמוק של מסמך שלם. כדי להעביר תוכן בין שני מופעים שונים של Document, יש לקרוא ל-ImportNode(srcNode, isImportChildren) על מסמך היעד כדי להביא צומת מעץ זר, או לקרוא ל-Document.AppendDocument(srcDoc, importFormatMode) כדי להצמיד את המקטעים של מסמך אחד לאחר באמצעות ImportFormatMode שנבחר — KeepSourceFormatting, UseDestinationStyles או KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) מוסיף את תוכן מסמך המקור במיקום הסמן של הבונה במקום בסוף היעד.

הגנת מסמכים

Document.Protect(type, password) מגביל עריכה על פי ערך ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields או NoProtection להסרת ההגנה. Unprotect() (עם או בלי סיסמה) מבטל זאת. זהו מגבלת עריכה שמיישמת Word, נפרדת מהצפנת הסיסמה של OOXML ש-OoxmlSaveOptions.Password מיישמת בעת שמירת קובץ.

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

  • העדף את DocumentBuilder לבניית תוכן חדש; עבור למניפולציה ישירה של צמתים (AppendChild, InsertAfter, Clone) כאשר אתה צריך שליטה מדויקת על עץ קיים.
  • קרא ל-FileFormatUtil.DetectFileFormat לפני טעינת קובץ ממקור לא מהימן או שסופק על ידי משתמש כדי שתוכל לבדוק את LoadFormat ולדחות קלט לא נתמך או מוצפן מוקדם.
  • בעת שילוב מסמכים עם AppendDocument או InsertDocument, בחר את ה-ImportFormatMode במודע — KeepSourceFormatting משמר את המראה של המקור, UseDestinationStyles תואם את ערכת הסגנון של מסמך היעד.
  • השתמש במחלקה תת-סוג DocumentVisitor במקום הליכה רקורסיבית ידנית בעץ כאשר אתה צריך לעבד כל מופע של סוג צומת באופן עקבי.
  • Document.Protect היא מגבלת עריכה, לא הצפנה — צמד אותה עם OoxmlSaveOptions.Password אם הקובץ השמור עצמו צריך לדרוש סיסמה לפתיחה.

בעיות נפוצות

בעיהסיבהפתרון
Document(fileName) זורק שגיאה עבור קובץ שפתיחה ב-Word תקינהפורמט הקובץ אינו נתמך בגרסה זו לטעינהקרא ל-FileFormatUtil.DetectFileFormat קודם ובדוק את ה-LoadFormat המוחזר לפני הטעינה
תוכן מצורף מקבל את הגופנים או הסגנונות השגוייםImportFormatMode אי-התאמה בין קבוצות הסגנון של המקור והיעדהעבר את KeepSourceFormatting או את UseDestinationStyles במפורש במקום להסתמך על ברירת מחדל
המעבר של DocumentVisitor נעצר מוקדם או מדלג על תוכןהחלפה של Visit*Start / Visit*End מחזירה SkipThisNode או Stop בטעותהחזר VisitorAction.Continue מכל החלפה אלא אם אתה מתכוון במפורש לדלג או לעצור
Unprotect() אינו משפיעהמסמך לא היה מוגן בסיסמה, או שסופקה סיסמה שגויהקרא ל-Unprotect() ללא ארגומנטים אם Protect קרא ללא סיסמה, אחרת העבר את הסיסמה המתאימה

FAQ

מה ההבדל בין Document.Clone() ל-ImportNode?

Clone() מעתיק מסמך שלם למופע חדש של Document. ImportNode(srcNode, isImportChildren) מעביר צומת יחיד (ואפשרות לילדים שלו) מעץ של מסמך אחד לאחר, וזה מה שאתה משתמש בו כאשר משלב תוכן ספציפי במקום מסמכים שלמים.

אילו פורמטי קבצים Document(fileName) יכול לטעון?

Document(fileName) טוען DOCX, DOCM, DOTX, DOTM, Flat OPC (כולל גרסאות עם מקרו ותבניות), Markdown, וטקסט פשוט. פורמטים ישנים של עיבוד תמלילים ואינטרנט אינם נכללים במטעינים של גרסה זו.

איך אני מוצא היכן DocumentBuilder ממוקם כרגע?

קרא את CurrentNode, CurrentParagraph או CurrentSection במופע הבונה.

האם Document.Protect מצפין את הקובץ השמור?

לא — זו מגבלת עריכה שמבוצעת על-ידי Word כאשר הקובץ נפתח. כדי לדרוש סיסמה רק לפתיחת הקובץ, הגדר OoxmlSaveOptions.Password בעת השמירה.

איך אני קורא רק את הפסקאות בגוף המסמך?

השתמש באוסף Body.Paragraphs, או ב-Body.GetChildNodes(nodeType, isDeep) לסוגי צמתים אחרים.

API Reference סיכום

מחלקה/מתודהתיאור
Documentשורש של מודל עצם המסמך; הבונים טוענים מקובץ או זרם, או יוצרים מסמך ריק.
Document.Saveכותב את המסמך לקובץ, לזרם, או לתשובת HTTP בפורמט נבחר.
Document.Clone()מייצר העתק עמוק של כל המסמך.
Document.Protect(type, password) / Unprotect()מיישם או מסיר מגבלת עריכה.
Document.AppendDocument(srcDoc, importFormatMode)מוסיף את החלקים של מסמך אחר למסמך זה.
DocumentBuilderמבוסס-סמן API לכתיבת טקסט והכנסת תוכן למסמך.
DocumentBuilder.InsertDocument(srcDoc, importFormatMode)מכניס את תוכן מסמך המקור במיקום הסמן.
Section / SectionCollectionחלק יחיד של מסמך, והאוסף של כל החלקים.
Bodyמכולה לטקסט הראשי (פסקאות וטבלאות) של קטע.
Rangeאזור רציף של עץ המסמך; תומך ב-Text וב-Replace.
DocumentVisitorמחלקה בסיסית מופשטת לסיור בכל צומת בעץ המסמך.
ProtectionTypeEnum של מגבלות עריכה ברמת המסמך.
FileFormatUtil.DetectFileFormatמזהה את הפורמט של קובץ או זרם לפני טעינתו.

ראה גם

 עברית