القارئ الشامل مرجع JavaScript SDK (إصدار 1.4)
يحتوي SDK للقارئ الشامل على مكتبة JavaScript تتيح لك دمج القارئ الشامل في التطبيق الخاص بك.
يمكنك استخدام npmأو yarnأو عنصر HTML <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
الوظائف
تعرض SDK هذه الدالات:
- ImmersiveReader.launchAsync(token, subdomain, content, options)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons (خيارات)
وظيفه: launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options)تشغيل القارئ الشامل داخل عنصر HTML iframe في تطبيق الويب الخاص بك. يقتصر حجم المحتوى الخاص بك على 50 ميجابايت كحد أقصى.
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| المعلمة | النوع | الوصف |
|---|---|---|
| الرمز المميز | سلسلة | رمز مصادقة Microsoft Entra المميز. لمعرفة المزيد، راجع كيفية إنشاء مورد القارئ الشامل. |
| فرعي | سلسلة | المجال الفرعي المخصص لمورد القارئ الشامل في Azure. |
| المحتوى | المحتوى | كائن يحتوي على المحتوى الذي سيتم عرضه في القارئ الشامل. |
| خيارات | الخيارات | خيارات لتكوين سلوكيات معينة خاصة بالقارئ الشامل. اختياري. |
المرتجعات
أعد Promise<LaunchResponse>، والذي يحل عند تحميل القارئ الشامل. يتم Promise حل إلى كائن LaunchResponse .
استثناءات
إذا فشل تحميل القارئ الشامل، يتم رفض الذي تم إرجاعه Promise باستخدام كائن Error.
وظيفه: close
ImmersiveReader.close()إغلاق القارئ الشامل.
مثال على حالة استخدام هذه الدالة في حالة كان زر الخروج مخفيًا عن طريق التعيين hideExitButton: trueفيالخيارات. بعد ذلك، يمكن لزر مختلف (على سبيل المثال، سهم خلفي لعنوان الهاتف المحمول) استدعاء هذه close الدالة عند النقر فوقها.
close(): void;
وظيفه: renderButtons
الدالة ImmersiveReader.renderButtons(options) ليست ضرورية إذا كنت تستخدم إرشادات الزر كيفية تخصيص القارئ الشامل.
تقوم هذه الوظيفة بتصميم وتحديث عناصر زر القارئ الشامل للمستند. إذا options.elements تم توفيرها، فسيتم عرض الأزرار داخل كل عنصر متوفر في options.elements. يعد استخدام المعلمة options.elements مفيدًا عندما يكون لديك أقسام متعددة في المستند الخاص بك لتشغيل القارئ الشامل، وتريد طريقة مبسطة لعرض أزرار متعددة بنفس التصميم، أو تريد عرض الأزرار بنمط تصميم بسيط ومتسق. لاستخدام هذه الدالة مع معلمة خيارات renderButtons، قم باستدعاء ImmersiveReader.renderButtons(options: RenderButtonsOptions); تحميل الصفحة كما هو موضح في القصاصة البرمجية التالية. وإلا، يتم عرض الأزرار داخل عناصر المستند التي تحتوي على الفئة immersive-reader-button كما هو موضح في كيفية تخصيص زر القارئ الشامل.
// 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});
راجع سمات زر التشغيل الاختيارية لمزيد من خيارات العرض. لاستخدام هذه الخيارات، أضف أي من سمات الخيار إلى كل HTMLDivElement منها في صفحة HTML الخاصة بك.
renderButtons(options?: RenderButtonsOptions): void;
| المعلمة | النوع | الوصف |
|---|---|---|
| خيارات | خيارات أزرار العرض | خيارات لتكوين سلوكيات معينة لوظيفة أزرار العرض. اختياري. |
خيارات أزرار العرض
خيارات خاصة لعرض أزرار القارئ الشامل.
{
elements: HTMLDivElement[];
}
| المعلمة | النوع | الوصف |
|---|---|---|
| عناصر | HTMLDivElement[] | عناصر خاصة بعرض أزرار القارئ الشامل فيها. |
Type: HTMLDivElement[]
Required: false
زر التشغيل
يوفر SDK التصميم الافتراضي لزر التشغيل القارئ الشامل. استخدم immersive-reader-button سمة الفئة لتمكين هذا التصميم. لمزيد من المعلومات، راجع كيفية تخصيص زر القارئ الشامل.
<div class='immersive-reader-button'></div>
استخدم السمات الاختيارية التالية لتكوين شكل الزر وأسلوبه.
| السمة | الوصف |
|---|---|
| نمط زر البيانات | يضبط نمط الزر. يمكن أن يكون icon، أو text، أو iconAndText. الإعدادات الافتراضية لـ icon. |
| إعدادات البيانات المحلية | يضبط الإعدادات المحلية. على سبيل المثال: en-US أو fr-FR. الإعدادات الافتراضية إلى اللغةِ الإنجليزية en. |
| أيقونة البيانات-px-size | يضبط حجم الأيقونة بالبكسل. الافتراضيات إلى 20 px. |
LaunchResponse
يتضمن على الاستجابة من الاستدعاء إلى ImmersiveReader.launchAsync. يمكن الوصول إلى مرجع إلى عنصر HTML iframe الذي يحتوي على القارئ الشامل عبر container.firstChild.
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| المعلمة | النوع | الوصف |
|---|---|---|
| حاوية | عنصر HTMLDivEl | عنصر HTML الذي يشتمل على عنصر القارئ الشاملiframe. |
| sessionId | السلسلة | معرّف فريد عمومي خاص بهذه الجلسة، يُستخدم لتصحيح الأخطاء. |
| charactersProcessed | رقم | إجمالي عدد الأحرف المعالجة |
خطأ
يحتوي على معلومات حول خطأ.
{
code: string;
message: string;
}
| المعلمة | النوع | الوصف |
|---|---|---|
| الكود | السلسلة | إحدى مجموعة رموز الخطأ. |
| رسالة | السلسلة | تمثيل للخطأ يمكن قراءته من قبل الإنسان. |
| رمز الخطأ | الوصف |
|---|---|
| BadArgument | الوسيطة المتوفرة غير صحيحة. راجع message معلمة الخطأ. |
| المهلة | فشل القارئ الشامل في التحميل خلال المهلة المحددة. |
| انتهت صلاحية الرمز المميز | انتهاء صلاحية الرمز المميز المتوفر. |
| مقيد | تم تجاوز حد سعر المكالمة. |
الأنواع
المحتوى
يحتوي على المحتوى الذي سيعرض في القارئ الشامل.
{
title?: string;
chunks: Chunk[];
}
| المعلمة | النوع | الوصف |
|---|---|---|
| العنوان | السلسلة | يظهر نص العنوان أعلى القارئ الشامل (اختياري) |
| مجموعات | Chunk[] | صفيف مكون من مجموعات |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
مجموعة
مجموعة واحدة من البيانات، والتي يتم تمريرها إلى محتوى القارئ الشامل.
{
content: string;
lang?: string;
mimeType?: string;
}
| المعلمة | النوع | الوصف |
|---|---|---|
| المحتوى | السلسلة | السلسلة التي تشتمل على المحتوى المرسل إلى القارئ الشامل. |
| lang | السلسلة | لغة النص، القيمة بتنسيق علامة IETF BCP 47 لغة ، على سبيل المثال، en، es-ES. يتم الكشف عن اللغة تلقائيا إذا لم يتم تحديدها. لمزيد من المعلومات، راجع اللغات المدعومة. |
| mimeType | سلسلة | يتم دعم تنسيقات النص العادي، و MathML، و HTML و Microsoft Word DOCX. للمزيد من المعلومات، يرجي مراجعة أنواع الملفات المدعومة. |
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"
أنواع الملفات المدعومة
| نوع MIME | الوصف |
|---|---|
| رسالة نصية/نص عادي | نص عادي. |
| text/html | محتوى HTML. |
| تطبيق/mathml+xml | لغة العلامات الرياضية (MathML). |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | مستندات بتنسيق Microsoft Word. |
الخيارات
يحتوي على خصائص تكون سلوكيات معينة للقارئ الشامل.
{
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;
}
| المعلمة | النوع | الوصف |
|---|---|---|
| اللغة الخاصة بواجهة المستخدم | السلسلة | لغة واجهة المستخدم، القيمة بتنسيق علامة IETF BCP 47 لغة ، على سبيل المثال، en، es-ES. إعدادات افتراضية للغة المتصفح في حالة عدم تحديدها. |
| المهلة | الرقم | المدة (بالمللي ثانية) قبل فشل الإطلاق غير المتزامن مع خطأ انتهاء المهلة (الافتراضي هو 15000 مللي ثانية). لا تنطبق هذه المهلة إلا على الإطلاق الأولي لصفحة القارئ، عندما تفتح صفحة القارئ بنجاح ويبدأ زر الزيادة والنقصان. لا ينبغي أن يكون تعديل المهلة ضروريا. |
| uiZIndex | الرقم | فهرس Z لعنصر HTML iframe الذي تم إنشاؤه (الافتراضي هو 1000). |
| useWebview | Boolean | استخدم علامة عرض الويب بدلا من عنصر HTML iframe ، للتوافق مع تطبيقات Chrome (الافتراضي هو خطأ). |
| onExit | الدالة | ينفذ عند الخروج من القارئ الشامل. |
| مجال مخصص | السلسلة | محجوز للاستخدام الداخلي. مجال مخصص حيث يستضاف القارئ الشامل webapp (الافتراضي فارغ). |
| allowFullscreen | Boolean | القدرة على تبديل وضع ملء الشاشة (الافتراضي هو صحيح). |
| أصل | العقدة | العقدة التي يتم وضع عنصر HTML iframe أو Webview الحاوية فيها. في حالة عدم وجود العنصر، يوضع iframe في body. |
| hideExitButton | Boolean | إخفاء سهم زر خروج القارئ الشامل (الإعداد الافتراضي خطأ). يجب أن تكون هذه القيمة صحيحة فقط إذا كانت هناك آلية بديلة متوفرة للخروج من القارئ الشامل (على سبيل المثال، السهم الخلفي لشريط أدوات المحمول). |
| cookiePolicy | CookiePolicy | إعداد استخدام ملفات تعريف الارتباط الخاصة بالقارئ الشامل (الإعداد الافتراضي هو تعطيل نهج ملفات الارتباط). تقع على عاتق التطبيق المضيف مسؤولية الحصول على أي موافقة ضرورية للمستخدم باتباع نهج الامتثال الخاص بملفات تعريف الارتباط في الاتحاد الأوروبي. لمزيد من المعلومات، راجع خيارات نهج ملف تعريف الارتباط. |
| disableFirstRun | Boolean | عطل تجربة التشغيل الأولى. |
| خيارات القراءة بصوت مسموع | خيارات القراءة بصوت مسموع | خيارات لتكوين القراءة بصوت مسموع. |
| translationOptions | TranslationOptions | خيارات لتكوين الترجمة. |
| displayOptions | خيارات العرض | خيارات لتكوين حجم النص والخط والموضوع وما إلى ذلك. |
| التفضيلات | السلسلة | أعيدت السلسلة من onPreferencesChanged التي تمثل تفضيلات المستخدم في القارئ الشامل. لمزيد من المعلومات، راجع كيفية تخزين تفضيلات المستخدم. |
| onPreferencesChanged | الدالة | ينفذ عندما تتغير تفضيلات المستخدم. لمزيد من المعلومات، راجع كيفية تخزين تفضيلات المستخدم. |
| disableTranslation | Boolean | تعطيل تجربة ترجمة الكلمات والمستندات. |
| تعطيل التدقيق النحوي | Boolean | عطل تجربة التدقيق النحوي. يقوم هذا الخيار أيضا بتعطيل المقاطع وأجزاء الكلام وقاموس الصور، والذي يعتمد على أجزاء من الكلام. |
| disableLanguageDetection | Boolean | عطل اكتشاف عن اللغة للتأكد من أن القارئ الشامل يستخدم اللغة المحددة بشكل صريح في مجموعة المحتوى/[]. يجب استخدام هذا الخيار باعتدال، في المقام الأول في الحالات التي لا يعمل فيها الكشف عن اللغة. على سبيل المثال، من المرجح أن تحدث هذه المشكلة مع مقاطع قصيرة أقل من 100 حرف. يلزم أن تكون متأكدًا من اللغة التي ترسلها، لأن تحويل النص إلى كلام لن يكون له الصوت الصحيح. لا تعمل المقاطع وأجزاء الكلام وقاموس الصور بشكل صحيح إذا لم تكن اللغة صحيحة. |
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
تنبيه
لا تحاول تغيير قيم -preferences السلسلة المرسلة من وإلى تطبيق القارئ الشامل برمجيا لأن هذا قد يتسبب في سلوك غير متوقع يؤدي إلى انخفاض تجربة المستخدم. يجب ألا تقوم التطبيقات المضيفة أبدًا بتعيين قيمة مخصصة -preferencesللسلسلة أو التعامل معها. عند استخدام -preferences خيار السلسلة، استخدم القيمة الدقيقة التي أعيدت فقط من خيار رد الاتصال -onPreferencesChanged.
onPreferencesChanged
Type: Function
Required: false
Default value: null
customDomain
Type: String
Required: false
Default value: null
خيارات القراءة بصوت مسموع
type ReadAloudOptions = {
voice?: string;
speed?: number;
autoplay?: boolean;
};
| المعلمة | النوع | الوصف |
|---|---|---|
| الصوت | السلسلة | الصوت، إما أنثى أو ذكر. ليست كل اللغات تدعم كلا الجنسين. |
| السرعة | الرقم | سرعة التشغيل. يجب أن يكون بين 0.5 و2.5، ضمنا. |
| autoPlay | Boolean | ابدأ القراءة بصوت عالٍ تلقائيًا عند تحميل القارئ الشامل. |
إشعار
نظرًا إلى قيود المتصفح، لا يدعم التشغيل التلقائي في 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;
};
| المعلمة | النوع | الوصف |
|---|---|---|
| اللغة | السلسلة | تعيين لغة الترجمة، تكون القيمة بتنسيق علامة IETF BCP 47 لغة ، على سبيل المثال، fr-FR، es-MX، zh-Hans-CN. مطلوب لتمكين ترجمة الكلمات أو المستندات تلقائيًا. |
| autoEnableDocumentTranslation | Boolean | ترجمة المستند تلقائيًا بالكامل. |
| autoEnableWordTranslation | Boolean | تمكين ترجمة الكلمات تلقائيًا. |
language
Type: String
Required: true
Default value: null
Values available: For more information, see the Supported languages section
ThemeOption
enum ThemeOption { Light, Dark }
خيارات العرض
type DisplayOptions = {
textSize?: number;
increaseSpacing?: boolean;
fontFamily?: string;
themeOption?: ThemeOption
};
| المعلمة | النوع | الوصف |
|---|---|---|
| textSize | الرقم | ضبط حجم النص المختار. |
| increaseSpacing | Boolean | تعيين ما إذا كان سيشغل تباعد النص أو يتوقف تشغيله. |
| مجموعة الخطوط | السلسلة | تعيين الخط المختار (Calibri أو ComicSans أو Sitka). |
| themeOption | ThemeOption | تعيين النسق المختار للقارئ (فاتح، داكن). |
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"
خيارات نهج ملف تعريف الارتباط
enum CookiePolicy { Disable, Enable }
الإعدادات التالية هي لأغراض إعلامية فقط. يخزن القارئ الشامل إعداداته، أو تفضيلات المستخدم، في ملفات تعريف الارتباط. يعمل خيار ملف تعريف الارتباط هذا على تعطيل استخدام ملفات تعريف الارتباط افتراضيًا لاتباع قوانين الامتثال الخاصة بملفات تعريف الارتباط في الاتحاد الأوروبي. إذا كنت ترغب في إعادة تمكين ملفات تعريف الارتباط واستعادة الوظائف الافتراضية لتفضيلات المستخدم القارئ الشامل، يحتاج موقع الويب أو التطبيق إلى موافقة مناسبة من المستخدم لتمكين ملفات تعريف الارتباط. بعد ذلك، لإعادة تمكين ملفات تعريف الارتباط في القارئ الشامل، يجب تعيين خيار نهج ملفات تعريف الارتباط بشكل صريح إلى تعطيل سياسة ملفات تعريف الارتباط عند تشغيل القارئ الشامل.
يصف الجدول التالي الإعدادات التي يخزنها القارئ الشامل في ملف تعريف الارتباط الخاص به عند تمكين خيار cookiePolicy.
| الإعدادات | النوع | الوصف |
|---|---|---|
| textSize | الرقم | ضبط حجم النص المختار. |
| مجموعة الخطوط | السلسلة | تعيين الخط المختار (Calibri أو ComicSans أو Sitka). |
| textSpacing | الرقم | تعيين ما إذا كان سيشغل تباعد النص أو يتوقف تشغيله. |
| تمكين التنسيق | Boolean | تعيين ما إذا كان تنسيق HTML مشغلاً أو متوقفًا عن التشغيل. |
| النسق | السلسلة | تعيين النسق المختار (فاتح، داكن). |
| تمكين المقطع الصوتي | Boolean | تعيين ما إذا كان التبديل المقطعي إلى وضع التشغيل أو الإيقاف. |
| nounHighlightingEnabled | Boolean | لتعيين ما إذا كان يتم تشغيل تمييز الاسم أو إيقاف تشغيله. |
| nounHighlightingColor | السلسلة | تعيين اللون الذي اختير لتمييز الأسماء. |
| verbHighlightingEnabled | Boolean | لتعيين ما إذا كان سيتم تشغيل تمييز الفعل أو إيقاف تشغيله. |
| verbHighlightingColor | السلسلة | تعيين لون لتمييز الفعل المختار. |
| adjectiveHighlightingEnabled | Boolean | يعيّن ما إذا كان سيشغل تمييز الصفة أو يتوقف عن التشغيل. |
| adjectiveHighlightingColor | السلسلة | تعيين لون تمييز للصفة المختار. |
| adverbHighlightingEnabled | Boolean | لتعيين ما إذا كان يشغل تمييز الظرف أو يتوقف تشغيله. |
| adverbHighlightingColor | السلسلة | تعيين لون لتمييز الحال المختار. |
| pictureDictionaryEnabled | Boolean | تعيين ما إذا كان سيشغل القاموس المصور أو يتوقف عن التشغيل. |
| posLabelsEnabled | Boolean | يضبط ما إذا كان سيشغل أو يتوقف تسمية النص المرتفع لكل جزء مميز من الكلام. |
اللغات المدعومة
تدعم ميزة الترجمة في القارئ الشامل لغات متعددة. لمزيد من المعلومات، راجع دعم اللغة.
دعم HTML
عند تمكين التنسيق، يتم عرض المحتوى التالي بتنسيق HTML في القارئ الشامل.
| HTML | المحتوى المدعوم |
|---|---|
| أنماط الخطوط | غامق، مائل، تسطير، تعليمة برمجية، يتوسطه خط، مرتفع، منخفض |
| قوائم غير مرتبة | قرص، دائرة، مربع |
| القوائم المرتبة | عشري، أبجدي علوي، أبجدي سفلي، روماني علوي، روماني سفلي |
يتم عرض العلامات غير المدعومة بشكل مقارنة. تعد الصور والجداول غير مدعومة حاليًا.
دعم المستعرضات
استخدم أحدث الإصدارات من المستعرضات الموضحة أدناه للحصول على أفضل تجربة مع القارئ الشامل.
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari