JavaScript SDK başvurusu (v1.4) Tam Ekran Okuyucu

2025-05-02

Tam Ekran Okuyucu SDK'sı, Tam Ekran Okuyucu uygulamanızla tümleştirmenizi sağlayan bir JavaScript kitaplığı içerir.

Web uygulamanıza en son kararlı derleme kitaplığını eklemek için , npmveya bir HTML yarn öğesi kullanabilirsiniz<script>:

<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

İşlevler

SDK şu işlevleri kullanıma sunar:

ImmersiveReader.launchAsync(belirteç, alt etki alanı, içerik, seçenekler)
ImmersiveReader.close()
ImmersiveReader.renderButtons(seçenekler)

Fonksiyon: `launchAsync`

ImmersiveReader.launchAsync(token, subdomain, content, options)web uygulamanızdaki bir HTML iframe öğesinde Tam Ekran Okuyucu başlatır. İçeriğinizin boyutu en fazla 50 MB ile sınırlıdır.

launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;

Parametre	Tür	Açıklama
jeton	Dize	Microsoft Entra kimlik doğrulama belirteci. Daha fazla bilgi edinmek için bkz. Tam Ekran Okuyucu kaynağı oluşturma.
alt etki alanı	Dize	Azure'daki Tam Ekran Okuyucu kaynağınızın özel alt etki alanı.
içerik	İçerik	Tam Ekran Okuyucu gösterilecek içeriği içeren bir nesne.
seçenekler	Seçenekler	Tam Ekran Okuyucu belirli davranışlarını yapılandırma seçenekleri. isteğe bağlı.

Döndürülenler

Tam Ekran Okuyucu yüklendiğinde çözümlenen bir Promise<LaunchResponse>döndürür. Bir Promise LaunchResponse nesnesine çözümlenmiş olur.

Özel durumlar

Tam Ekran Okuyucu yüklenemezse, döndürülen Promise bir Error nesnesiyle reddedilir.

Fonksiyon: `close`

ImmersiveReader.close()Tam Ekran Okuyucu kapatır.

Bu işlev için bir örnek kullanım örneği, çıkış düğmesinin seçeneklerde hideExitButton: trueayarlanarak gizlendiği durumlardır. Ardından, tıklandığında farklı bir düğme (örneğin, bir mobil üst bilginin geri oku) bu close işlevi çağırabilir.

close(): void;

Fonksiyon: `renderButtons`

ImmersiveReader.renderButtons(options) Tam Ekran Okuyucu düğmesini özelleştirme kılavuzunu kullanırsanız işlev gerekli değildir.

Bu işlev, belgenin Tam Ekran Okuyucu düğme öğelerini stiller ve güncelleştirir. Sağlanırsa options.elements , düğmeler içinde options.elementssağlanan her öğe içinde işlenir. Parametresini options.elements kullanmak, belgenizde Tam Ekran Okuyucu başlatabileceğiniz birden çok bölüm olduğunda ve aynı stile sahip birden çok düğmeyi işlemek için basitleştirilmiş bir yol istediğinizde veya düğmeleri basit ve tutarlı bir tasarım deseniyle işlemek istediğinizde kullanışlıdır. Bu işlevi renderButtons seçenekleri parametresiyle ImmersiveReader.renderButtons(options: RenderButtonsOptions); Aksi takdirde, düğmeler belgenin Tam Ekran Okuyucu düğmesiniimmersive-reader-buttongösterildiği gibi sınıfı olan öğeleri içinde işlenir.

// 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});

Daha fazla işleme seçeneği için başlatma düğmesine isteğe bağlı özniteliklere bakın. Bu seçenekleri kullanmak için sayfa HTML'nizdeki her HTMLDivElement birine seçenek özniteliklerinden herhangi birini ekleyin.

renderButtons(options?: RenderButtonsOptions): void;

Parametre	Tür	Açıklama
seçenekler	renderButtons seçenekleri	renderButtons işlevinin belirli davranışlarını yapılandırma seçenekleri. isteğe bağlı.

