Cara UI Automation Mengekspos Objek Tersemat

Topik ini menjelaskan bagaimana Microsoft UI Automation menggunakan pola kendali Text dan TextRange untuk mengungkapkan objek yang disematkan (elemen anak/turunan) dalam dokumen teks atau wadah.

Untuk Automasi UI, objek yang disematkan adalah elemen apa pun yang memiliki batas non-tekstual seperti gambar, hyperlink, tabel, atau jenis dokumen (lembar bentang Microsoft Excel, file Microsoft Windows Media, dan sebagainya).

Catatan

Ini berbeda dari definisi OLE Model Objek Komponen (COM) (lihat Objek Tersemat), di mana elemen dibuat dalam satu aplikasi dan disematkan atau ditautkan di aplikasi lain. Apakah objek dapat diedit dalam aplikasi aslinya tidak relevan dalam konteks Automasi UI.

Objek Tertanam dan Pohon UI Automation

Objek yang disematkan diperlakukan sebagai elemen individual dalam tampilan kontrol pohon Automation UI. Kontainer tersebut dideteksi sebagai elemen turunan dari wadah teks sehingga dapat diakses melalui model objek yang sama seperti kontrol lain dalam Automasi UI.

Tabel berikut mencantumkan contoh elemen kontainer dan non-kontainer.

Elemen kontainer

Elemen bukan kontainer

  • Kalender
  • Kotak Kombo
  • DataGrid
  • Dokumen
  • Edit
  • Grup
  • Header
  • HeaderItem
  • Daftar
  • Menu
  • MenuBar
  • Panel
  • SplitButton
  • Tab
  • Tabel
  • Toolbar
  • Pohon
  • TreeItem
  • Jendela
  • Tautan
  • Kotak Centang
  • Tombol

Gambar berikut menunjukkan kontainer teks (dokumen) dengan tabel dan gambar yang disematkan.

ilustrasi memperlihatkan dokumen dengan tabel dan gambar yang disematkan

Tampilan konten Automation UI dari dokumen sebelumnya diperlihatkan dalam diagram berikut.

diagram tampilan konten otomatisasi ui dokumen dengan objek yang disematkan

Objek yang tertanam "Kompatibel" dan "Tidak Kompatibel"

Beberapa penyedia Automation UI menggunakan penyimpanan teks yang sama untuk setiap objek TextPattern yang dikandungnya. Objek yang didukung oleh penyimpanan teks yang sama dengan kontainernya disebut sebagai objek tersemat "kompatibel". Objek ini dapat menjadi objek TextPattern itu sendiri dan, dalam hal ini, rentang teksnya sebanding dengan rentang teks yang diperoleh dari kontainer mereka. Ini memungkinkan penyedia untuk mengekspos informasi klien tentang objek TextPattern individual seolah-olah mereka adalah satu, penyedia teks besar.

Namun, penyedia dapat menggunakan penyimpanan teks yang berbeda untuk objek TextPattern yang berbeda yang disematkan dalam kontainer TextPattern. Objek yang tidak didukung oleh penyimpanan teks kontainer disebut sebagai objek tersemat "tidak kompatibel". Jenis objek yang disematkan ini mungkin atau mungkin bukan objek berbasis TextPattern.

Tabel berikut mencantumkan beberapa contoh objek tersemat yang kompatibel dan tidak kompatibel.

Objek Objek tersemat yang kompatibel Objek yang disematkan tidak kompatibel
Objek Non-TextPattern yang tersemat Tombol di Microsoft Edge
Tabel Data di Microsoft Edge		 Tombol di RichTextBlock dalam kerangka kerja XAML Microsoft
Gambar dengan teks alt di Microsoft Edge
ListView dengan komponen ListItems di dalam RichTextBlock pada framework XAML milik Microsoft
Objek yang disematkan oleh TextPattern Kontrol input jenis "teks" di Microsoft Edge
Tabel dalam dokumen Word		 Elemen TextBox dalam dokumen Microsoft Word

Mengekspos Objek Tertanam

Pola kontrol Text dan TextRange mengekspos properti dan metode yang memfasilitasi navigasi dan kueri objek yang disematkan.

Konten tekstual (atau teks dalam) kontainer teks dan objek yang disematkan, seperti hyperlink atau sel tabel, diekspos sebagai aliran teks berkelanjutan tunggal dalam tampilan kontrol dan tampilan konten pohon Automation UI; batas objek diabaikan. Jika klien Automation UI mengambil teks untuk membaca, menginterpretasikan, atau menganalisis dengan cara tertentu, rentang teks harus diperiksa untuk kasus khusus, seperti tabel dengan konten tekstual atau objek tersemat lainnya. Panggil IUIAutomationTextRange::GetChildren untuk mendapatkan antarmuka IUIAutomationElement untuk setiap objek yang disematkan, lalu panggil IUIAutomationTextPattern::RangeFromChild untuk mendapatkan rentang teks untuk setiap elemen. Ini dilakukan secara rekursif sampai semua konten tekstual diambil.

