การทำงานกับฟิลด์

ภาพรวม

ฟิลด์ 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()
FieldTypeEnum ที่ระบุว่าฟิลด์ Word ใดที่อินสแตนซ์ Field แทน
FieldOptionsการกำหนดค่าการอัปเดตฟิลด์ทั่วทั้งเอกสาร ผ่าน Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated hooks รอบการอัปเดตแต่ละฟิลด์
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsการรายงานความคืบหน้าในการอัปเดตฟิลด์แบบกลุ่ม
IFieldResultFormatterการจัดรูปแบบแบบกำหนดเองของผลลัพธ์ที่คำนวณของฟิลด์
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowแหล่งข้อมูลภายนอกสำหรับฟิลด์ DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultการประเมินแบบกำหนดเองของนิพจน์ฟิลด์แบบเปรียบเทียบ
IFieldUserPromptRespondentจัดหาคำตอบสำหรับฟิลด์ที่ขอข้อมูลแบบ prompt ในการอัปเดตอัตโนมัติ
IFieldUpdateCultureProvider / FieldUpdateCultureSourceการเลือก Culture ระหว่างการอัปเดตฟิลด์
UserInformationอัตลักษณ์ของผู้เขียน/ผู้ใช้ (Name, Initials, Address) ที่อ่านโดยฟิลด์อัตลักษณ์

ดูเพิ่มเติม

 ภาษาไทย