JavaScript SDK başvurusu (v1.4) Tam Ekran Okuyucu
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 , yarnveya bir HTML <script> öğesi kullanabilirsiniznpm:
<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)
Işlev: 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 |
|---|---|---|
| token | Dize | Microsoft Entra kimlik doğrulama belirteci. Daha fazla bilgi edinmek için bkz. Tam Ekran Okuyucu kaynağı oluşturma. |
| Alt | Dize | Azure'daki Tam Ekran Okuyucu kaynağınızın özel alt etki alanı. |
| content | İç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.
Işlev: close
ImmersiveReader.close()Tam Ekran Okuyucu kapatır.
Bu işlev için bir örnek kullanım örneği, çıkış düğmesinin seçeneklerde ayarlanarak hideExitButton: true 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;
Işlev: 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 kullanmak için, aşağıdaki kod parçacığında gösterildiği gibi sayfa yüklemesini çağırınImmersiveReader.renderButtons(options: RenderButtonsOptions);. Aksi takdirde, düğmeler belgenin Tam Ekran Okuyucu düğmesini özelleştirme bölümünde gösterildiği gibi sınıfı immersive-reader-button 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. , textveya iconAndTextolabiliricon. varsayılan değeridir icon. |
| veri yerel ayarı | Yerel ayarı ayarlar. Örneğin, en-US veya fr-FR. Varsayılan olarak İngilizce enolur. |
| 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. |
| sessionId | String | 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 | String | Hata kodları kümesinden biri. |
| ileti | String | 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 . |
| Timeout | Tam Ekran Okuyucu belirtilen zaman aşımı içinde yüklenemedi. |
| TokenExpired | Sağlanan belirtecin süresi doldu. |
| Kısıtlandı | Çağrı oranı sınırı aşıldı. |
Türler
Content
Tam Ekran Okuyucu gösterilecek içeriği içerir.
{
title?: string;
chunks: Chunk[];
}
| Parametre | Tür | Açıklama |
|---|---|---|
| başlık | String | 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 |
|---|---|---|
| content | String | Tam Ekran Okuyucu gönderilen içeriği içeren dize. |
| Lang | String | 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. |
| Mimetype | 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 |
|---|---|
| text/plain | Düz metin. |
| text/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 | String | 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. |
| timeout | 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 | 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 | String | 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 | 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 bodyyerleştirilir. |
| hideExitButton | Boolean | 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 | İ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 | String | 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 | Sözcük ve belge çevirisi deneyimini devre dışı bırakın. |
| disableGrammar | Boolean | 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 | Tam Ekran Okuyucu yalnızca İçerik/Öbekleri[] ü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 |
|---|---|---|
| voice | String | 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 | 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 | String | Ç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 | Belgenin tamamını otomatik olarak çevirin. |
| autoEnableWordTranslation | Boolean | 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 |
|---|---|---|
| Textsıze | Sayı | Seçilen metin boyutunu ayarlar. |
| increaseSpacing | Boolean | Metin aralığının açık mı yoksa kapalı mı olduğunu ayarlar. |
| Fontfamily | String | 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 | Type | Açıklama |
|---|---|---|
| Textsıze | Sayı | Seçilen metin boyutunu ayarlar. |
| Fontfamily | String | 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 | HTML biçimlendirmenin açık mı yoksa kapalı mı olduğunu ayarlar. |
| tema | String | Seçilen temayı ayarlar (Açık, Koyu). |
| syllabificationEnabled | Boolean | Stil oluşturmanın açılıp kapatılmayacağını ayarlar. |
| nounHighlightingEnabled | Boolean | İsim vurgulamanın açık mı yoksa kapalı mı olduğunu ayarlar. |
| nounHighlightingColor | String | Seçilen isim vurgulama rengini ayarlar. |
| verbHighlightingEnabled | Boolean | Fiil vurgulamanın açık mı yoksa kapalı mı olduğunu ayarlar. |
| verbHighlightingColor | String | Seçilen fiil vurgulama rengini ayarlar. |
| sıfatHighlightingEnabled | Boolean | Sıfat vurgulamanın açık mı yoksa kapalı mı olduğunu ayarlar. |
| sıfatHighlightingColor | String | Seçilen sıfat vurgulama rengini ayarlar. |
| adverbHighlightingEnabled | Boolean | Saldırgan vurgulamanın açık mı yoksa kapalı mı olduğunu ayarlar. |
| adverbHighlightingColor | String | Seçilen ters vurgulama rengini ayarlar. |
| pictureDictionaryEnabled | Boolean | Resim Sözlüğü'ne geçiş yapılıp yapılmayacağını ayarlar. |
| posLabelsEnabled | Boolean | 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