Catatan

Rentang terdegenerasi (atau diciutkan) adalah keadaan di mana titik awal dan titik akhir sama. Rentang degenerasi sering digunakan untuk menunjukkan posisi kursor teks melalui metode ITextProviderGetSelection dan GetCaretRange .

Diagram berikut menunjukkan aliran teks dengan objek yang disematkan dan rentang rentangnya.

diagram memperlihatkan aliran teks dengan objek yang disematkan dan rentang rentangnya

Objek yang disematkan dan TextUnit

Objek ITextProvider dapat dilalui dengan menggunakan TextUnit tertentu. Penyedia yang berisi objek yang disematkan dapat dilalui dengan cara yang sama, tetapi objek yang disematkan memengaruhi traversal. Berikut adalah beberapa hal yang perlu diperhatikan:

  • Setiap objek yang disematkan yang tidak kompatibel diwakili oleh karakter pengganti U+FFFC di penyimpanan teks TextPattern elemen kontainer. Ini juga dianggap sebagai satuan karakter sekaligus satuan kata.
  • Objek yang disematkan yang kompatibel dapat terdiri dari beberapa karakter dan kata.
  • Elemen penutup adalah elemen paling bawah yang mencakup seluruh rentang teks.
  • Elemen turunan dari rentang juga merupakan elemen turunan dari elemen kontainer yang terletak sebagian atau sepenuhnya dalam rentang.
  • Idealnya (terutama dalam kasus elemen kontainer seperti Tabel) batas kata tidak melampaui batas objek. Dalam contoh berikut, satuan kata "Bar" tidak mengandung posisi teks manapun yang berada di luar tag </td> (<br \> bukan bagian dari kata "Bar").
<table style="width:100%">
  <tr>
    <th>Name</th>
    <th>Notes</th>
  </tr>
  <tr>
    <td>Eve Jackson</td>
    <td>Foo Bar</td>
  </tr>
</table>
<br/>
  • Secara umum, <br \> diperlakukan sebagai kata individu sehingga tidak melampaui batas garis.
  • Pengecualian untuk aturan sebelumnya adalah di mana unit teks Word berisi objek lengkap di dalamnya sendiri. Misalnya, <p>Hello <a href="#">link</a> here.</p>, yang mencakup kontainer sebaris, memiliki kata "Hello ", "link" dan "here." Di mana "tautan " memiliki objek TextPattern sebagai elemen penutup dan objek tautan sebagai turunannya.
  • Dalam kasus unit Karakter, objek adalah elemen penutup (unit teks seperti ini seharusnya tidak memiliki anak).
  • Objek anotasi tidak boleh direpresentasikan sebagai objek yang disematkan. Misalnya, keberadaan identifikasi Penulis lainnya dalam dokumen yang ditulis bersama.
  • Objek yang disematkan mengambil setidaknya satu posisi kursor, anotasi hanyalah metadata.
  • Setiap batas objek (awal dan akhir) diwakili oleh pemisah format dalam rentang dokumen TextPattern.
  • Untuk HTML, setiap tag html tidak selalu menghasilkan objek Automation UI. Misalnya, konten dalam tag penekanan tidak perlu direpresentasikan sebagai elemen melainkan aliran teks tempat UIA_IsItalicAttributeId mengembalikan TRUE.
  • Titik akhir awal bersifat inklusif dan merupakan titik akhir pilihan sementara titik akhir eksklusif. Ini berguna ketika rentang mengalami kerusakan dan titik akhir dari Mulai dan Akhir berada pada posisi yang sama untuk rentang tersebut.

Membandingkan objek yang disematkan

Objek TextPattern bersarang yang berada dalam hubungan anak yang serupa dan berbagi penyimpanan teks dasar yang sama disebut sebanding. Dalam hal ini, rentang dari salah satu objek TextPattern dapat dibandingkan menggunakan ITextRangeProvider::Compare dan ITextRangeProvider::CompareEndpoints. Keduanya menghasilkan nilai numerik yang valid yang menentukan posisi relatifnya.

Objek non-TextPattern yang disematkan dalam objek TextPattern sebanding dengan TextPattern jika objek memiliki rentang yang valid di TextPattern (ITextProvider::RangeFromChild) dan konten di belakang rentang teks tidak kosong dan bukan karakter pengganti.

