Pembaca Imersif referensi JavaScript SDK (v1.4)
SDK Immersive Reader berisi pustaka JavaScript yang memungkinkan Anda mengintegrasikan Immersive Reader ke dalam aplikasi Anda.
Anda dapat menggunakan npmelemen , yarn, atau HTML <script> untuk menyertakan pustaka build stabil terbaru di aplikasi web Anda:
<script type='text/javascript' src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.4.0.js'></script>
npm install @microsoft/immersive-reader-sdk
yarn add @microsoft/immersive-reader-sdk
Fungsi
SDK mengekspos fungsi-fungsi ini:
- ImmersiveReader.launchAsync(token, subdomain, konten, opsi)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(options)
Fungsi: launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options)meluncurkan Pembaca Imersif dalam elemen HTML iframe di aplikasi web Anda. Perhatikan bahwa ukuran konten Anda dibatasi hingga maksimum 50 MB.
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| Parameter | Jenis | Deskripsi |
|---|---|---|
| token | string | Token autentikasi Microsoft Entra. Untuk mempelajari selengkapnya, lihat Cara membuat sumber daya Pembaca Imersif. |
| subdomain | string | Subdomain kustom sumber daya Pembaca Imersif Anda di Azure. |
| konten | Konten | Objek yang berisi konten yang akan ditampilkan dalam Pembaca Imersif. |
| opsi | Opsi | Opsi untuk mengonfigurasikan perilaku tertentu dari Immersive Reader. Opsional. |
Mengembalikan
Mengembalikan sebuah Promise<LaunchResponse>, yang menyelesaikan ketika Immersive Reader dimuat. Menyelesaikan Promise ke objek LaunchResponse .
Pengecualian
Jika Pembaca Imersif gagal dimuat, yang dikembalikan Promise ditolak dengan objek Kesalahan.
Fungsi: close
ImmersiveReader.close()menutup Pembaca Imersif.
Contoh kasus penggunaan untuk fungsi ini adalah jika tombol keluar disembunyikan dengan mengatur hideExitButton: true diopsi. Kemudian, tombol yang berbeda (misalnya, panah belakang header seluler) dapat memanggil fungsi ini close saat diklik.
close(): void;
Fungsi: renderButtons
Fungsi ImmersiveReader.renderButtons(options) ini tidak diperlukan jika Anda menggunakan panduan Cara menyesuaikan tombol Pembaca Imersif.
Fungsi ini menata dan memperbarui elemen tombol Immersive Reader dokumen. Jika options.elements disediakan, maka tombol dirender dalam setiap elemen yang disediakan dalam options.elements. Menggunakan options.elements parameter berguna ketika Anda memiliki beberapa bagian dalam dokumen Anda untuk meluncurkan Immersive Reader, dan menginginkan cara yang disederhanakan untuk merender beberapa tombol dengan gaya yang sama, atau ingin merender tombol dengan pola desain yang sederhana dan konsisten. Untuk menggunakan fungsi ini dengan parameter opsi renderButtons, panggil ImmersiveReader.renderButtons(options: RenderButtonsOptions); pemuatan halaman seperti yang ditunjukkan dalam cuplikan kode berikut. Jika tidak, tombol dirender dalam elemen dokumen yang memiliki kelas immersive-reader-button seperti yang ditunjukkan dalam Cara menyesuaikan tombol Pembaca Imersif.
// This snippet assumes there are two empty div elements in
// the page HTML, button1 and button2.
const btn1: HTMLDivElement = document.getElementById('button1');
const btn2: HTMLDivElement = document.getElementById('button2');
const btns: HTMLDivElement[] = [btn1, btn2];
ImmersiveReader.renderButtons({elements: btns});
Lihat tombol luncurkan atribut opsional untuk opsi penyajian lainnya. Untuk menggunakan opsi ini, tambahkan salah satu atribut opsi ke masing-masing HTMLDivElement di HTML halaman Anda.
renderButtons(options?: RenderButtonsOptions): void;
| Parameter | Jenis | Deskripsi |
|---|---|---|
| opsi | opsi renderButtons | Opsi untuk mengonfigurasikan perilaku tertentu dari fungsi renderButtons. Opsional. |
opsi renderButtons
Opsi untuk merender tombol Immersive Reader.
{
elements: HTMLDivElement[];
}
| Parameter | Jenis | Deskripsi |
|---|---|---|
| elemen | HTMLDivElement[] | Elemen untuk merender tombol Immersive Reader. |
Type: HTMLDivElement[]
Required: false
Tombol Luncurkan
SDK menyediakan gaya default untuk tombol luncurkan Pembaca Imersif. Gunakan atribut kelas immersive-reader-button untuk mengaktifkan gaya ini. Untuk informasi selengkapnya, lihat Cara mengkustomisasi tombol Pembaca Imersif.
<div class='immersive-reader-button'></div>
Gunakan atribut opsional berikut untuk mengonfigurasi tampilan dan nuansa tombol.
| Atribut | Deskripsi |
|---|---|
| gaya tombol data | Mengatur gaya tombol. Bisa icon, text, atau iconAndText. Default ke icon. |
| lokal data | Menyetel lokal. Misalnya, en-US atau fr-FR. Default Bahasa Inggris en. |
| data-icon-px-size | Mengatur ukuran ikon dalam piksel. Default ke 20 px. |
LaunchResponse
Berisi respons dari panggilan ke ImmersiveReader.launchAsync. Referensi ke elemen HTML iframe yang berisi Pembaca Imersif dapat diakses melalui container.firstChild.
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| Parameter | Jenis | Deskripsi |
|---|---|---|
| kontainer | HTMLDivElement | Elemen HTML yang berisi elemen iframe Immersive Reader. |
| sessionId | String | Pengidentifikasi unik global untuk sesi ini, digunakan untuk debugging. |
| charactersProcessed | number | Jumlah total karakter yang diproses |
Error
Berisi informasi tentang kesalahan.
{
code: string;
message: string;
}
| Parameter | Jenis | Deskripsi |
|---|---|---|
| kode | String | Salah satu himpunan kode galat. |
| pesan | String | Representasi kesalahan yang dapat dibaca manusia. |
| Kode kesalahan | Deskripsi |
|---|---|
| BadArgument | Argumen yang disediakan tidak valid. Lihat message parameter kesalahan. |
| Waktu habis | Immersive Reader gagal dimuat dalam batas waktu yang ditentukan. |
| TokenExpired | Token yang disediakan kedaluwarsa. |
| Dibatasi | Batas tarif panggilan telah terlampaui. |
Jenis
Konten
Berisi konten yang akan ditampilkan di Immersive Reader.
{
title?: string;
chunks: Chunk[];
}
| Parameter | Jenis | Deskripsi |
|---|---|---|
| title | String | Teks judul yang ditampilkan di bagian atas Immersive Reader (opsional) |
| Gugus | Gugus[] | Array gugus |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
Gugus
Satu potongan data, yang diteruskan ke konten Pembaca Imersif.
{
content: string;
lang?: string;
mimeType?: string;
}
| Parameter | Jenis | Deskripsi |
|---|---|---|
| konten | String | String yang berisi konten yang dikirim ke Immersive Reader. |
| lang | String | Bahasa teks, nilainya dalam format tag bahasa IETF BCP 47, misalnya, en, es-ES. Bahasa terdeteksi secara otomatis jika tidak ditentukan. Untuk informasi selengkapnya, lihat Bahasa yang didukung. |
| mimeType | string | Format teks biasa, MathML, HTML & Microsoft Word DOCX didukung. Untuk informasi selengkapnya, lihat Jenis MIME yang didukung. |
content
Type: String
Required: true
Default value: null
lang
Type: String
Required: false
Default value: Automatically detected
mimeType
Type: String
Required: false
Default value: "text/plain"
Jenis MIME yang didukung
| Jenis MIME | Deskripsi |
|---|---|
| text/plain | Teks biasa. |
| teks/html | Konten HTML. |
| aplikasi/mathml+xml | Bahasa Markup Matematika (MathML). |
| application/vnd.openxmlformats-officedocument.wordprocessingml.documen | Microsoft Word .docx memformat dokumen. |
Opsi
Berisi properti yang mengonfigurasikan perilaku tertentu dari Immersive Reader.
{
uiLang?: string;
timeout?: number;
uiZIndex?: number;
useWebview?: boolean;
onExit?: () => any;
customDomain?: string;
allowFullscreen?: boolean;
parent?: Node;
hideExitButton?: boolean;
cookiePolicy?: CookiePolicy;
disableFirstRun?: boolean;
readAloudOptions?: ReadAloudOptions;
translationOptions?: TranslationOptions;
displayOptions?: DisplayOptions;
preferences?: string;
onPreferencesChanged?: (value: string) => any;
disableGrammar?: boolean;
disableTranslation?: boolean;
disableLanguageDetection?: boolean;
}
| Parameter | Jenis | Deskripsi |
|---|---|---|
| uiLang | String | Bahasa UI, nilainya dalam format tag bahasa IETF BCP 47, misalnya, en, es-ES. Default ke bahasa browser jika tidak ditentukan. |
| waktu habis | Angka | Durasi (dalam milidetik) sebelum launchAsyncgagal dengan kesalahan waktu habis (defaultnya adalah 15.000 md). Batas waktu ini hanya berlaku untuk peluncuran awal halaman Pembaca, saat halaman Pembaca terbuka dan spinner dimulai. Penyesuaian batas waktu seharusnya tidak diperlukan. |
| uiZIndex | Angka | Indeks Z dari elemen HTML iframe yang dibuat (defaultnya adalah 1000). |
| gunakanWebview | Boolean | Gunakan tag webview alih-alih elemen HTML iframe , untuk kompatibilitas dengan Chrome Apps (defaultnya salah). |
| onExit | Function | Mengeksekusi ketika Immersive Reader keluar. |
| kustomDomain | String | Dicadangkan untuk penggunaan internal. Domain kustom tempat webapp Immersive Reader dihosting (defaultnya null). |
| allowFullscreen | Boolean | Kemampuan untuk beralih layar penuh (default adalah benar). |
| induk | Simpul | Simpul tempat elemen atau Webview kontainer HTML iframe ditempatkan. Jika elemen tidak ada, iframe ditempatkan di body. |
| hideExitButton | Boolean | Menyembunyikan panah tombol keluar Immersive Reader (defaultnya adalah false). Nilai ini seharusnya hanya benar jika ada mekanisme alternatif yang disediakan untuk keluar dari Pembaca Imersif (misalnya, panah belakang toolbar seluler). |
| cookiePolicy | CookiePolicy | Pengaturan untuk penggunaan cookie Immersive Reader (defaultnya adalah CookiePolicy.Disable). Aplikasi host bertanggung jawab untuk mendapatkan persetujuan pengguna yang diperlukan sesuai dengan Kebijakan Kepatuhan Cookie Uni Eropa. Untuk informasi selengkapnya, lihat Opsi Kebijakan Cookie. |
| disableFirstRun | Boolean | Nonaktifkan pengalaman menjalankan pertama. |
| bacaAloudOptions | BacaAloudOptions | Opsi untuk mengonfigurasikan Read Aloud. |
| translationOptions | TranslationOptions | Opsi untuk mengonfigurasikan terjemahan. |
| displayOptions | DisplayOptions | Opsi untuk mengonfigurasi ukuran teks, font, tema, dan sebagainya. |
| preferensi | String | Untai yang dikembalikan dari onPreferencesChanged mewakili preferensi pengguna di Immersive Reader. Untuk informasi selengkapnya, lihat Cara menyimpan preferensi pengguna. |
| onPreferencesChanged | Function | Dijalankan ketika preferensi pengguna telah berubah. Untuk informasi selengkapnya, lihat Cara menyimpan preferensi pengguna. |
| disableTranslation | Boolean | Menonaktifkan pengalaman terjemahan kata dan dokumen. |
| disableGrammar | Boolean | Menonaktifkan pengalaman Grammar. Opsi ini juga menonaktifkan Suku Kata, Bagian Ucapan, dan Kamus Gambar, yang tergantung pada Bagian Ucapan. |
| disableLanguageDetection | Boolean | Menonaktifkan Deteksi Bahasa untuk memastikan Immersive Reader hanya menggunakan bahasa yang ditentukan secara eksplisit pada Content/Chunk[]. Opsi ini harus digunakan secara hemat, terutama dalam situasi di mana deteksi bahasa tidak berfungsi. Misalnya, masalah ini lebih mungkin terjadi dengan bagian pendek kurang dari 100 karakter. Anda harus yakin tentang bahasa yang Anda kirim, karena teks ke ucapan tidak akan bersuara dengan benar. Suku kata, Bagian Ucapan, dan Kamus Gambar tidak berfungsi dengan benar jika bahasa tidak benar. |
uiLang
Type: String
Required: false
Default value: User's browser language
timeout
Type: Number
Required: false
Default value: 15000
uiZIndex
Type: Number
Required: false
Default value: 1000
onExit
Type: Function
Required: false
Default value: null
preferences
Type: String
Required: false
Default value: null
Perhatian
Jangan mencoba mengubah nilai -preferences string yang dikirim ke dan dari aplikasi Pembaca Imersif secara terprogram karena ini dapat menyebabkan perilaku tak terduga yang mengakibatkan pengalaman pengguna yang terdegradasi. Aplikasi host tidak boleh menetapkan nilai kustom atau memanipulasi untai -preferences. Saat menggunakan opsi untai -preferences, gunakan hanya nilai persis yang dikembalikan dari opsi panggilan balik -onPreferencesChanged.
onPreferencesChanged
Type: Function
Required: false
Default value: null
customDomain
Type: String
Required: false
Default value: null
ReadAloudOptions
type ReadAloudOptions = {
voice?: string;
speed?: number;
autoplay?: boolean;
};
| Parameter | Jenis | Deskripsi |
|---|---|---|
| Suara | String | Suara, baik Perempuan atau Laki-laki. Tidak semua bahasa mendukung dua gender. |
| kecepatan | Angka | Kecepatan pemutaran. Harus antara 0,5 dan 2,5, inklusif. |
| putar otomatis | Boolean | Mulai Read Aloud secara Otomatis saat Immersive Reader dimuat. |
Catatan
Karena keterbatasan browser, putar otomatis tidak didukung di Safari.
voice
Type: String
Required: false
Default value: "Female" or "Male" (determined by language)
Values available: "Female", "Male"
speed
Type: Number
Required: false
Default value: 1
Values available: 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2, 2.25, 2.5
TranslationOptions
type TranslationOptions = {
language: string;
autoEnableDocumentTranslation?: boolean;
autoEnableWordTranslation?: boolean;
};
| Parameter | Jenis | Deskripsi |
|---|---|---|
| bahasa | String | Mengatur bahasa terjemahan, nilainya dalam format tag bahasa IETF BCP 47, misalnya, fr-FR, es-MX, zh-Hans-CN. Diperlukan untuk mengaktifkan terjemahan kata atau dokumen secara otomatis. |
| autoEnableDocumentTranslation | Boolean | Secara otomatis menerjemahkan seluruh dokumen. |
| AutoEnableWordTranslation | Boolean | Secara otomatis mengaktifkan terjemahan kata. |
language
Type: String
Required: true
Default value: null
Values available: For more information, see the Supported languages section
ThemeOption
enum ThemeOption { Light, Dark }
DisplayOptions
type DisplayOptions = {
textSize?: number;
increaseSpacing?: boolean;
fontFamily?: string;
themeOption?: ThemeOption
};
| Parameter | Jenis | Deskripsi |
|---|---|---|
| textSize | Angka | Menyetel ukuran teks yang dipilih. |
| peningkatanSpacing | Boolean | Mengatur apakah penspasian teks dianut atau di luar. |
| fontFamily | String | Mengatur font yang dipilih (Calibri, ComicSans, atau Sitka). |
| themeOption | ThemeOption | Mengatur tema pembaca yang dipilih (Terang, Gelap). |
textSize
Type: Number
Required: false
Default value: 20, 36 or 42 (Determined by screen size)
Values available: 14, 20, 28, 36, 42, 48, 56, 64, 72, 84, 96
fontFamily
Type: String
Required: false
Default value: "Calibri"
Values available: "Calibri", "Sitka", "ComicSans"
Opsi CookiePolicy
enum CookiePolicy { Disable, Enable }
Pengaturan berikut hanya untuk tujuan informasi. Immersive Reader menyimpan pengaturannya, atau preferensi pengguna, dalam cookie. Opsi cookiePolicy ini menonaktifkan penggunaan cookie secara default untuk mematuhi undang-undang Kepatuhan Cookie Uni Eropa. Jika Anda ingin mengaktifkan kembali cookie dan memulihkan fungsionalitas default untuk preferensi pengguna Pembaca Imersif, situs web atau aplikasi Anda memerlukan persetujuan yang tepat dari pengguna untuk mengaktifkan cookie. Kemudian, untuk mengaktifkan kembali cookie di Immersive Reader, Anda harus secara eksplisit mengatur opsicookiePolicy ke CookiePolicy.Enable saat meluncurkan Immersive Reader.
Tabel berikut ini menjelaskan pengaturan apa yang disimpan Pembaca Imersif dalam cookie-nya ketika opsi cookiePolicy diaktifkan.
| Pengaturan | Jenis | Deskripsi |
|---|---|---|
| textSize | Angka | Menyetel ukuran teks yang dipilih. |
| fontFamily | String | Mengatur font yang dipilih (Calibri, ComicSans, atau Sitka). |
| textSpacing | Angka | Mengatur apakah penspasian teks dianut atau di luar. |
| formattingEnabled | Boolean | Menyetel apakah pemformatan HTML dianut atau di luar. |
| Tema | String | Mengatur tema yang dipilih (Terang, Gelap). |
| syllabificationEnabled | Boolean | Mengatur apakah syllabification akan mengaktifkan atau menonaktifkan. |
| nounHighlightingEnabled | Boolean | Mengatur apakah penyorotan kata benda diaktifkan atau dinonaktifkan. |
| nounHighlightingColor | String | Mengatur warna penyorotan kata benda yang dipilih. |
| verbHighlightingEnabled | Boolean | Mengatur apakah penyorotan kata kerja diaktifkan atau dinonaktifkan. |
| verbHighlightingColor | String | Mengatur warna penyorotan kata kerja yang dipilih. |
| adjectiveHighlightingEnabled | Boolean | Mengatur apakah penyorotan kata sifat diaktifkan atau dinonaktifkan. |
| adjectiveHighlightingColor | String | Mengatur warna penyorotan kata sifat yang dipilih. |
| adverbHighlightingEnabled | Boolean | Mengatur apakah penyorotan kata keterangan diaktifkan atau dinonaktifkan. |
| adverbHighlightingColor | String | Mengatur warna penyorotan kata keterangan yang dipilih. |
| pictureDictionaryEnabled | Boolean | Menyetel apakah Kamus Gambar diaktifkan atau dinonaktifkan. |
| posLabelsEnabled | Boolean | Menyetel apakah label teks superskrip dari setiap Bagian Ucapan yang disorot diaktifkan atau dinonaktifkan. |
Bahasa yang didukung
Fitur terjemahan Immersive Reader mendukung banyak bahasa. Untuk informasi selengkapnya, lihat Dukungan bahasa.
Dukungan HTML
Saat pemformatan diaktifkan, konten berikut dirender sebagai HTML dalam Pembaca Imersif.
| HTML | Konten yang didukung |
|---|---|
| Gaya font | Tebal, miring, garis bawah, kode, coretan, superskrip, subskrip |
| Daftar yang tidak diurutkan | Disk, lingkaran, persegi |
| Daftar yang diurutkan | Desimal, upper-Alpha, lower-Alpha, upper-Roman, lower-Roman |
Tag yang tidak didukung dirender sebanding. Gambar dan tabel saat ini tidak didukung.
Dukungan browser
Gunakan versi terbaru browser berikut untuk pengalaman terbaik dengan Immersive Reader.
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari
Langkah selanjutnya
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk