Bagikan melalui

Pola Kontrol ItemContainer

  • Artikel

Menjelaskan panduan dan konvensi untuk menerapkan IItemContainerProvider, termasuk informasi tentang metode. Pola kontrol ItemContainer digunakan untuk mendukung virtualisasi item.

Kontrol yang berisi sejumlah besar item anak dapat menggunakan virtualisasi untuk mengelola item secara efisien. Dengan virtualisasi, kontrol mempertahankan informasi lengkap dalam memori hanya untuk subset item pada waktu tertentu. Biasanya, subset hanya menyertakan item yang saat ini terlihat oleh pengguna. Informasi lengkap tentang item virtual yang tersisa disimpan di penyimpanan dan dimuat ke dalam memori, atau direalisasikan, karena kontrol membutuhkannya, misalnya, karena item baru terlihat oleh pengguna.

Misalnya, diagram berikut menunjukkan kotak daftar yang berisi ribuan item virtual. Karena kontrol mempertahankan informasi lengkap hanya untuk item anak yang saat ini terlihat, penyedia dapat mengekspos elemen Microsoft UI Automation hanya untuk item 100—127.

diagram memperlihatkan item dalam kotak daftar yang divirtualisasikan dan tidak divirtualisasi

Kontrol yang menggunakan virtualisasi mewakili tantangan karena hanya item yang direalisasikan (de-virtualisasi) yang sepenuhnya tersedia sebagai elemen Automasi UI di pohon Automation UI. Item virtual tidak ada di pohon, sehingga informasi tentang item tersebut tidak tersedia.

Untuk memberikan informasi tentang item virtual, penyedia menerapkan pola kontrol ItemContainer, yang mengekspos antarmukaIItemContainerProvider. MetodeFindItemByProperty menemukan item turunan berdasarkan nilai properti tertentu, seperti Nama, AutomationId, atau . Jika item divirtualisasi, FindItemByProperty mengambil elemen tempat penampung Automation UI untuk item tersebut. Elemen tempat penampung adalah implementasi antarmukaIRawElementProviderSimple yang hanya mendukung pola kontrol VirtualizedItem.

Metode IVirtualizedItemProvider::Real memungkinkan klien untuk meminta agar item virtual direalisasikan, sehingga mengekspos elemen Automation UI lengkap untuk item sehingga semua properti dan pola yang diperlukan tersedia.

Meskipun tujuan utama pola kontrol ItemContainer adalah untuk mendukung skenario kontainer virtual, itu dapat diimplementasikan oleh kontainer apa pun yang mengambil item turunan berdasarkan nama, terlepas dari apakah kontainer menggunakan virtualisasi.

Topik ini berisi bagian berikut.

Pedoman dan Konvensi Implementasi

Saat menerapkan pola kontrol ItemContainer, perhatikan panduan dan konvensi berikut:

  • Kontrol apa pun yang dapat berisi item virtual harus mendukung pola kontrol ItemContainer. Setiap kontainer yang mendukung pengambilan item berdasarkan nilai properti dapat mendukung pola ini, terlepas dari apakah kontainer menggunakan virtualisasi.
  • Saat kontainer divirtualisasi, pola kontrol lain seperti Pilihan, tabel , dan Kisi dapat terpengaruh. Misalnya, metode ISelectionProvider::GetSelection hanya dapat mendukung elemen yang ada di viewport, atau hanya elemen yang dipilih yang saat ini tidak divirtualisasi.
  • Pola kontrol Scroll harus tidak terpengaruh oleh virtualisasi.
  • Tidak ada jumlah item atau informasi indeks yang tersedia untuk item virtual. Kontrol virtual dapat menggunakan describedBy atau properti ItemStatus untuk memberikan informasi ini, jika perlu.
  • Pengembang kontrol harus mendokumentasikan dan menerbitkan detail semua properti Automation UI dan pola kontrol yang terpengaruh oleh penggunaan virtualisasi. Meskipun pola kontrol ItemContainer dan VirtualizedItem menawarkan dukungan dasar, pola tersebut mungkin tidak mendukung beberapa perilaku virtualisasi.