renderButtons seçenekleri

Tam Ekran Okuyucu düğmelerini işleme seçenekleri.

{
    elements: HTMLDivElement[];
}

Parametre	Tür	Açıklama
öğeler	HTMLDivElement[]	Tam Ekran Okuyucu düğmelerini işlemek için öğeler.

Type: HTMLDivElement[]
Required: false

Başlat düğmesi

SDK, Tam Ekran Okuyucu başlatma düğmesi için varsayılan stil sağlar. immersive-reader-button Bu stili etkinleştirmek için sınıf özniteliğini kullanın. Daha fazla bilgi için bkz. Tam Ekran Okuyucu düğmesini özelleştirme.

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

Düğmenin genel görünümünü yapılandırmak için aşağıdaki isteğe bağlı öznitelikleri kullanın.

Öznitelik	Açıklama
veri düğmesi stili	Düğmenin stilini ayarlar. , `icon`veya `text`olabilir`iconAndText`. varsayılan değeridir `icon`.
veri yerel ayarı	Yerel ayarı ayarlar. Örneğin, `en-US` veya `fr-FR`. Varsayılan olarak İngilizce `en`olur.
data-icon-px-size	Simgenin boyutunu piksel cinsinden ayarlar. Varsayılan olarak 20 pikseldir.

LaunchResponse

çağrısından ImmersiveReader.launchAsyncgelen yanıtı içerir. Tam Ekran Okuyucu içeren HTML iframe öğesine başvuruya aracılığıyla container.firstChilderişilebilir.

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

Parametre	Tür	Açıklama
kapsayıcı	HTMLDivElement	Tam Ekran Okuyucu `iframe` öğesini içeren HTML öğesi.
oturumKimliği	Dize	Bu oturum için genel olarak benzersiz tanımlayıcı, hata ayıklama için kullanılır.
charactersProcessed	Numara	İşlenen toplam karakter sayısı

Hata

Bir hata hakkında bilgi içerir.

{
    code: string;
    message: string;
}

Parametre	Tür	Açıklama
kod	Dize	Hata kodları kümesinden biri.
ileti	Dize	Hatanın insan tarafından okunabilir gösterimi.

Hata kodu	Açıklama
BadArgument	Sağlanan bağımsız değişken geçersiz. Hatanın parametresine bakın `message` .
Zaman Aşımı	Tam Ekran Okuyucu belirtilen zaman aşımı içinde yüklenemedi.
Jeton Süresi Doldu	Sağlanan belirtecin süresi doldu.
Kısıtlandı	Çağrı oranı sınırı aşıldı.

Türler

İçerik

Tam Ekran Okuyucu gösterilecek içeriği içerir.

{
    title?: string;
    chunks: Chunk[];
}

Parametre	Tür	Açıklama
başlık	Dize	Tam Ekran Okuyucu üst kısmında gösterilen başlık metni (isteğe bağlı)
öbekler	Öbek[]	Öbek dizisi

`title`

Type: String
Required: false
Default value: "Immersive Reader"

`chunks`

Type: Chunk[]
Required: true
Default value: null

Öbek

Tam Ekran Okuyucu içeriğine geçirilen tek bir veri öbekleri.

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

Parametre	Tür	Açıklama
içerik	Dize	Tam Ekran Okuyucu gönderilen içeriği içeren dize.
Lang	Dize	Metnin dili, değer IETF BCP 47 dil etiketi biçimindedir; örneğin, en, es-ES. Dil belirtilmezse otomatik olarak algılanır. Daha fazla bilgi edinmek için bkz. Desteklenen diller.
MIME türü	Dize	Düz metin, MathML, HTML ve Microsoft Word DOCX biçimleri desteklenir. Daha fazla bilgi için bkz . Desteklenen MIME türleri.

