Referensi SDK JavaScript Immersive Reader (v1.2)

  • Artikel
  • 10 menit untuk membaca

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

Anda dapat menggunakan elemen npm, yarn, atau HTML<script> untuk menyertakan perpustakaan build stabil terbaru dalam aplikasi web:

<script type='text/javascript' src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.2.0.js'></script>

npm install @microsoft/immersive-reader-sdk

yarn add @microsoft/immersive-reader-sdk

Fungsi

SDK memaparkan fungsi:


launchAsync

Meluncurkan Immersive Reader dalam elemen HTMLiframe 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. Untuk informasi selengkapnya, lihat Cara Membuat Sumber Daya Immersive Reader .
subdomain string Subdomain kustom sumber daya Immersive Reader Anda di Azure. Untuk informasi selengkapnya, lihat Cara Membuat Sumber Daya Immersive Reader .
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 fungsi close 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. Untuk informasi selengkapnya, lihat Cara Menyesuaikan tombol Immersive Reader.

<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

Fungsi renderButtons ini tidak diperlukan jika Anda menggunakan panduan Cara Mengkustomisasi tombol 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-button seperti yang ditunjukkan dalam Cara Mengkustomisasi 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 HTMLiframe yang berisi Immersive Reader dapat diakses melalui container.firstChild.

{
    container: HTMLDivElement;
    sessionId: string;
    charactersProcessed: number;
}

Parameter LaunchResponse

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

Kesalahan

Berisi informasi tentang kesalahan.

{
    code: string;
    message: string;
}

Parameter Kesalahan

Pengaturan Jenis Deskripsi
kode Untai (karakter) Salah satu himpunan kode galat. Untuk informasi selengkapnya, 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. 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.
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;
    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 Opsi

Nama Jenis Deskripsi
uiLang Untai (karakter) Bahasa UI, nilainya dalam format tag bahasa IETF BCP 47, misalnya, en, es-ES. Default ke bahasa browser jika tidak ditentukan.
waktu habis Number 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 waktu habis seharusnya tidak diperlukan.
uiZIndex Number Indeks Z dari elemen HTMLiframe yang akan dibuat (defaultnya adalah 1000).
gunakanWebview Boolean Gunakan tag tampilan web alih-alih elemen HTMLiframe untuk kompatibilitas dengan Aplikasi Chrome (defaultnya adalah false).
onExit Fungsi Mengeksekusi ketika Immersive Reader keluar.
kustomDomain Untai (karakter) 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 Node saat elemen HTMLiframe atau kontainer Webview ditempatkan. Jika elemen tidak ada, iframe ditempatkan di body.
hideExitButton Boolean Menyembunyikan panah tombol keluar Immersive Reader (defaultnya adalah false). Nilai ini seharusnya hanya true 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). 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 Untai (karakter) Untai yang dikembalikan dari onPreferencesChanged mewakili preferensi pengguna di Immersive Reader. Untuk informasi selengkapnya, lihatt Parameter Pengaturan danPreferensi Pengguna untuk Cara Menyimpan.
onPreferencesChanged Fungsi Dijalankan ketika preferensi pengguna telah berubah. Untuk informasi selengkapnya, lihat Preferensi Pengguna untuk Cara Menyimpan.
disableTranslation Boolean Menonaktifkan pengalaman terjemahan kata dan dokumen.
disableGrammar Boolean Menonaktifkan pengalaman Grammar. Opsi ini juga akan menonaktifkan Kamus Suku Kata, Kelas Kata, dan Gambar, yang bergantung pada Kelas Kata.
disableLanguageDetection Boolean Menonaktifkan Deteksi Bahasa untuk memastikan Immersive Reader hanya menggunakan bahasa yang ditentukan secara eksplisit pada Content/Chunk[]. Opsi ini harus digunakan dengan bijak, terutama dalam situasi saat deteksi bahasa tidak berfungsi, misalnya, masalah ini kemungkinan besar terjadi pada paragraf pendek yang kurang dari 100 karakter. Anda harus yakin tentang bahasa yang Anda kirim, karena teks ke ucapan tidak akan bersuara dengan benar. Kamus Suku kata, Kelas Kata, dan Gambar tidak akan berfungsi dengan benar jika bahasanya 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

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". Tidak semua bahasa mendukung dua gender.
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) Menetapkan bahasa terjemahan, nilainya dalam format tag IETF BCP 47-bahasa, 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 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").
themeOption ThemeOption Menetapkan 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 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 Uni Eropa. Jika Anda ingin mengaktifkan kembali cookie dan memulihkan fungsi default untuk preferensi pengguna Immersive Reader, Anda harus memastikan bahwa situs web atau aplikasi mendapatkan 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 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 Mengatur apakah penyorotan kata benda diaktifkan atau dinonaktifkan.
nounHighlightingColor Untai (karakter) Mengatur warna penyorotan kata benda yang dipilih.
verbHighlightingEnabled Boolean Mengatur apakah penyorotan kata kerja diaktifkan atau dinonaktifkan.
verbHighlightingColor Untai (karakter) Mengatur warna penyorotan kata kerja yang dipilih.
adjectiveHighlightingEnabled Boolean Mengatur apakah penyorotan kata sifat diaktifkan atau dinonaktifkan.
adjectiveHighlightingColor Untai (karakter) Mengatur warna penyorotan kata sifat yang dipilih.
adverbHighlightingEnabled Boolean Mengatur 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. Untuk informasi selengkapnya, lihat Dukungan Bahasa.


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