Bekerja dengan Fields

Bekerja dengan Field

Sebuah field Word – DATE, IF, DATABASE, REF, dan puluhan lainnya – direpresentasikan dalam Aspose.Words FOSS untuk .NET oleh Field kelas dan subclass-nya, semuanya dalam Aspose.Words.Fields namespace. Halaman ini mencakup mesin field inti: Field model objek itu sendiri, bagaimana field dikumpulkan dan diperbarui, serta antarmuka callback yang memungkinkan Anda menyisipkan data dan perilaku khusus selama pembaruan field. Keluarga field tertentu – hyperlink dan referensi silang, field tanggal/waktu, field mail-merge, field indeks dan daftar isi – masing-masing memiliki halaman panduan pengembang khusus.


Model Objek Field

Setiap field dalam dokumen adalah instance Field yang terdiri dari tiga node penanda – FieldStart, Separator, dan FieldEnd – yang ditampilkan sebagai properti Field.Start, Field.Separator, dan Field.End. Field.Type mengidentifikasi FieldType apa yang direpresentasikan oleh field, Field.Result dan Field.DisplayResult menampilkan nilai yang terakhir dihitung, dan Field.Format menyimpan segala switch (seperti string format numerik atau tanggal-waktu) yang terlampir pada kode field. Field.IsLocked dan Field.IsDirty melaporkan status terkunci dan usang dari field. Panggil Field.GetFieldCode() untuk membaca teks kode field mentah, Field.Update() untuk menghitung ulang hasilnya, Field.Unlink() untuk mengganti field dengan teks statis, dan Field.Remove() untuk menghapusnya sepenuhnya.


Mengakses dan Memperbarui Field dalam Dokumen

Document.Range.Fields mengembalikan sebuah FieldCollection – field yang terdapat dalam rentang tersebut, dengan Count, Remove(), RemoveAt(), dan Clear() untuk penghapusan massal. Range.UpdateFields() menghitung ulang setiap field dalam rentang, Range.UnlinkFields() mengubah setiap field dalam rentang menjadi teks statis, dan Range.NormalizeFieldTypes() menyelaraskan kode tipe field yang disimpan dengan kode field sebenarnya setelah penyuntingan manual. DocumentBuilder.InsertField() menyisipkan field baru pada kursor, dengan overload yang memperbarui hasil field baru secara langsung atau membiarkannya untuk proses Range.UpdateFields() berikutnya.


Opsi Pembaruan Field dan Budaya

Document.FieldOptions adalah sebuah instance FieldOptions yang mengatur bagaimana semua bidang dokumen berperilaku saat diperbarui: CurrentUser menyediakan UserInformation yang digunakan oleh bidang identitas, DefaultDocumentAuthor menanamkan hasil terkait penulis, LegacyNumberFormat dan UseInvariantCultureNumberFormat mengontrol pemformatan angka, dan PreProcessCulture serta FieldUpdateCultureSource (dipasangkan dengan callback IFieldUpdateCultureProvider) menentukan budaya mana yang mengatur pemformatan tanggal dan angka selama pembaruan. TemplateName, FileName, dan BuiltInTemplatesPaths menyediakan nilai yang dibaca kembali oleh bidang yang sadar template dan nama file.


Melacak dan Menyesuaikan Pembaruan Bidang

Implement IFieldUpdatingCallback (FieldUpdating dan FieldUpdated) pada FieldOptions untuk menjalankan kode segera sebelum dan sesudah setiap bidang dihitung ulang – berguna untuk mengaudit bidang mana yang berubah dalam pekerjaan batch. Implement IFieldUpdatingProgressCallback (Notify) untuk melacak kemajuan keseluruhan pada dokumen besar; ia menerima sebuah FieldUpdatingProgressArgs dengan TotalFieldsCount, UpdatedFieldsCount, dan UpdateCompleted. Untuk mengubah cara hasil numerik atau umum sebuah bidang ditampilkan sebagai teks, implement IFieldResultFormatter (Format(value, format) dan FormatNumeric(value, format)) dan tetapkan ke FieldOptions.ResultFormatter.


Menyediakan Data Eksternal ke Bidang

Bidang DATABASE membaca barisnya melalui IFieldDatabaseProvider.GetQueryResult(), yang mengembalikan sebuah FieldDatabaseDataTable (ColumnNames, Rows) yang dibangun dari instance FieldDatabaseDataRow (Values) – tetapkan implementasi Anda ke FieldOptions.FieldDatabaseProvider. Bidang perbandingan seperti IF mengevaluasi kondisinya melalui IComparisonExpressionEvaluator.Evaluate(), yang menerima sebuah ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) dan mengembalikan sebuah ComparisonEvaluationResult (Result, ErrorMessage); tetapkan evaluator khusus ke FieldOptions.ComparisonExpressionEvaluator untuk mengganti logika perbandingan default. Bidang yang biasanya meminta masukan pengguna selama pembaruan – seperti ASK dan FILLIN – memanggil IFieldUserPromptRespondent.Respond() ketika satu ditetapkan ke FieldOptions.UserPromptRespondent, sehingga pembaruan tanpa pengawasan tidak terblokir menunggu masukan interaktif.


Identitas Pengguna dan Dokumen untuk Bidang

UserInformation (Name, Initials, Address, dan UserInformation.DefaultUser statis) menyediakan identitas yang dibaca oleh bidang yang terkait dengan nama penulis dan pengguna. Tetapkan sebuah instance ke Document.FieldOptions.CurrentUser sebelum memperbarui bidang yang bergantung pada penulis dokumen atau identitas pengguna.


