إشعار
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تسجيل الدخول أو تغيير الدلائل.
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تغيير الدلائل.
يحتوي Immersive Reader SDK على مكتبة JavaScript تسمح لك بدمج Immersive Reader في التطبيق الخاص بك.
يمكنك استخدام 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 إرجاعه باستخدام كائن خطأ .
دالة: 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;
| البارامتر | النوع | وصف |
|---|---|---|
| خيارات | خيارات أزرار العرض | خيارات لتكوين سلوكيات معينة لدالة renderButtons. اختياري. |
خيارات أزرار العرض
خيارات لعرض أزرار القارئ الشامل.
{
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;
}
| البارامتر | النوع | وصف |
|---|---|---|
| وعاء | HTMLDivElement | عنصر HTML الذي يحتوي على عنصر القارئ iframe الشامل. |
| معرف جلسة العمل | سلسلة | معرف فريد عمومي لجلسة العمل هذه، يستخدم لتصحيح الأخطاء. |
| الأحرف المعالجة | رقم | إجمالي عدد الأحرف التي تمت معالجتها |
خطأ
يحتوي على معلومات حول خطأ.
{
code: string;
message: string;
}
| البارامتر | النوع | وصف |
|---|---|---|
| رمز | سلسلة | واحدة من مجموعة من رموز الخطأ. |
| رسالة | سلسلة | تمثيل للخطأ يمكن قراءته من قبل الإنسان. |
| رمز الخطأ | وصف |
|---|---|
| BadArgument | الوسيطة المتوفرة غير صحيحة. راجع message معلمة الخطأ. |
| مهله | فشل تحميل القارئ الشامل خلال المهلة المحددة. |
| انتهت صلاحية الرمز المميز | انتهت صلاحية الرمز المميز الذي تم توفيره. |
| مخنوق | تم تجاوز حد معدل المكالمة. |
الأنواع
محتوى
يحتوي على المحتوى الذي سيتم عرضه في القارئ الشامل.
{
title?: string;
chunks: Chunk[];
}
| البارامتر | النوع | وصف |
|---|---|---|
| عنوان | سلسلة | نص العنوان المعروض في أعلى القارئ الشامل (اختياري) |
| قطع | مجموعة[] | صفيف من المجموعات |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
قطعه
مجموعة واحدة من البيانات، والتي يتم تمريرها إلى محتوى القارئ الشامل.
{
content: string;
lang?: string;
mimeType?: string;
}
| البارامتر | النوع | وصف |
|---|---|---|
| محتوى | سلسلة | السلسلة التي تحتوي على المحتوى المرسل إلى القارئ الشامل. |
| لانغ | سلسلة | لغة النص، القيمة بتنسيق علامة IETF BCP 47 لغة ، على سبيل المثال، en، es-ES. يتم الكشف عن اللغة تلقائيا إذا لم يتم تحديدها. لمزيد من المعلومات، راجع اللغات المدعومة. |
| mimeType | خيط | يتم دعم تنسيقات النص العادي، و MathML، و HTML و Microsoft Word DOCX. لمزيد من المعلومات، راجع أنواع MIME المدعومة. |
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 المدعومة
| نوع MIME | وصف |
|---|---|
| رسالة نصية/نص عادي | نص عادي. |
| نص/html | محتوى HTML. |
| application/mathml+xml | لغة العلامات الرياضية (MathML). |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | تنسيق مستند Microsoft Word .docx. |
الخيارات
يحتوي على خصائص تقوم بتكوين سلوكيات معينة للقارئ الشامل.
{
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;
}
| البارامتر | النوع | وصف |
|---|---|---|
| uiLang | سلسلة | لغة واجهة المستخدم، القيمة بتنسيق علامة IETF BCP 47 لغة ، على سبيل المثال، en، es-ES. الإعدادات الافتراضية للغة المستعرض إذا لم يتم تحديدها. |
| مهله | رقم | المدة (بالمللي ثانية) قبل فشل launchAsync مع خطأ انتهاء المهلة (الافتراضي هو 15000 مللي ثانية). تنطبق هذه المهلة فقط على التشغيل الأولي لصفحة القارئ، عندما تفتح صفحة القارئ بنجاح ويبدأ المغزل. لا ينبغي أن يكون تعديل المهلة ضروريا. |
| uiZIndex | رقم | فهرس Z لعنصر HTML iframe الذي تم إنشاؤه (الافتراضي هو 1000). |
| استخدامWebview | منطقي | استخدم علامة عرض الويب بدلا من عنصر HTML iframe ، للتوافق مع تطبيقات Chrome (الافتراضي هو خطأ). |
| onExit | الدالة | يتم التنفيذ عند إنهاء القارئ الشامل. |
| مجال مخصص | سلسلة | محجوز للاستخدام الداخلي. مجال مخصص حيث تتم استضافة تطبيق الويب Immersive Reader (الافتراضي فارغ). |
| شاشة allowFull | منطقي | القدرة على تبديل ملء الشاشة (الافتراضي صحيح). |
| الوالد | كعب | العقدة التي يتم وضع عنصر HTML iframe أو Webview الحاوية فيها. إذا لم يكن العنصر موجودا، يتم وضع iframe في body. |
| hideExitButton | منطقي | إخفاء سهم زر الخروج للقارئ الشامل (الافتراضي خطأ). يجب أن تكون هذه القيمة صحيحة فقط إذا كانت هناك آلية بديلة متوفرة للخروج من القارئ الشامل (على سبيل المثال، السهم الخلفي لشريط أدوات المحمول). |
| نهج ملف تعريف الارتباط | نهج ملف تعريف الارتباط | إعداد استخدام ملفات تعريف الارتباط للقارئ الشامل (الافتراضي هو CookiePolicy.Disable). تقع على عاتق التطبيق المضيف مسؤولية الحصول على أي موافقة مستخدم ضرورية بعد سياسة الامتثال لملفات تعريف الارتباط في الاتحاد الأوروبي. لمزيد من المعلومات، راجع خيارات نهج ملف تعريف الارتباط. |
| disableFirstRun | منطقي | تعطيل تجربة التشغيل الأولى. |
| readAloudOptions | ReadAloudOptions | خيارات لتكوين القراءة بصوت عال. |
| عمليات الترجمة | عمليات الترجمة | خيارات لتكوين الترجمة. |
| خيارات العرض | خيارات العرض | خيارات لتكوين حجم النص والخط والنسق وما إلى ذلك. |
| التفضيلات | سلسلة | تم إرجاع السلسلة من onPreferencesChanged التي تمثل تفضيلات المستخدم في القارئ الشامل. لمزيد من المعلومات، راجع كيفية تخزين تفضيلات المستخدم. |
| onPreferencesChanged | الدالة | يتم التنفيذ عند تغيير تفضيلات المستخدم. لمزيد من المعلومات، راجع كيفية تخزين تفضيلات المستخدم. |
| تعطيل التحويل | منطقي | تعطيل تجربة ترجمة الكلمة والمستند. |
| تعطيلGrammar | منطقي | تعطيل تجربة التدقيق النحوي. يقوم هذا الخيار أيضا بتعطيل المقاطع وأجزاء الكلام وقاموس الصور، والذي يعتمد على أجزاء من الكلام. |
| تعطيلLanguageDetection | منطقي | قم بتعطيل الكشف عن اللغة للتأكد من أن القارئ الشامل يستخدم فقط اللغة المحددة بشكل صريح في مجموعة المحتوى/[]. يجب استخدام هذا الخيار باعتدال، في المقام الأول في الحالات التي لا يعمل فيها الكشف عن اللغة. على سبيل المثال، من المرجح أن تحدث هذه المشكلة مع مقاطع قصيرة أقل من 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
ReadAloudOptions
type ReadAloudOptions = {
voice?: string;
speed?: number;
autoplay?: boolean;
};
| البارامتر | النوع | وصف |
|---|---|---|
| صوت | سلسلة | الصوت، إما أنثى أو ذكر. لا تدعم كل اللغات كلا الجنسين. |
| سرعة | رقم | سرعة التشغيل. يجب أن يكون بين 0.5 و2.5، ضمنا. |
| التشغيل التلقائي | منطقي | بدء القراءة بصوت عال تلقائيا عند تحميل القارئ الشامل. |
ملاحظة
نظرا لقيود المستعرض، لا يتم دعم التشغيل التلقائي في 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
عمليات الترجمة
type TranslationOptions = {
language: string;
autoEnableDocumentTranslation?: boolean;
autoEnableWordTranslation?: boolean;
};
| البارامتر | النوع | وصف |
|---|---|---|
| اللغة | سلسلة | تعيين لغة الترجمة، تكون القيمة بتنسيق علامة IETF BCP 47 لغة ، على سبيل المثال، fr-FR، es-MX، zh-Hans-CN. مطلوب لتمكين ترجمة الكلمة أو المستند تلقائيا. |
| autoEnableDocumentTranslation | منطقي | ترجمة المستند بأكمله تلقائيا. |
| autoEnableWordTranslation | منطقي | تمكين ترجمة الكلمات تلقائيا. |
language
Type: String
Required: true
Default value: null
Values available: For more information, see the Supported languages section
نسق النسق
enum ThemeOption { Light, Dark }
خيارات العرض
type DisplayOptions = {
textSize?: number;
increaseSpacing?: boolean;
fontFamily?: string;
themeOption?: ThemeOption
};
| البارامتر | النوع | وصف |
|---|---|---|
| حجم النص | رقم | تعيين حجم النص المختار. |
| زيادةSpacing | منطقي | تعيين ما إذا كان يتم تشغيل تباعد النص أو إيقاف تشغيله. |
| fontFamily | سلسلة | تعيين الخط المختار (Calibri أو ComicSans أو Sitka). |
| نسقOption | نسق النسق | تعيين النسق المختار للقارئ (فاتح، داكن). |
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 هذا استخدام ملفات تعريف الارتباط بشكل افتراضي لاتباع قوانين التوافق مع ملفات تعريف الارتباط في الاتحاد الأوروبي. إذا كنت ترغب في إعادة تمكين ملفات تعريف الارتباط واستعادة الوظيفة الافتراضية لتفضيلات مستخدم القارئ الشامل، يحتاج موقع الويب أو التطبيق إلى موافقة مناسبة من المستخدم لتمكين ملفات تعريف الارتباط. بعد ذلك، لإعادة تمكين ملفات تعريف الارتباط في القارئ الشامل، يجب تعيين خيار cookiePolicy بشكل صريح إلى CookiePolicy.Enable عند تشغيل Immersive Reader.
يصف الجدول التالي الإعدادات التي يخزنها القارئ الشامل في ملف تعريف الارتباط الخاص به عند تمكين خيار cookiePolicy .
| اعداد | النوع | وصف |
|---|---|---|
| حجم النص | رقم | تعيين حجم النص المختار. |
| fontFamily | سلسلة | تعيين الخط المختار (Calibri أو ComicSans أو Sitka). |
| textSpacing | رقم | تعيين ما إذا كان يتم تشغيل تباعد النص أو إيقاف تشغيله. |
| formattingEnabled | منطقي | تعيين ما إذا كان تنسيق HTML قيد التشغيل أو إيقاف التشغيل. |
| النسق | سلسلة | تعيين النسق المختار (فاتح، داكن). |
| syllabificationEnabled | منطقي | تعيين ما إذا كان أسلوب المناهج متبولا أو متوقفا عن التشغيل. |
| nounHighlightingEnabled | منطقي | تعيين ما إذا كان يتم تشغيل تمييز الاسم أو إيقاف تشغيله. |
| nounHighlightingColor | سلسلة | تعيين لون تمييز الاسم المختار. |
| verbHighlightingEnabled | منطقي | تعيين ما إذا كان التمييز الفعلي قد تم تبديله أو إيقاف تشغيله. |
| verbHighlightingColor | سلسلة | تعيين لون تمييز الفعل المختار. |
| adjectiveHighlightingEnabled | منطقي | تعيين ما إذا كان يتم تشغيل تمييز الصفة أو إيقاف تشغيله. |
| adjectiveHighlightingColor | سلسلة | تعيين لون تمييز الصفة المختار. |
| adverbHighlightingEnabled | منطقي | تعيين ما إذا كان يتم تشغيل تمييز adverb أو إيقاف تشغيله. |
| adverbHighlightingColor | سلسلة | تعيين لون تمييز adverb المختار. |
| pictureDictionaryEnabled | منطقي | تعيين ما إذا كان تم تشغيل "قاموس الصور" أو إيقاف تشغيله. |
| posLabelsEnabled | منطقي | تعيين ما إذا كان يتم تبديل تسمية النص المرتفع لكل جزء من "الكلام" المميز أو إيقاف تشغيله. |
اللغات المدعومة
تدعم ميزة الترجمة في Immersive Reader العديد من اللغات. لمزيد من المعلومات، راجع دعم اللغة.
دعم HTML
عند تمكين التنسيق، يتم عرض المحتوى التالي بتنسيق HTML في القارئ الشامل.
| HTML | المحتوى المدعوم |
|---|---|
| أنماط الخطوط | غامق، مائل، تسطير، تعليمة برمجية، يتوسطه خط، مرتفع، منخفض |
| قوائم غير مرتبة | قرص، دائرة، مربع |
| القوائم المرتبة | عشري، أبجدي علوي، أبجدي سفلي، روماني علوي، روماني سفلي |
يتم عرض العلامات غير المدعومة بشكل مقارنة. الصور والجداول غير معتمدة حاليا.
دعم المستعرض
استخدم أحدث إصدارات المستعرضات التالية للحصول على أفضل تجربة مع القارئ الشامل.
- Microsoft Edge
- Google Chrome
- موزيلا فايرفوكس
- Apple Safari