Bekerja dengan Daftar
Gambaran Umum
Panduan ini menunjukkan cara daftar bernomor dan berpoin direpresentasikan dan dikendalikan dalam Aspose.Words FOSS untuk .NET. Sebuah List adalah definisi daftar yang dapat digunakan kembali dan dibagikan oleh setiap paragraf yang menggunakannya, ListFormat adalah cara sebuah paragraf individu merujuk ke sebuah daftar dan levelnya saat ini, dan ListLevel menyimpan format penomoran atau peluru sebenarnya untuk satu level daftar.
Objek Daftar dan ListCollection
List mewakili satu definisi daftar — aturan penomoran yang dapat diterapkan dokumen ke banyak paragraf. List.ListId mengidentifikasinya, List.IsMultiLevel melaporkan apakah ia mendefinisikan lebih dari satu level, dan List.ListLevels mengembalikan sebuah ListLevelCollection yang memuat satu ListLevel per level yang didefinisikan daftar. List.IsListStyleDefinition dan IsListStyleReference membedakan daftar yang mendefinisikan formatnya sendiri dari yang merujuk format melalui Style yang ditautkan (tersedia melalui List.Style). Semua daftar dalam dokumen dapat diakses melalui Document.Lists, yang mengembalikan sebuah ListCollection: ListCollection.Add(listTemplate) membuat daftar baru dari salah satu format ListTemplate yang telah ditentukan Word, Add(listStyle) membuat satu dari Style, AddSingleLevelList(listTemplate) membuat varian satu level, dan AddCopy(srcList) menduplikasi daftar yang ada — berguna ketika Anda ingin paragraf memiliki penomoran independen (restart baru) alih-alih berbagi penghitung yang sama. ListCollection.GetListByListId(listId) mengambil daftar tertentu, dan Count melaporkan berapa banyak daftar yang dimiliki dokumen.
Menerapkan Daftar ke Paragraf dengan ListFormat
ListFormat, yang diakses dari format paragraf, mengontrol daftar mana yang menjadi milik paragraf dan pada level apa. ListFormat.List adalah List yang digunakan paragraf, dan ListFormat.ListLevelNumber adalah level berbasis nol dalam daftar tersebut; IsListItem melaporkan apakah paragraf termasuk dalam daftar sama sekali. ApplyBulletDefault() dan ApplyNumberDefault() menerapkan format daftar peluru atau bernomor default Word ke sebuah paragraf dalam satu panggilan, RemoveNumbers() menghapus format daftar, dan ListIndent()/ListOutdent() memindahkan paragraf lebih dalam atau lebih dangkal dari level daftar — operasi yang sama yang dilakukan Word ketika menekan Tab atau Shift+Tab di awal paragraf daftar.
Level Daftar dan Gaya Penomoran
ListLevel menyimpan pemformatan untuk satu tingkat daftar: NumberStyle (nilai enum NumberStyle seperti angka Arab atau angka Romawi), NumberFormat (string format yang menggabungkan angka dengan teks literal, seperti titik atau kurung), StartAt (nomor awal), dan RestartAfterLevel (tingkat yang lebih tinggi mana yang meningkatkan dan memulai ulang penghitung tingkat ini). Alignment (nilai ListLevelAlignment: Left, Center, Right) dan TrailingCharacter (nilai ListTrailingCharacter: Tab, Space, Nothing) mengontrol bagaimana label diposisikan dan dipisahkan dari teks paragraf, bersama TabPosition, NumberPosition, dan TextPosition untuk tata letak yang tepat. IsLegal memaksa penomoran gaya hukum (selalu Arab, terlepas dari NumberStyle), dan LinkedStyle mengaitkan tingkat dengan Style paragraf. Untuk bullet gambar, CreatePictureBullet() dan DeletePictureBullet() mengelola gambar bullet ImageData, dan ListLevel.Font mengatur pemformatan angka atau karakter bullet itu sendiri. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) menghitung nilai label sebenarnya pada posisi tertentu dalam urutan penomoran.
Label Daftar dan Template Pradefinisi
ListLabel menjelaskan label yang dirender untuk contoh item daftar tertentu — LabelString adalah teks literal yang ditampilkan Word (seperti “3.” atau “•”), LabelValue adalah nilai numerik dasarnya, dan Font adalah pemformatan label tersebut. ListTemplate adalah enum format daftar pradefinisi Word (gaya bullet seperti BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds, dan format bernomor), digunakan dengan ListCollection.Add(listTemplate) untuk memulai dari format bawaan alih-alih menyusun properti satu per satu.
Tips dan Praktik Terbaik
- Gunakan
ListCollection.AddCopy(srcList)ketika sekelompok paragraf baru membutuhkan penomoran daftar yang dimulai kembali secara independen, alih-alih menggunakan kembaliListyang sudah terhubung ke paragraf lain. - Lebih pilih
ListFormat.ApplyNumberDefault()/ApplyBulletDefault()untuk daftar standar daripada mengonfigurasi secara manual setiap propertiListLevel. - Periksa
List.IsListStyleReferencevsIsListStyleDefinitionsebelum mengubah pemformatan daftar secara langsung — pemformatan daftar yang merujuk gaya mungkin dikendalikan olehStyleyang terhubung padanya. - Atur
RestartAfterLevelsecara eksplisit pada daftar bersarang daripada mengandalkan perilaku restart default ketika penomoran harus direset pada tingkat outline tertentu. - Gunakan
ListFormat.ListIndent()/ListOutdent()untuk memindahkan paragraf antar tingkat daftar alih-alih mengaturListLevelNumbersecara langsung, karena metode ini menjaga format daftar paragraf tetap konsisten secara internal.
Masalah Umum
| Masalah | Penyebab | Perbaikan |
|---|---|---|
| Dua paragraf yang seharusnya bernomor secara independen melanjutkan urutan yang sama | Kedua paragraf ListFormat.List merujuk pada objek List yang sama | Berikan paragraf kedua daftar tersendiri melalui ListCollection.AddCopy(srcList) alih-alih menggunakan kembali List yang sama |
| String format penomoran khusus tidak dirender seperti yang diharapkan | ListLevel.NumberFormat tidak cocok dengan pola yang diharapkan untuk tingkat NumberStyle | Verifikasi NumberFormat dan NumberStyle diatur secara konsisten untuk level yang sedang diedit |
| Indentasi daftar tampak salah setelah mengubah level secara programatik | ListLevelNumber diatur secara langsung tanpa memperbarui properti posisi yang terkait | Gunakan ListFormat.ListIndent()/ListOutdent() alih-alih mengatur ListLevelNumber secara langsung |
| Bullet gambar tidak muncul | Tidak ada bullet gambar yang dibuat untuk level tersebut, atau pemformatan bullet teks default masih aktif | Panggil ListLevel.CreatePictureBullet() dan berikan data gambar sebelum menghapus pemformatan bullet teks |
FAQ
Apa perbedaan antara List dan ListFormat?
List adalah definisi penomoran/poin yang dapat digunakan kembali dan dibagikan di antara paragraf; ListFormat bersifat per-paragraf — ia menunjuk pada List yang digunakan oleh paragraf tertentu dan pada tingkat mana, melalui ListFormat.List dan ListLevelNumber.
Bagaimana cara memeriksa apakah sebuah paragraf termasuk dalam daftar?
Baca ListFormat.IsListItem tentang format paragraf; jika true, ListFormat.List dan ListLevelNumber menjelaskan daftar dan tingkat mana yang menjadi miliknya.
Bagaimana cara membuat daftar baru memulai penomoran dari 1 secara terpisah dari daftar yang sudah ada?
Gunakan ListCollection.AddCopy(srcList) untuk membuat salinan independen dari definisi daftar, lalu terapkan salinan tersebut ke paragraf baru — daripada menggunakan kembali List yang asli, yang akan melanjutkan penghitung yang sama.
Bagaimana cara saya membuat daftar berpoin atau bernomor dari awal?
Gunakan ListFormat.ApplyBulletDefault() atau ApplyNumberDefault() untuk format bawaan Word, atau ListCollection.Add(listTemplate) dengan nilai ListTemplate untuk memulai dari salah satu format pra-definisi Word dan menyesuaikan List.ListLevels yang dihasilkan dari situ.
Bagaimana saya mengontrol format angka, misalnya “1)” alih-alih “1.”?
Setel ListLevel.NumberFormat pada tingkat yang relevan ke string format yang diinginkan, bersama dengan NumberStyle untuk gaya angka itu sendiri.
API Reference Ringkasan
| Kelas/Metode | Deskripsi |
|---|---|
List | Definisi daftar yang dapat digunakan kembali (penomoran/poin) |
ListCollection | Koleksi semua daftar dalam sebuah dokumen |
ListCollection.Add(listTemplate) / AddCopy(srcList) | Buat daftar dari templat yang telah ditentukan, atau salin yang sudah ada |
ListFormat | Referensi per paragraf ke List dan tingkat saat ini |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | Terapkan format bullet atau bernomor default pada paragraf |
ListLevel | Format penomoran/bullet untuk satu tingkat List |
ListLevel.NumberStyle / NumberFormat | Gaya numerik dan string format untuk sebuah level |
ListLabel | Label yang dirender (teks dan nilai) untuk item daftar tertentu |
ListTemplate | Enum format daftar pra-definisi Word |