Referensi SDK JavaScript Immersive Reader (v1.1)

SDK Immersive Reader berisi pustaka JavaScript yang memungkinkan Anda mengintegrasikan Immersive Reader ke dalam aplikasi Anda.

Fungsi

SDK memaparkan fungsi:


launchAsync

Meluncurkan Immersive Reader dalam iframe 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 launchAsync

Nama Jenis Deskripsi
token string Token autentikasi Azure Active Directory. Lihat Cara Membuat Sumber Daya Immersive Reader untuk detail selengkapnya.
subdomain string Subdomain kustom sumber daya Immersive Reader Anda di Azure. Lihat Cara Membuat Sumber Daya Immersive Reader untuk detail selengkapnya.
content Konten Objek yang berisi konten yang akan ditampilkan di Immersive Reader.
options Opsi Opsi untuk mengonfigurasikan perilaku tertentu dari Immersive Reader. Opsional.

Mengembalikan

Mengembalikan sebuah Promise<LaunchResponse>, yang menyelesaikan ketika Immersive Reader dimuat. PromiseMenyelesaikan ke sebuah LaunchResponse objek.

Pengecualian

Yang dikembalikan Promise akan ditolak dengan Error objek jika Immersive Reader gagal dimuat. Untuk informasi selengkapnya, lihat Kode galat.


tutup

Menutup Immersive Reader.

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 close fungsi ini saat diklik.

close(): void;

Edit tombol peluncuran Immersive Reader

SDK menyediakan gaya default untuk tombol untuk meluncurkan Immersive Reader. Gunakan immersive-reader-buttonatribut kelas untuk mengaktifkan gaya ini. Lihat Cara Menyesuaikan tombol Immersive Readeruntuk detail selengkapnya.

<div class='immersive-reader-button'></div>

Atribut opsional

Gunakan atribut berikut untuk mengonfigurasikan tampilan dan nuansa tombol.

Atribut Deskripsi
data-button-style Mengatur gaya tombol. Bisa icon, text, atau iconAndText. Default ke icon.
data-locale Menyetel lokal. Misalnya, en-US atau fr-FR. Default Bahasa Inggris en.
data-icon-px-size Mengatur ukuran ikon dalam piksel. Default ke 20px.

renderButton

renderButtonsFungsi ini tidak diperlukan jika Anda menggunakan panduan tombol Cara Menyesuaikan Immersive Reader.

Fungsi ini menata dan memperbarui elemen tombol Immersive Reader dokumen. Jika options.elements disediakan, maka tombol akan 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 di bawah ini. Jika tidak, tombol akan dirender dalam elemen dokumen yang memiliki kelas immersive-reader-buttonseperti yang ditunjukkan dalam Cara Menyesuaikan tombol Immersive Reader .

// 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 Atribut Opsional di atas untuk opsi rendering lainnya. Untuk menggunakan opsi ini, tambahkan salah satu atribut opsi ke masing-masing HTMLDivElement di HTML halaman Anda.

renderButtons(options?: RenderButtonsOptions): void;

parameter renderButtons

Nama Jenis Deskripsi
options opsi renderButtons Opsi untuk mengonfigurasikan perilaku tertentu dari fungsi renderButtons. Opsional.

Opsi renderButtons

Opsi untuk merender tombol Immersive Reader.

{
    elements: HTMLDivElement[];
}

Parameter Opsi renderButtons

Pengaturan Jenis Deskripsi
elemen HTMLDivElement[] Elemen untuk merender tombol Immersive Reader.
elements
Type: HTMLDivElement[]
Required: false

LaunchResponse

Berisi respons dari panggilan ke ImmersiveReader.launchAsync. Perhatikan bahwa referensi ke iframe yang berisi Immersive Reader dapat diakses melalui container.firstChild.

{
    container: HTMLDivElement;
    sessionId: string;
}

Parameter LaunchResponse

Pengaturan Jenis Deskripsi
kontainer HTMLDivElement Elemen HTML yang berisi iframe Immersive Reader.
sessionId Untai (karakter) Pengidentifikasi unik global untuk sesi ini, digunakan untuk debugging.

Kesalahan

Berisi informasi tentang kesalahan.

{
    code: string;
    message: string;
}

Parameter Kesalahan

Pengaturan Jenis Deskripsi
kode Untai (karakter) Salah satu himpunan kode galat. Lihat Kode galat.
pesan Untai (karakter) Representasi kesalahan yang dapat dibaca manusia.

Kode galat

Kode Deskripsi
BadArgument Argumen yang disediakan tidak valid, lihatmessage parameter Kesalahan.
Batas waktu 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 Konten

Nama Jenis Deskripsi
judul Untai (karakter) 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 akan diteruskan ke dalam Konten Immersive Reader.

{
    content: string;
    lang?: string;
    mimeType?: string;
}

Parameter Gugus

Nama Jenis Deskripsi
konten Untai (karakter) String yang berisi konten yang dikirim ke Immersive Reader.
lang Untai (karakter) Bahasa teks, nilainya dalam format tag bahasa IETF BCP 47, misalnya en, es-ES. Bahasa akan terdeteksi secara otomatis jika tidak ditentukan. See Bahasa yang Didukung.
mimeType string Format teks biasa, MathML, HTML & Microsoft Word DOCX didukung. Lihat Jenis MIME yang didukung untuk detail selengkapnya.
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.
text/html Konten HTML. Pelajari lebih lanjut
aplikasi/mathml+xml Bahasa Markup Matematika (MathML). Pelajari selengkapnya.
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;
    allowFullscreen?: boolean;
    hideExitButton?: boolean;
    cookiePolicy?: CookiePolicy;
    disableFirstRun?: boolean;
    readAloudOptions?: ReadAloudOptions;
    translationOptions?: TranslationOptions;
    displayOptions?: DisplayOptions;
    preferences?: string;
    onPreferencesChanged?: (value: string) => any;
    customDomain?: string;
}

Parameter Opsi

Nama Jenis Deskripsi
uiLang Untai (karakter) Bahasa UI, nilainya dalam format tag bahasa IETF BCP 47, mis. id, es-ES. Default ke bahasa browser jika tidak ditentukan.
waktu habis Number Durasi (dalam milidetik) sebelum peluncuranAsyncgagal dengan kesalahan waktu habis (defaultnya adalah 15000 md). Batas waktu ini hanya berlaku untuk peluncuran awal halaman Pembaca, tempat keberhasilan diamati ketika halaman Pembaca terbuka dan pemintal dimulai. Penyesuaian waktu habis seharusnya tidak diperlukan.
uiZIndex Number Indeks Z dari iframe yang akan dibuat (defaultnya adalah 1000).
gunakanWebview Boolean Gunakan tag tampilan web alih-alih iframe, untuk kompatibilitas dengan Aplikasi Chrome (defaultnya salah).
onExit Fungsi Mengeksekusi ketika Immersive Reader keluar.
allowFullscreen Boolean Kemampuan untuk beralih layar penuh (default adalah benar).
hideExitButton Boolean Apakah menyembunyikan panah tombol keluar Immersive Reader (defaultnya adalah palsu). Ini seharusnya hanya benar jika ada mekanisme alternatif yang disediakan untuk keluar dari Immersive Reader (misalnya panah belakang toolbar seluler).
cookiePolicy CookiePolicy Pengaturan untuk penggunaan cookie Immersive Reader (defaultnya adalah CookiePolicy.Disable). Merupakan sebuah tanggung jawab aplikasi host untuk mendapatkan persetujuan pengguna yang diperlukan sesuai dengan Kebijakan Kepatuhan Cookie Eropa. Lihat Opsi Azure Policy Cookie.
disableFirstRun Boolean Nonaktifkan pengalaman menjalankan pertama.
bacaAloudOptions BacaAloudOptions Opsi untuk mengonfigurasikan Read Aloud.
translationOptions TranslationOptions Opsi untuk mengonfigurasikan terjemahan.
displayOptions DisplayOptions Opsi untuk mengonfigurasikan ukuran teks, font, dll.
preferensi Untai (karakter) Untai yang dikembalikan dari onPreferencesChanged mewakili preferensi pengguna di Immersive Reader. Lihat Parameter Pengaturan danPreferensi Pengguna Cara Menyimpanuntuk informasi selengkapnya.
onPreferencesChanged Fungsi Dijalankan ketika preferensi pengguna telah berubah. Lihat Preferensi Pengguna Cara Menyimpan untuk informasi selengkapnya.
kustomDomain Untai (karakter) Dicadangkan untuk penggunaan internal. Domain kustom tempat webapp Immersive Reader dihosting (defaultnya null).
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

Perhatian

PENTING Jangan mencoba untuk secara terprogram mengubah nilai -preferences untai yang dikirim ke dan dari aplikasi Immersive Reader karena ini dapat menyebabkan perilaku tak terduga yang mengakibatkan pengalaman pengguna yang terdegradasi bagi pelanggan Anda. Aplikasi host tidak boleh menetapkan nilai kustom untuk atau memanipulasi -preferences untai. Saat menggunakan -preferences opsi untai, gunakan hanya nilai persis yang dikembalikan dari opsi -onPreferencesChanged callback.

Type: String
Required: false
Default value: null
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 BacaAloudOptions

Nama Jenis Deskripsi
Suara Untai (karakter) Suara, baik "Perempuan" atau "Laki-laki". Perhatikan bahwa tidak semua bahasa mendukung kedua jenis kelamin.
kecepatan Number Kecepatan pemutaran, harus antara 0,5 dan 2,5, inklusif.
putar otomatis Boolean Mulai Read Aloud secara Otomatis saat Immersive Reader dimuat.
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

Catatan

Karena keterbatasan browser, putar otomatis tidak didukung di Safari.


TranslationOptions

type TranslationOptions = {
    language: string;
    autoEnableDocumentTranslation?: boolean;
    autoEnableWordTranslation?: boolean;
};

Parameter TranslationOptions

Nama Jenis Deskripsi
bahasa Untai (karakter) 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: See the Supported Languages section

DisplayOptions

type DisplayOptions = {
    textSize?: number;
    increaseSpacing?: boolean;
    fontFamily?: string;
};

Parameter DisplayOptions

Nama Jenis Deskripsi
textSize Number Menyetel ukuran teks yang dipilih.
peningkatanSpacing Boolean Mengatur apakah penspasian teks dianut atau di luar.
fontFamily Untai (karakter) Mengatur font yang dipilih ("Calibri", "ComicSans", atau "Sitka").
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 yang tercantum di bawah ini 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 Eropa. Jika Anda ingin mengaktifkan kembali cookie dan memulihkan fungsi default untuk preferensi pengguna Immersive Reader, Anda harus memastikan bahwa situs web atau aplikasi Anda mendapatkan persetujuan yang tepat dari pengguna untuk mengaktifkan cookie. Kemudian, untuk mengaktifkan kembali cookie di Immersive Reader, Anda harus secara eksplisit mengatur opsi cookiePolicy ke CookiePolicy.Enable saat meluncurkan Immersive Reader. Tabel di bawah ini menjelaskan pengaturan apa yang disimpan Immersive Reader dalam cookienya saat opsi cookiePolicy diaktifkan.

Parameter Pengaturan

Pengaturan Jenis Deskripsi
textSize Number Menyetel ukuran teks yang dipilih.
fontFamily Untai (karakter) Mengatur font yang dipilih ("Calibri", "ComicSans", atau "Sitka").
textSpacing Number Mengatur apakah penspasian teks dianut atau di luar.
formattingEnabled Boolean Menyetel apakah pemformatan HTML dianut atau di luar.
Tema Untai (karakter) Mengatur tema yang dipilih (misalnya "Cahaya", "Gelap"...).
syllabificationEnabled Boolean Mengatur apakah syllabification akan mengaktifkan atau menonaktifkan.
nounHighlightingEnabled Boolean yang mengatur apakah penyorotan kata benda dianut atau dimatikan.
nounHighlightingColor Untai (karakter) Menyetel warna penyorotan kata benda yang dipilih.
verbHighlightingEnabled Boolean Menyetel apakah penyorotan kata kerja diaktifkan atau dinonaktifkan.
verbHighlightingColor Untai (karakter) Mengatur warna penyorotan kata kerja yang dipilih.
adjectiveHighlightingEnabled Boolean Menyetel apakah penyorotan kata sifat diaktifkan atau dinonaktifkan.
adjectiveHighlightingColor Untai (karakter) Menyetel warna penyorotan kata sifat yang dipilih.
adverbHighlightingEnabled Boolean Menyetel apakah penyorotan kata keterangan diaktifkan atau dinonaktifkan.
adverbHighlightingColor Untai (karakter) 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. Lihat Dukungan Bahasa untuk detail selengkapnya.


Dukungan HTML

Saat pemformatan diaktifkan, konten berikut akan dirender sebagai HTML di Immersive Reader.

HTML Konten yang Didukung
Gaya Font Tebal, Miring, Garis Bawah, Kode, Coret, Superskrip, Subskrip
Daftar Tidak Berurut Cakram, Lingkaran, Persegi
Daftar Berurut Desimal, Upper-Alpha, Lower-Alpha, Upper-Roman, Lower-Roman

Tag yang tidak didukung akan dirender secara sebanding. Gambar dan tabel saat ini tidak didukung.


Dukungan browser

Gunakan versi terbaru browser berikut untuk pengalaman terbaik dengan Immersive Reader.

  • Microsoft Edge
  • Internet Explorer 11
  • Google Chrome
  • Mozilla Firefox
  • Apple Safari

Langkah berikutnya