ทำงานกับเอกสาร

การทำงานกับเอกสาร

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` หยุดก่อนกำหนดหรือข้ามเนื้อหา	การแทนที่ `VisitStart` / `VisitEnd` คืนค่า `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 บน builder instance.

`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`	คลาสฐานแบบนามธรรมสำหรับการเดินผ่านทุกโหนดในโครงสร้างเอกสาร.
`ProtectionType`	Enum ของข้อจำกัดการแก้ไขระดับเอกสาร.
`FileFormatUtil.DetectFileFormat`	ตรวจจับรูปแบบของไฟล์หรือสตรีมก่อนทำการโหลด.

ดูเพิ่มเติม

Aspose.Words for .NET — Enterprise Documentation