Panduan dan persyaratan berikut berlaku untuk metodeIItemContainerProvider::FindItemByProperty.

  • Meskipun tidak diperlukan, Microsoft sangat menyarankan agar FindItemByProperty mendukung Nama, AutomationId, dan properti IsSelected.
  • FindItemByProperty bisa lambat jika perlu melintasi beberapa objek untuk menemukan objek yang cocok.
  • FindItemByProperty dapat dipanggil berulang kali untuk menemukan item secara berurutan. Item dapat dalam urutan apa pun selama setiap item dikembalikan hanya sekali.
  • FindItemByProperty dapat diimplementasikan untuk menemukan hanya elemen yang muncul dalam tampilan kontrol atau konten pohon Automation UI. Elemen yang hanya muncul dalam tampilan mentah dapat dilewati untuk menghindari pengambilan beberapa elemen yang hanya mewakili sebagian "item" kepada pengguna.
  • Saat kriteria pencarian cocok dengan item virtual, penyedia dapat mengembalikan elemen tempat penampung yang mendukung pola kontrol VirtualizedItem. Panduan berikut berlaku untuk elemen tempat penampung:
    • Mengambil elemen tempat penampung untuk item virtual tidak boleh menyebabkan perubahan UI.
    • Elemen tempat penampung harus menjadi serekan elemen turunan lainnya (peristiwa yang diubah struktur diperlukan).
    • Jika memungkinkan, penyedia dapat membuat elemen otomatisasi penuh alih-alih tempat penampung.
  • Ketika kriteria pencarian cocok dengan elemen yang tidak divirtualisasi, penyedia harus mengembalikan elemen aktual, bukan tempat penampung.
  • Ketika tidak ada item yang ditemukan, IItemContainerProvider::FindItemByProperty harus mengatur parameter pFound ke NULL dan mengembalikan S_OK.
  • Ketika parameter propertyId adalah 0, penyedia harus mengembalikan item berikutnya setelah pStartAfter.
  • Jika parameter pStartAfter NULL dan propertyId adalah 0, penyedia harus mengembalikan item pertama dalam kontainer.
  • Saat parameter propertyId adalah 0, parameter nilai diabaikan.

Panduan dan persyaratan berikut berlaku untuk elemen tempat penampung untuk item virtual di pohon Automation UI.

  • Meskipun penyedia didorong untuk mendukung lebih banyak properti dan pola kontrol untuk elemen tempat penampung, hanya pola kontrol VirtualizedItem yang diperlukan.
  • Penyedia dapat membatalkan elemen tempat penampung sebelumnya saat IItemContainerProvider::FindItemByProperty dipanggil lagi. (Jika klien perlu mewujudkan elemen tempat penampung, itu harus segera melakukannya; jika tidak, elemen dapat dibatalkan jika FindItemByProperty dipanggil lagi atau jika viewport berubah karena alasan apa pun.)
  • Tindakan UI seperti menggulir atau mengubah ukuran dapat menyebabkan viewport kontainer berubah dan sekumpulan item turunan baru menjadi terlihat. Dalam hal ini, elemen tempat penampung yang diambil sebelumnya mungkin tidak tersedia di pohon Automation UI.
  • Penyedia tidak boleh memvirtualisasi elemen UI yang tersedia di layar di viewport objek kontainer.

Anggota yang Diperlukan untuk IItemContainerProvider

Metode berikut diperlukan untuk menerapkan antarmukaIItemContainerProvider.

Anggota yang diperlukan Jenis anggota Catatan
FindItemByProperty Metode Tidak

 

Pola kontrol ItemContainer tidak memiliki properti atau peristiwa terkait.

Jenis Kontrol dan Pola Kontrol yang Didukung

Gambaran Umum Pola Kontrol Automasi UI

Gambaran Umum Pohon Automasi UI

Pola Kontrol VirtualizedItem