`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"

Desteklenen MIME türleri

MIME türü	Açıklama
düz metin	Düz metin.
metin/html	HTML içeriği.
application/mathml+xml	Matematiksel İşaretlemeyi Dili (MathML).
application/vnd.openxmlformats-officedocument.wordprocessingml.document	Microsoft Word .docx belgeyi biçimlendirin.

Seçenekler

Tam Ekran Okuyucu belirli davranışlarını yapılandıran özellikler içerir.

{
    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;
}

Parametre	Tür	Açıklama
uiLang	Dize	Kullanıcı arabiriminin dili, değer IETF BCP 47 dil etiketi biçimindedir; örneğin, en, es-ES. Belirtilmezse varsayılan olarak tarayıcı dilini kullanır.
zaman aşımı	Sayı	Başlatmadan önceki süre (milisaniye cinsinden)Async bir zaman aşımı hatasıyla başarısız oluyor (varsayılan değer 15.000 ms'dir). Bu zaman aşımı yalnızca Okuyucu sayfası başarıyla açıldığında ve değiştirici başlatıldığında Okuyucu sayfasının ilk başlatılması için geçerlidir. Zaman aşımının ayarlanması gerekli olmamalıdır.
uiZIndex	Sayı	Oluşturulan HTML `iframe` öğesinin Z dizini (varsayılan değer 1000'dir).
useWebview	Boolean (Boole Mantığı)	Chrome Uygulamaları ile uyumluluk için HTML `iframe` öğesi yerine web görünümü etiketi kullanın (varsayılan değer false'tur).
onExit	İşlev	Tam Ekran Okuyucu çıktığında yürütülür.
customDomain	Dize	dahili kullanım için ayrılmıştır. Tam Ekran Okuyucu web uygulamasının barındırıldığı özel etki alanı (varsayılan değer null).
allowFullscreen	Boolean (Boole Mantığı)	Tam ekranda geçiş yapma özelliği (varsayılan değer true'dur).
ana	Düğüm	HTML `iframe` öğesinin veya `Webview` kapsayıcının yerleştirildiği düğüm. Öğesi yoksa, iframe içine `body`yerleştirilir.
hideExitButton	Boolean (Boole Mantığı)	Tam Ekran Okuyucu çıkış düğmesi okunu gizler (varsayılan değer false'tur). Bu değer yalnızca Tam Ekran Okuyucu çıkmak için sağlanan alternatif bir mekanizma varsa (örneğin, bir mobil araç çubuğunun geri oku) doğru olmalıdır.
cookiePolicy	CookiePolicy	Tam Ekran Okuyucu tanımlama bilgisi kullanımı ayarı (varsayılan ayar CookiePolicy.Disable'tır). AB Tanımlama Bilgisi Uyumluluk İlkesi'nin ardından gerekli kullanıcı onayını almak konak uygulamanın sorumluluğundadır. Daha fazla bilgi için bkz . Tanımlama Bilgisi İlkesi seçenekleri.
disableFirstRun	Boolean (Boole Mantığı)	İlk çalıştırma deneyimini devre dışı bırakın.
readAloudOptions	ReadAloudOptions	Sesli Okuma'ya yapılandırma seçenekleri.
translationOptions	TranslationOptions	Çeviriyi yapılandırma seçenekleri.
displayOptions	DisplayOptions	Metin boyutunu, yazı tipini, temayı vb. yapılandırma seçenekleri.
Tercihler	Dize	Tam Ekran Okuyucu kullanıcının tercihlerini temsil eden onPreferencesChanged öğesinden döndürülen dize. Daha fazla bilgi için bkz . Kullanıcı tercihlerini depolama.
onPreferencesChanged	İşlev	Kullanıcının tercihleri değiştiğinde yürütülür. Daha fazla bilgi için bkz . Kullanıcı tercihlerini depolama.
disableTranslation	Boolean (Boole Mantığı)	Sözcük ve belge çevirisi deneyimini devre dışı bırakın.
disableGrammar	Boolean (Boole Mantığı)	Dil bilgisi deneyimini devre dışı bırakın. Bu seçenek heceleri, Konuşma Bölümleri'ni ve Konuşma Bölümleri'ne bağlı olan Resim Sözlüğü'ni de devre dışı bırakır.
disableLanguageDetection	Boolean (Boole Mantığı)	Tam Ekran Okuyucu yalnızca İçerik/ üzerinde açıkça belirtilen dili kullandığından emin olmak için Dil Algılamayı devre dışı bırakın. Bu seçenek, öncelikle dil algılamanın çalışmadığı durumlarda tedbirli bir şekilde kullanılmalıdır. Örneğin, bu sorun 100 karakterden daha az kısa pasajlarla gerçekleşme olasılığı daha yüksektir. Metin okuma doğru sese sahip olmayacağından, gönderdiğiniz dilden emin olmanız gerekir. Heceler, Konuşma Bölümleri ve Resim Sözlüğü dil doğru değilse düzgün çalışmaz.

`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

Dikkat

Tam Ekran Okuyucu uygulamasına gönderilen ve uygulamadan gönderilen dizenin -preferences değerlerini program aracılığıyla değiştirmeyin, çünkü bu beklenmeyen bir davranışa neden olabilir ve bu da kullanıcı deneyiminin düşmesine neden olabilir. Konak uygulamaları hiçbir zaman dizeye özel bir değer atamamalı veya dizeyi -preferences işlememelidir. Dize seçeneğini kullanırken -preferences , yalnızca geri arama seçeneğinden -onPreferencesChanged döndürülen tam değeri kullanın.

`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;
};

Parametre	Tür	Açıklama
ses	Dize	Ses, kadın ya da erkek. Tüm diller her iki cinsiyeti de desteklemez.
Hız	Sayı	Kayıttan yürütme hızı. 0,5 ile 2,5 (dahil) arasında olmalıdır.
autoPlay	Boolean (Boole Mantığı)	Tam Ekran Okuyucu yüklendiğinde Sesli Okuma'ya otomatik olarak başlayın.

Not

Tarayıcı sınırlamaları nedeniyle Safari'de otomatik yürütme desteklenmez.

`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;
};

Parametre	Tür	Açıklama
dil	Dize	Çeviri dilini ayarlar, değer IETF BCP 47 dil etiketi biçimindedir, örneğin fr-FR, es-MX, zh-Hans-CN. Sözcük veya belge çevirisini otomatik olarak etkinleştirmek için gereklidir.
autoEnableDocumentTranslation	Boolean (Boole Mantığı)	Belgenin tamamını otomatik olarak çevirin.
autoEnableWordTranslation	Boolean (Boole Mantığı)	Sözcük çevirisini otomatik olarak etkinleştirin.

`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
};

Parametre	Tür	Açıklama
textSize	Sayı	Seçilen metin boyutunu ayarlar.
increaseSpacing	Boolean (Boole Mantığı)	Metin aralığının açık mı yoksa kapalı mı olduğunu ayarlar.
fontFamily	Dize	Seçilen yazı tipini (Calibri, ComicSans veya Sitka) ayarlar.
themeOption	ThemeOption	Okuyucunun seçili temasını ayarlar (Açık, Koyu).

`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"

CookiePolicy seçenekleri

enum CookiePolicy { Disable, Enable }

Aşağıdaki ayarlar yalnızca bilgilendirme amaçlıdır. Tam Ekran Okuyucu ayarlarını veya kullanıcı tercihlerini tanımlama bilgilerinde depolar. Bu cookiePolicy seçeneği , AB Çerez Uyumluluğu yasalarına uymak için tanımlama bilgilerinin kullanımını varsayılan olarak devre dışı bırakır . Tanımlama bilgilerini yeniden etkinleştirmek ve Tam Ekran Okuyucu kullanıcı tercihleri için varsayılan işlevselliği geri yüklemek istiyorsanız, web sitenizin veya uygulamanızın tanımlama bilgilerini etkinleştirmek için kullanıcıdan uygun onay alması gerekir. Ardından, Tam Ekran Okuyucu tanımlama bilgilerini yeniden etkinleştirmek için, Tam Ekran Okuyucu başlatırken cookiePolicy seçeneğini cookiePolicy.Enable olarak açıkça ayarlamanız gerekir.