Objek TextPattern yang Disematkan dan Unit Teks Dokumen

Untuk objek TextPattern yang disematkan, unit Dokumen hanya mengenali konten yang terkandung dalam elemen tersebut.

Hierarki elemen Word TextPattern

  • Elemen dokumen mengimplementasikan TextPattern dan Document mengembalikan seluruh rentang dokumen Word.
  • Halaman individual dokumen mengimplementasikan TextPattern dan Dokumen mengembalikan konten halaman individual tersebut (meskipun halaman berbagi penyimpanan teks yang sama dengan seluruh dokumen TextPattern).

Kontrol input halaman web dan teks di Edge

  • Elemen Panel halaman web utama mengimplementasikan TextPattern dan mengekspos seluruh konten halaman web.
  • Kontrol input teks individual mendukung TextPattern di mana rentang dokumen mewakili teks yang terdapat di setiap bidang input (meskipun mereka berbagi penyimpanan teks yang sama dengan seluruh halaman web).

Skenario Umum

Bagian ini menyajikan contoh skenario umum yang melibatkan objek yang disematkan: hyperlink, gambar, dan tabel. Dalam contoh berikut, kurung kurawal kiri ({) mewakili titik akhir Mulai rentang teks, dan kurung kurawal kanan (}) mewakili titik akhir Akhir.

Contoh HyperLink 1: Rentang teks yang berisi hiperlink teks yang tertanam

Rentang teks berikut berisi hyperlink teks yang disematkan.