Tips dan Praktik Terbaik

  • Aspose.Words FOSS tidak menghitung ulang field secara otomatis saat memuat atau menyimpan seperti Word – panggil Range.UpdateFields() (atau Field.Update() untuk satu field) secara eksplisit setelah setiap edit programatik yang harus tercermin dalam hasil field.
  • FieldStart, Separator, dan FieldEnd adalah node nyata dalam pohon dokumen; hapus sebuah field melalui Field.Remove() atau Field.Unlink() alih-alih menghapus node penanda secara langsung, atau struktur field dapat menjadi tidak konsisten.
  • Field yang hasilnya bergantung pada tata letak halaman – PAGE, NUMPAGES, dan entri nomor halaman TOC – dievaluasi menjadi placeholder 0, karena edisi ini tidak menyertakan mesin page-layout/rendering engine.
  • Daftarkan IFieldUpdatingCallback sebelum menjalankan Range.UpdateFields() pada dokumen yang besar atau tidak familiar jika Anda perlu mencatat atau mengaudit secara tepat field mana yang berubah.
  • Atur FieldOptions.UserPromptRespondent (atau berikan nilai DefaultResponse pada kelas field yang dipicu prompt secara individu) sebelum memperbarui dokumen dalam pipeline yang tidak diawasi, sehingga field ASK/FILLIN tidak terhenti menunggu input interaktif.

Masalah Umum

MasalahPenyebabPerbaikan
Hasil bidang tidak terbaru setelah mengedit dokumenAspose.Words FOSS tidak memperbarui bidang secara otomatis saat memuat atau menyimpanPanggil Range.UpdateFields() atau Field.Update() secara eksplisit
PAGE, NUMPAGES, atau nomor halaman TOC menunjukkan 0Tata letak/penyajian halaman tidak termasuk dalam edisi iniPerilaku yang diharapkan – gunakan versi komersial Aspose.Words untuk .NET jika Anda memerlukan nomor halaman yang dihitung
field DATABASE tidak menghasilkan barisTidak ada IFieldDatabaseProvider yang ditetapkan ke FieldOptions.FieldDatabaseProviderImplementasikan IFieldDatabaseProvider dan tetapkan sebelum memanggil Range.UpdateFields()
Pembaruan bidang batch tampaknya menggantungBidang yang dipicu prompt (ASK, FILLIN) tidak memiliki IFieldUserPromptRespondent yang ditetapkanTetapkan FieldOptions.UserPromptRespondent, atau atur DefaultResponse pada instance bidang

FAQ

Apakah Aspose.Words FOSS mengevaluasi setiap tipe field Word?

Model objek Field mewakili setiap nilai FieldType dan memperbarui sebagian besar di antaranya, tetapi bidang yang hasilnya bergantung pada tata letak halaman – seperti PAGE dan NUMPAGES – mengevaluasi menjadi placeholder 0 karena edisi ini tidak menyertakan mesin tata letak/rendering.

Bagaimana cara saya mengevaluasi ulang bidang setelah mengedit dokumen secara programatis?

Panggil Range.UpdateFields() pada rentang yang mencakup konten yang diedit, atau Document.Range.UpdateFields() untuk memperbarui setiap bidang dalam dokumen.

Apakah saya dapat mengonversi bidang menjadi teks biasa yang statis?

Ya – Field.Unlink() menggantikan bidang dengan hasil perhitungannya yang terakhir sebagai teks biasa, menghapus kode bidang yang mendasarinya.

Bagaimana cara saya menghapus bidang sepenuhnya, termasuk hasilnya?

Panggil Field.Remove(). Itu menghapus node FieldStart, Separator, dan FieldEnd bersama dengan kode bidang serta konten hasilnya.

Bagaimana cara saya menyediakan data khusus ke bidang DATABASE?

Implementasikan IFieldDatabaseProvider dan tetapkan ke Document.FieldOptions.FieldDatabaseProvider. Implementasi GetQueryResult() Anda mengembalikan FieldDatabaseDataTable yang dibangun dari instance FieldDatabaseDataRow.


API Reference Ringkasan

Kelas / AntarmukaDeskripsi
FieldKelas dasar untuk bidang Word; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionBidang-bidang dalam rentang, melalui Range.Fields; Count, Remove(), Clear()
FieldTypeEnum yang mengidentifikasi bidang Word mana yang diwakili oleh instance Field
FieldOptionsKonfigurasi pembaruan bidang di seluruh dokumen, melalui Document.FieldOptions
IFieldUpdatingCallbackHook FieldUpdating / FieldUpdated di sekitar setiap pembaruan bidang
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsPelaporan kemajuan selama pembaruan bidang massal
IFieldResultFormatterPemformatan khusus hasil perhitungan bidang
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowSumber data eksternal untuk bidang DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultEvaluasi khusus untuk ekspresi bidang bergaya perbandingan
IFieldUserPromptRespondentMenyediakan respons untuk bidang yang dipandu prompt dalam pembaruan tanpa pengawasan
IFieldUpdateCultureProvider / FieldUpdateCultureSourcePemilihan budaya selama pembaruan bidang
UserInformationIdentitas penulis/pengguna (Name, Initials, Address) dibaca oleh bidang identitas

Lihat Juga

 Bahasa Indonesia