Cara Automation UI Mengekspos Objek Tersemat

Topik ini menjelaskan bagaimana Microsoft UI Automation menggunakan pola kontrol Text dan TextRange untuk mengekspos objek yang disematkan (elemen turunan/turunan) dalam dokumen teks atau kontainer.

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 Tersemat dan Pohon UI Automation

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

Tabel berikut mencantumkan contoh elemen kontainer dan non-kontainer.

Elemen kontainer

Elemen non-kontainer

• Calendar
• Kotak Kombo
• DataGrid
• Dokumen
• Edit
• Grupkan
• Header
• HeaderItem
• List
• 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.

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

Objek tersemat "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 tersemat Non-TextPattern	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 ListItems di RichTextBlock dalam kerangka kerja XAML Microsoft
Objek yang disematkan TextPattern	Kontrol input jenis "teks" di Microsoft Edge Tabel dalam dokumen Word	Elemen TextBox dalam dokumen Microsoft Word

Mengekspos Objek Tersemat

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 degenerasi (atau diciutkan) adalah tempat titik akhir mulai dan titik akhir sama. Rentang degenerasi sering digunakan untuk menunjukkan posisi kursor teks melalui metode ITextProvider GetSelection dan GetCaretRange .

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

Objek yang disematkan dan TextUnit

Objek ITextProvider dapat dilalui dan oleh 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 unit karakter dan unit 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 sebagian atau sepenuhnya diapit dalam rentang.
• Idealnya (terutama dalam kasus elemen kontainer seperti Tabel) batas kata tidak melampaui batas objek. Dalam contoh berikut, unit kata "Bar" tidak berisi posisi teks apa pun yang berada di luar </td> tag (<br \> bukan bagian dari kata "Bilah").

<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 penentu 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 merosgan dan titik akhir Mulai dan Akhir termasuk dalam posisi yang sama untuk rentang tersebut.

Membandingkan objek yang disematkan

Objek TextPattern berlapis yang berada dalam hubungan anak serupa dan berbagi penyimpanan teks pencadangan 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 TextUnit 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 hyperlink teks yang disematkan

Rentang teks berikut berisi hyperlink teks yang disematkan.

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

Memanggil metode 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 Automation UI terdalu 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, tempat elemen Automation UI 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 metode 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 "URL".
IUIAutomationTextRange::GetEnclosingElement	Mengembalikan elemen Automation UI terdalu yang mencakup rentang teks, dalam hal ini, elemen yang mewakili penyedia teks itu sendiri.
IUIAutomationTextRange::Move	Memindahkan rentang rentang teks ke "https://" karena teks hyperlink terdiri dari kata individual. Dalam hal ini, hyperlink tidak diperlakukan sebagai objek tunggal. URL {http} disematkan dalam teks.

Contoh Gambar 1: Rentang teks yang berisi gambar yang disematkan

Rentang teks berikut berisi gambar antar-jemput yang disematkan.

{Gambar disematkan dalam teks}.

Memanggil metode IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren, dan IUIAutomationTextPattern::RangeFromChild 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 tempat elemen Automation UI 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} 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".
IUIAutomationTextRange::GetEnclosingElement	Mengembalikan elemen Automation UI terdalu yang mencakup rentang teks, dalam hal ini, elemen yang mewakili penyedia teks itu sendiri.
IUIAutomationTextRange::Pindahkan dengan parameter (TextUnit_Word, 2).	Memindahkan rentang teks ke "adalah ". 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 mendapatkan kontainer teks dari konten sel.

Sel dengan Gambar	Sel dengan Teks
	X
	Y
	Z

Memanggil metode 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 .
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 mendapatkan konten teks 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.

Topik terkait

Konseptual

• Tentang Pola Kontrol Text dan TextRange
• Atribut Teks Automasi UI
• Gambaran Umum Pola Kontrol Automasi Antarmuka Pengguna
• Dukungan Automasi UI untuk Konten Tekstual