{URL https://www.microsoft.com disematkan dalam teks}.

Memanggil IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren, dan IUIAutomationTextPattern::RangeFromChild menghasilkan perilaku yang dijelaskan dalam tabel berikut.

Metode yang Dipanggil Hasil
IUIAutomationTextRange::GetText Mengembalikan string "URL https://www.microsoft.com disematkan dalam teks".
IUIAutomationTextRange::GetEnclosingElement Mengembalikan elemen UI Automation yang paling dalam yang mencakup rentang teks, dalam hal ini, elemen otomatisasi yang mewakili penyedia teks itu sendiri.
IUIAutomationTextRange::GetChildren Mengembalikan elemen Automation UI yang mewakili kontrol hyperlink.
IUIAutomationTextPattern::RangeFromChild, di mana elemen UI Automation dikembalikan oleh metode IUIAutomationTextRange::GetChildren sebelumnya. Mengembalikan rentang yang mewakili "https://www.microsoft.com".

Contoh HyperLink 2: Rentang teks yang sebagian mencakup hyperlink teks yang disematkan

Rentang teks berikut sebagian mencakup hyperlink teks yang disematkan.

URL https://{www} disematkan dalam teks.

Memanggil IUIAutomationTextRange::GetText, GetEnclosingElement, dan GetChildren menghasilkan perilaku yang dijelaskan dalam tabel berikut.

Metode yang Dipanggil Hasil
IUIAutomationTextRange::GetText Mengembalikan string "www".
IUIAutomationTextRange::GetEnclosingElement Mengembalikan elemen Automation UI terdalu yang mencakup rentang teks; dalam hal ini, kontrol hyperlink.
IUIAutomationTextRange::GetChildren Mengembalikan NULL karena rentang teks tidak mencakup seluruh string URL.

Contoh HyperLink 3: Rentang teks yang sebagian mencakup konten kontainer teks

Rentang teks berikut sebagian mencakup konten kontainer teks. Kontainer teks memiliki hyperlink teks yang disematkan yang bukan bagian dari rentang teks.

{URL} https://www.microsoft.com disematkan dalam teks.

Memanggil metode IUIAutomationTextRange::GetText, GetEnclosingElement, dan Move menghasilkan perilaku yang dijelaskan dalam tabel berikut.

Metode yang Dipanggil Hasil
IUIAutomationTextRange::GetText Mengembalikan string "The URL".
IUIAutomationTextRange::GetEnclosingElement Mengembalikan elemen UI Automation yang paling dalam yang mencakup rentang teks, dalam hal ini, elemen yang mewakili penyedia teks itu sendiri.
IUIAutomationTextRange::Move Memindahkan rentang teks ke "https://" karena teks hyperlink terdiri dari kata-kata terpisah. Dalam hal ini, hyperlink tidak diperlakukan sebagai objek tunggal.
URL {http} disematkan dalam teks.

Contoh Gambar 1: Rentang teks yang berisi gambar yang disematkan

Teks berikut berisi gambar pesawat ulang-alik yang tersemat.

{Gambar ilustrasi pesawat ulang-alik disematkan dalam teks}.

Memanggil metode IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren, dan IUIAutomationTextPattern::RangeFromChild akan menghasilkan perilaku yang dijelaskan dalam tabel berikut.

Metode yang Dipanggil Hasil
IUIAutomationTextRange::GetText Mengembalikan string "Gambar disematkan dalam teks". Teks ALT apa pun yang terkait dengan gambar tidak disertakan dalam aliran teks.
IUIAutomationTextRange::GetEnclosingElement Mengembalikan elemen Automation UI terdalu yang mencakup rentang teks, dalam hal ini, elemen yang mewakili penyedia teks itu sendiri.
IUIAutomationTextRange::GetChildren Mengembalikan elemen Automation UI yang mewakili kontrol gambar.
IUIAutomationTextPattern::RangeFromChild di mana elemen UI Automation dikembalikan oleh metode IUIAutomationTextRange::GetChildren sebelumnya. Mengembalikan rentang degenerasi.

Contoh Gambar 2: Rentang teks yang sebagian mencakup konten kontainer teks

Rentang teks berikut sebagian mencakup konten kontainer teks. Kontainer teks memiliki gambar yang disematkan yang bukan bagian dari rentang teks.

{Gambar} ilustrasi pesawat ulang-alik disematkan dalam teks.

Memanggil metode IUIAutomationTextRange::GetText, GetEnclosingElement, dan Move menghasilkan perilaku yang dijelaskan dalam tabel berikut.

Metode yang Dipanggil Hasil
IUIAutomationTextRange::GetText Mengembalikan string "Gambar tersebut".
IUIAutomationTextRange::GetEnclosingElement Mengembalikan elemen UI Automation terdalam yang mengelilingi rentang teks, dalam hal ini, elemen yang mewakili penyedia teks itu sendiri.
IUIAutomationTextRange::Pindahkan dengan parameter (TextUnit_Word, 2). Memindahkan rentang teks ke "is ". Karena hanya objek tersemat berbasis teks yang dianggap sebagai bagian dari aliran teks, gambar dalam contoh ini tidak memengaruhi IUIAutomationTextRange::Move atau nilai pengembaliannya, dalam hal ini, 2.

Tabel

Contoh Tabel 1: Mendapatkan kontainer teks dari konten sel

Tabel berikut menampilkan wadah teks dari isi sel.

Sel dengan Gambar Sel dengan Teks
ilustrasi antar-jemput X
ilustrasi ruang dan teleskop Y
ilustrasi mikroskop Z

Memanggil IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild, dan IUIAutomationTextRange::GetEnclosingElement menghasilkan perilaku yang dijelaskan dalam tabel berikut.

Metode yang Dipanggil Hasil
IUIAutomationGridPattern::GetItem dengan parameter (0, 0). Mengembalikan elemen Automation UI yang mewakili konten sel tabel, dalam hal ini, elemen adalah kontrol teks.
iuiautomationtextpattern::rangefromchild mengembalikan rentang gambar ilustrasi pesawat ulang-alik.
GetEnclosingElement untuk objek yang dikembalikan oleh metode IUIAutomationTextPattern::RangeFromChild sebelumnya. Mengembalikan elemen Automation UI yang mewakili sel tabel. Dalam hal ini, elemen adalah kontrol teks yang mendukung pola kontrol TableItem .
IUIAutomationTextRange::GetEnclosingElement untuk objek yang dikembalikan oleh metode GetEnclosingElement sebelumnya. Mengembalikan elemen Automation UI yang mewakili tabel.
IUIAutomationTextRange::GetEnclosingElement untuk objek yang dikembalikan oleh metode GetEnclosingElement sebelumnya. Mengembalikan elemen Automation UI yang mewakili penyedia teks itu sendiri.

Contoh Tabel 2: Mendapatkan konten teks sel

Tabel dalam contoh sebelumnya mengambil teks dari sebuah sel.

Memanggil metode IUIAutomationGridPattern::GetItem dan IUIAutomationTextPattern::RangeFromChild menghasilkan perilaku yang dijelaskan dalam tabel berikut.

Metode yang Dipanggil Hasil
IUIAutomationGridPattern::GetItem dengan parameter (1,1). Mengembalikan elemen Automation UI yang mewakili konten sel tabel. Dalam hal ini, elemen adalah kontrol teks.
IUIAutomationTextPattern::RangeFromChild di mana elemen Automation UI adalah objek yang dikembalikan oleh metode IUIAutomationGridPattern::GetItem sebelumnya. Mengembalikan "Y".

Saat menelusuri dokumen dengan TextUnit_Line, jika rentang teks memasukkan tabel yang disematkan, setiap baris teks dalam sel harus diperlakukan sebagai baris.

Konseptual

  • Last updated on