การทำงานกับฟิลด์
ภาพรวม
ฟิลด์ Word – DATE, IF, DATABASE, REF, และหลายสิบรายการอื่น – แสดงใน Aspose.Words FOSS สำหรับ .NET โดย Field คลาสและคลาสย่อยของมัน, ทั้งหมดใน Aspose.Words.Fields เนมสเปซ. หน้านี้ครอบคลุมเครื่องยนต์ฟิลด์หลัก: ของ Field โมเดลวัตถุเอง, วิธีที่ฟิลด์ถูกรวบรวมและอัปเดต, และอินเทอร์เฟซ callback ที่ให้คุณแทรกข้อมูลและพฤติกรรมที่กำหนดเองระหว่างการอัปเดตฟิลด์. กลุ่มฟิลด์เฉพาะ – ไฮเปอร์ลิงก์และการอ้างอิงข้าม, ฟิลด์วัน/เวลา, ฟิลด์เมล-เมิร์จ, ดัชนีและสารบัญ – แต่ละมีหน้าแนะนำนักพัฒนาที่อุทิศเฉพาะ.
โมเดลวัตถุฟิลด์
ทุกฟิลด์ในเอกสารเป็นอินสแตนซ์ Field ที่ประกอบด้วยโหนดเครื่องหมายสามตัว – FieldStart, Separator และ FieldEnd – ซึ่งเปิดให้เข้าถึงเป็นคุณสมบัติ Field.Start, Field.Separator และ Field.End. Field.Type ระบุว่า FieldType ใดที่ฟิลด์แสดง, Field.Result และ Field.DisplayResult เปิดเผยค่าที่คำนวณล่าสุด, และ Field.Format เก็บสวิตช์ใด ๆ (เช่น สตริงรูปแบบตัวเลขหรือวันที่-เวลา) ที่แนบกับโค้ดฟิลด์. Field.IsLocked และ Field.IsDirty รายงานสถานะล็อคและล้าสมัยของฟิลด์. เรียก Field.GetFieldCode() เพื่ออ่านข้อความโค้ดฟิลด์ดิบ, Field.Update() เพื่อคำนวณผลใหม่, Field.Unlink() เพื่อแทนที่ฟิลด์ด้วยข้อความคงที่, และ Field.Remove() เพื่อลบออกอย่างสมบูรณ์.
การเข้าถึงและอัปเดตฟิลด์ในเอกสาร
Document.Range.Fields คืนค่า FieldCollection – ฟิลด์ที่อยู่ในช่วงนั้น, พร้อมกับ Count, Remove(), RemoveAt() และ Clear() สำหรับการลบเป็นกลุ่ม. Range.UpdateFields() คำนวณใหม่ทุกฟิลด์ในช่วง, Range.UnlinkFields() แปลงทุกฟิลด์ในช่วงเป็นข้อความคงที่, และ Range.NormalizeFieldTypes() ตรวจสอบความสอดคล้องของรหัสประเภทฟิลด์ที่เก็บไว้กับโค้ดฟิลด์จริงหลังจากแก้ไขด้วยมือ. DocumentBuilder.InsertField() แทรกฟิลด์ใหม่ที่เคอร์เซอร์, พร้อม overload ที่หรือจะอัปเดตผลของฟิลด์ใหม่ทันทีหรือปล่อยไว้สำหรับการผ่าน Range.UpdateFields() ในภายหลัง.
ตัวเลือกการอัปเดตฟิลด์และวัฒนธรรม
Document.FieldOptions เป็นอินสแตนซ์ FieldOptions ที่กำหนดพฤติกรรมของฟิลด์ทั้งหมดในเอกสารเมื่อมีการอัปเดต: CurrentUser จัดหา UserInformation ที่ใช้โดยฟิลด์อัตลักษณ์, DefaultDocumentAuthor เป็นเมล็ดสำหรับผลลัพธ์ที่เกี่ยวกับผู้เขียน, LegacyNumberFormat และ UseInvariantCultureNumberFormat ควบคุมรูปแบบตัวเลข, และ PreProcessCulture กับ FieldUpdateCultureSource (ร่วมกับคอลแบ็ก IFieldUpdateCultureProvider) กำหนดว่าภูมิภาคใดจะควบคุมการจัดรูปแบบวันที่และตัวเลขระหว่างการอัปเดต. TemplateName, FileName, และ BuiltInTemplatesPaths จัดหาค่าที่ฟิลด์ที่ตระหนักถึงเทมเพลตและชื่อไฟล์จะอ่านกลับ.
การติดตามและปรับแต่งการอัปเดตฟิลด์
ดำเนินการ IFieldUpdatingCallback (FieldUpdating และ FieldUpdated) บน FieldOptions เพื่อเรียกโค้ดทันทีก่อนและหลังที่ฟิลด์แต่ละอันทำการคำนวณใหม่ – มีประโยชน์สำหรับการตรวจสอบว่าฟิลด์ใดเปลี่ยนแปลงในงานแบตช์. ดำเนินการ IFieldUpdatingProgressCallback (Notify) เพื่อติดตามความคืบหน้าโดยรวมของเอกสารขนาดใหญ่; มันรับ FieldUpdatingProgressArgs ที่มี TotalFieldsCount, UpdatedFieldsCount, และ UpdateCompleted. เพื่อเปลี่ยนวิธีที่ผลลัพธ์เชิงตัวเลขหรือทั่วไปของฟิลด์แสดงเป็นข้อความ, ดำเนินการ IFieldResultFormatter (Format(value, format) และ FormatNumeric(value, format)) และกำหนดให้กับ FieldOptions.ResultFormatter.
การจัดหาข้อมูลภายนอกให้กับฟิลด์
ฟิลด์ DATABASE อ่านแถวของมันผ่าน IFieldDatabaseProvider.GetQueryResult(), ซึ่งส่งคืน FieldDatabaseDataTable (ColumnNames, Rows) ที่สร้างจากอินสแตนซ์ FieldDatabaseDataRow (Values) – กำหนดการดำเนินการของคุณให้กับ FieldOptions.FieldDatabaseProvider. ฟิลด์เปรียบเทียบเช่น IF ประเมินเงื่อนไขของพวกมันผ่าน IComparisonExpressionEvaluator.Evaluate(), ซึ่งรับ ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) และส่งคืน ComparisonEvaluationResult (Result, ErrorMessage); กำหนดตัวประเมินแบบกำหนดเองให้กับ FieldOptions.ComparisonExpressionEvaluator เพื่อแทนที่ตรรกะการเปรียบเทียบเริ่มต้น. ฟิลด์ที่โดยปกติจะเรียกผู้ใช้ให้ป้อนข้อมูลระหว่างการอัปเดต – เช่น ASK และ FILLIN – จะเรียก IFieldUserPromptRespondent.Respond() เมื่อมีการกำหนดค่าให้กับ FieldOptions.UserPromptRespondent, เพื่อให้การอัปเดตแบบไม่มีผู้ใช้ไม่บล็อกรอการป้อนข้อมูลแบบโต้ตอบ.
อัตลักษณ์ผู้ใช้และเอกสารสำหรับฟิลด์
UserInformation (Name, Initials, Address และ UserInformation.DefaultUser แบบคงที่) จัดหาอัตลักษณ์ที่ฟิลด์ที่เกี่ยวกับชื่อผู้เขียนและชื่อผู้ใช้จะอ่านจาก. กำหนดอินสแตนซ์ให้กับ Document.FieldOptions.CurrentUser ก่อนทำการอัปเดตฟิลด์ที่ขึ้นกับผู้เขียนเอกสารหรืออัตลักษณ์ผู้ใช้.
เคล็ดลับและแนวทางปฏิบัติที่ดีที่สุด
- Aspose.Words FOSS ไม่ทำการคำนวณฟิลด์ใหม่โดยอัตโนมัติเมื่อโหลดหรือบันทึกแบบที่ Word ทำ – เรียก
Range.UpdateFields()(หรือField.Update()สำหรับฟิลด์เดียว) อย่างชัดเจนหลังการแก้ไขเชิงโปรแกรมใด ๆ ที่ควรสะท้อนในผลลัพธ์ของฟิลด์. FieldStart,SeparatorและFieldEndเป็นโหนดจริงในต้นไม้ของเอกสาร; ให้ลบฟิลด์ผ่านField.Remove()หรือField.Unlink()แทนการลบโหนดเครื่องหมายโดยตรง, มิฉะนั้นโครงสร้างฟิลด์อาจกลายเป็นไม่สอดคล้องกัน.- ฟิลด์ที่ผลลัพธ์ขึ้นอยู่กับการจัดหน้า –
PAGE,NUMPAGESและ TOC page-number entries – จะประเมินเป็นตัวแทน0เนื่องจากฉบับนี้ไม่ได้รวมเอาเอนจินการจัดหน้า/การเรนเดอร์. - ลงทะเบียน
IFieldUpdatingCallbackก่อนรันRange.UpdateFields()กับเอกสารขนาดใหญ่หรือที่ไม่คุ้นเคย หากคุณต้องการบันทึกหรือตรวจสอบอย่างแม่นยำว่าฟิลด์ใดถูกเปลี่ยน. - ตั้งค่า
FieldOptions.UserPromptRespondent(หรือให้ค่าของDefaultResponseในคลาสฟิลด์ที่ขับเคลื่อนด้วยการแจ้งเตือนแต่ละตัว) ก่อนอัปเดตเอกสารใน pipeline ที่ไม่มีผู้ดูแล, เพื่อให้ฟิลด์ASK/FILLINไม่หยุดค้างรออินพุตแบบโต้ตอบ.
ปัญหาทั่วไป
| ปัญหา | สาเหตุ | แก้ไข |
|---|---|---|
| ผลลัพธ์ของฟิลด์ล้าสมัยหลังจากแก้ไขเอกสาร | Aspose.Words FOSS ไม่ได้อัปเดตฟิลด์อัตโนมัติเมื่อโหลดหรือบันทึก | เรียก Range.UpdateFields() หรือ Field.Update() อย่างชัดเจน |
PAGE, NUMPAGES, หรือหมายเลขหน้าของ TOC แสดง 0 | การจัดหน้า/การเรนเดอร์ไม่ได้เป็นส่วนหนึ่งของฉบับนี้ | พฤติกรรมที่คาดหวัง – ใช้รุ่นเชิงพาณิชย์ Aspose.Words สำหรับ .NET หากคุณต้องการหมายเลขหน้าที่คำนวณ |
ฟิลด์ DATABASE ไม่สร้างแถวใด | ไม่มี IFieldDatabaseProvider ถูกกำหนดให้กับ FieldOptions.FieldDatabaseProvider | ดำเนินการ IFieldDatabaseProvider และกำหนดค่าให้ก่อนเรียก Range.UpdateFields() |
| การอัปเดตฟิลด์แบบแบตช์ดูเหมือนค้าง | ฟิลด์ที่ขับเคลื่อนด้วยพรอมต์ (ASK, FILLIN) ไม่มี IFieldUserPromptRespondent ถูกกำหนด | กำหนด FieldOptions.UserPromptRespondent หรือกำหนด DefaultResponse บนอินสแตนซ์ของฟิลด์ |
FAQ
FOSS Aspose.Words ประเมินทุกประเภทฟิลด์ของ Word หรือไม่?
โมเดลวัตถุ Field แสดงค่าทุกค่า FieldType และอัปเดตส่วนใหญ่ของมัน แต่ฟิลด์ที่ผลลัพธ์ขึ้นอยู่กับการจัดหน้า – เช่น PAGE และ NUMPAGES – จะประเมินเป็น 0 เนื่องจากรุ่นนี้ไม่ได้รวมเอาเอนจินการจัดหน้า/การเรนเดอร์.
ฉันจะประเมินฟิลด์ใหม่หลังจากแก้ไขเอกสารแบบโปรแกรมได้อย่างไร?
เรียก Range.UpdateFields() บนช่วงที่ครอบคลุมเนื้อหาที่แก้ไข หรือ Document.Range.UpdateFields() เพื่ออัปเดตทุกฟิลด์ในเอกสาร.
ฉันสามารถแปลงฟิลด์เป็นข้อความธรรมดาแบบคงที่ได้หรือไม่?
ใช่ – Field.Unlink() จะทดแทนฟิลด์ด้วยผลลัพธ์ที่คำนวณล่าสุดเป็นข้อความธรรมดา โดยลบโค้ดฟิลด์พื้นฐานออก.
ฉันจะลบฟิลด์ออกอย่างสมบูรณ์ รวมถึงผลลัพธ์ของมันได้อย่างไร?
เรียก Field.Remove(). มันจะลบโหนด FieldStart, Separator และ FieldEnd พร้อมกับโค้ดและเนื้อหาผลลัพธ์ของฟิลด์.
ฉันจะส่งข้อมูลที่กำหนดเองไปยังฟิลด์ DATABASE ได้อย่างไร?
ดำเนินการ IFieldDatabaseProvider และกำหนดให้กับ Document.FieldOptions.FieldDatabaseProvider. การดำเนินการ GetQueryResult() ของคุณจะคืนค่า FieldDatabaseDataTable ที่สร้างจากอินสแตนซ์ FieldDatabaseDataRow.
API Reference สรุป
| คลาส / อินเทอร์เฟซ | คำอธิบาย |
|---|---|
Field | คลาสพื้นฐานสำหรับฟิลด์ Word; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | ฟิลด์ในช่วงหนึ่ง ผ่าน Range.Fields; Count, Remove(), Clear() |
FieldType | Enum ที่ระบุว่าฟิลด์ Word ใดที่อินสแตนซ์ Field แทน |
FieldOptions | การกำหนดค่าการอัปเดตฟิลด์ทั่วทั้งเอกสาร ผ่าน Document.FieldOptions |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated hooks รอบการอัปเดตแต่ละฟิลด์ |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | การรายงานความคืบหน้าในการอัปเดตฟิลด์แบบกลุ่ม |
IFieldResultFormatter | การจัดรูปแบบแบบกำหนดเองของผลลัพธ์ที่คำนวณของฟิลด์ |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | แหล่งข้อมูลภายนอกสำหรับฟิลด์ DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | การประเมินแบบกำหนดเองของนิพจน์ฟิลด์แบบเปรียบเทียบ |
IFieldUserPromptRespondent | จัดหาคำตอบสำหรับฟิลด์ที่ขอข้อมูลแบบ prompt ในการอัปเดตอัตโนมัติ |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | การเลือก Culture ระหว่างการอัปเดตฟิลด์ |
UserInformation | อัตลักษณ์ของผู้เขียน/ผู้ใช้ (Name, Initials, Address) ที่อ่านโดยฟิลด์อัตลักษณ์ |