Aşağıdaki tabloda, cookiePolicy seçeneği etkinleştirildiğinde Tam Ekran Okuyucu tanımlama bilgisinde hangi ayarların depolandığı açıklanmaktadır.

Ayar	Tür	Açıklama
textSize	Sayı	Seçilen metin boyutunu ayarlar.
fontFamily	Dize	Seçilen yazı tipini (Calibri, ComicSans veya Sitka) ayarlar.
textSpacing	Sayı	Metin aralığının açık mı yoksa kapalı mı olduğunu ayarlar.
formattingEnabled	Boolean (Boole Mantığı)	HTML biçimlendirmenin açık mı yoksa kapalı mı olduğunu ayarlar.
tema	Dize	Seçilen temayı ayarlar (Açık, Koyu).
syllabificationEnabled	Boolean (Boole Mantığı)	Stil oluşturmanın açılıp kapatılmayacağını ayarlar.
nounHighlightingEnabled	Boolean (Boole Mantığı)	İsim vurgulamanın açık mı yoksa kapalı mı olduğunu ayarlar.
nounHighlightingColor	Dize	Seçilen isim vurgulama rengini ayarlar.
verbHighlightingEnabled	Boolean (Boole Mantığı)	Fiil vurgulamanın açık mı yoksa kapalı mı olduğunu ayarlar.
verbHighlightingColor	Dize	Seçilen fiil vurgulama rengini ayarlar.
sıfatHighlightingEnabled	Boolean (Boole Mantığı)	Sıfat vurgulamanın açık mı yoksa kapalı mı olduğunu ayarlar.
sıfatHighlightingColor	Dize	Seçilen sıfat vurgulama rengini ayarlar.
adverbHighlightingEnabled	Boolean (Boole Mantığı)	Saldırgan vurgulamanın açık mı yoksa kapalı mı olduğunu ayarlar.
adverbHighlightingColor	Dize	Seçilen ters vurgulama rengini ayarlar.
pictureDictionaryEnabled	Boolean (Boole Mantığı)	Resim Sözlüğü'ne geçiş yapılıp yapılmayacağını ayarlar.
posLabelsEnabled	Boolean (Boole Mantığı)	Vurgulanan Konuşma Bölümünün üst simge metin etiketinin açık mı yoksa kapalı mı olduğunu ayarlar.

Desteklenen diller

Tam Ekran Okuyucu'nin çeviri özelliği birçok dili destekler. Daha fazla bilgi için bkz . Dil desteği.

HTML desteği

Biçimlendirme etkinleştirildiğinde, aşağıdaki içerik Tam Ekran Okuyucu HTML olarak işlenir.

HTML	Desteklenen içerik
Yazı tipi stilleri	Kalın, italik, alt çizgi, kod, üstü çizili, üst simge, alt simge
Sırasız listeler	Disk, daire, kare
Sıralı listeler	Ondalık, üst-Alfa, alt-Alfa, üst-Romen, alt-Romen

Desteklenmeyen etiketler benzer şekilde işlenir. Görüntüler ve tablolar şu anda desteklenmiyor.

Tarayıcı desteği

Tam Ekran Okuyucu en iyi deneyim için aşağıdaki tarayıcıların en son sürümlerini kullanın.

Microsoft Edge
Google Chrome
Mozilla Firefox
Apple Safari

Sonraki adım

Tam Ekran Okuyucu SDK'sını keşfetme

Aracılığıyla paylaş

JavaScript SDK başvurusu (v1.4) Tam Ekran Okuyucu

İşlevler

Fonksiyon: launchAsync

Döndürülenler

Özel durumlar

Fonksiyon: close

Fonksiyon: renderButtons

renderButtons seçenekleri

Başlat düğmesi

LaunchResponse

Hata

Türler

İçerik

title

chunks

Öbek

content

lang

mimeType

Desteklenen MIME türleri

Seçenekler

uiLang

timeout

uiZIndex

onExit

preferences

onPreferencesChanged

customDomain