blockly > FocusManager

فئة FocusManager

عنصر أحادي النسخة لكل صفحة يدير تركيز Blockly على مستوى شجرة واحدة أو أكثر من أشجار IFocusableTree، ويتم مزامنة هذا التركيز بشكل ثنائي الاتجاه مع نموذج المستند (DOM).

على المتصلين الذين يريدون تغيير تركيز الإدخال بشكل صريح لمكوّنات Blockly محدّدة على الصفحة استخدام دوال التركيز في هذا المدير.

يكون المدير مسؤولاً عن معالجة أحداث التركيز من نموذج المستند (DOM) (التي قد تنشأ من نقر المستخدمين على عناصر الصفحة) والتأكّد من أنّ عقد IFocusableNode المقابلة يتم تمييزها بوضوح على أنّها مميّزة بشكل نشط أو غير نشط بالطريقة نفسها التي سيتم تمثيلها بها من خلال طلبات إلى focusNode().

Signature:

export declare class FocusManager 

الشركات المصنِّعة

الشركة المصنِّعة	مفاتيح التعديل	الوصف
(constructor)(addGlobalEventListener)		تنشئ هذه الدالة مثيلاً جديدًا لفئة FocusManager

الخصائص

الموقع	مفاتيح التعديل	النوع	الوصف
ACTIVE_FOCUS_NODE_CSS_CLASS_NAME	static readonly	(لم يتم الإفصاح عنها)	فئة CSS المعيّنة لعناصر IFocusableNode التي تتضمّن حاليًا تركيزًا نشطًا على DOM وBlockly يجب عدم استخدامها مباشرةً أبدًا. بدلاً من ذلك، اعتمد على FocusManager للتأكّد من أنّ العُقد لديها تركيز نشط (إما تلقائيًا من خلال تركيز DOM أو يدويًا من خلال طرق focus* المختلفة التي توفّرها هذه الفئة). ننصحك أيضًا بعدم إجراء طلب بحث باستخدام اسم الفئة هذا. بدلاً من ذلك، استخدِم FocusableTreeTraverser أو طرق IFocusableTree للعثور على عقدة معيّنة.
PASSIVE_FOCUS_NODE_CSS_CLASS_NAME	static readonly	(لم يتم الإفصاح عنها)	فئة CSS المعيّنة لعناصر IFocusableNode التي تركّز حاليًا بشكل غير مباشر (أي أنّها كانت آخر عقدة في شجرتها النسبية التي تركّز بشكل مباشر، راجِع ACTIVE_FOCUS_NODE_CSS_CLASS_NAME، وستركّز بشكل مباشر مرة أخرى إذا طُلب من شجرتها المحيطة أن تصبح مركّزة، أي باستخدام focusTree أدناه). راجِع ACTIVE_FOCUS_NODE_CSS_CLASS_NAME للاطّلاع على التحذيرات والقيود المتعلقة باستخدام هذا الثابت مباشرةً (بشكل عام، لا يجب استخدامه مطلقًا).

الطُرق

الطريقة	مفاتيح التعديل	الوصف
ephemeralFocusTaken()
focusNode(focusableNode)		يركّز إدخال DOM على العقدة المحدّدة، ويضع علامة عليها كعنصر نشط. سيتم تعديل أي عقدة تم التركيز عليها سابقًا لتصبح مميّزة بشكل غير نشط (إذا كانت في شجرة قابلة للتركيز مختلفة) أو غير واضحة (إذا كانت في الشجرة نفسها). **ملاحظة مهمة**: إذا تعذّر التركيز على العقدة المقدَّمة (مثلاً، إذا عرضت الدالة canBeFocused() القيمة "خطأ")، سيتم تجاهلها وستبقى حالة التركيز الحالية بدون تغيير. يُرجى العِلم أنّ هذا الإجراء قد يعدّل قيمة tabindex للعنصر المحدّد في العقدة لضمان أن تتمكّن برامج قراءة الشاشة من قراءته بشكل صحيح عند التركيز عليه.
focusTree(focusableTree)		يركّز على IFocusableTree المحدّد. يعني ذلك إما استعادة التركيز النشط إلى العقدة التي تم التركيز عليها بشكل غير مباشر في الشجرة، أو التركيز على العقدة الجذرية للشجرة. يُرجى العِلم أنّه إذا كانت الشجرة المحدّدة تتضمّن عقدة تم التركيز عليها، لن يؤدي ذلك إلى تغيير أي تركيز حالي (إلا إذا كانت تلك العقدة تتضمّن تركيزًا غير نشط، وفي هذه الحالة ستتم استعادة التركيز النشط). راجِع getFocusedNode للحصول على تفاصيل حول كيفية تأثُّر العُقد الأخرى.
getFocusedNode()		تعرض هذه الدالة IFocusableNode الحالي الذي تم التركيز عليه (والذي يكون مرتبطًا دائمًا بـ IFocusableTree الذي تم التركيز عليه)، أو تعرض قيمة فارغة إذا لم يكن هناك IFocusableNode. يُرجى العِلم أنّ هذه الدالة ستحافظ على التكافؤ مع IFocusableTree.getFocusedNode()‎. أي أنّه إذا كان التركيز على شجرة نفسها ولكن ليس على أي من عناصرها الفرعية غير الجذرية، ستعرض هذه الدالة القيمة null ولكن لن تعرض الدالة getFocusedTree()‎ القيمة null. يُرجى العِلم أيضًا أنّه إذا تم حاليًا التقاط التركيز المؤقت (على سبيل المثال، باستخدام takeEphemeralFocus)، قد لا يكون للعقدة التي تم إرجاعها هنا تركيز DOM حاليًا.
getFocusedTree()		تعرِض هذه السمة IFocusableTree الحالي الذي تم ضبط التركيز عليه، أو قيمة فارغة إذا لم يتم ضبط التركيز على أي عنصر حاليًا. يُرجى العِلم أيضًا أنّه إذا تم حاليًا التقاط التركيز المؤقت (على سبيل المثال، باستخدام takeEphemeralFocus)، قد لا تتضمّن الشجرة التي تم إرجاعها هنا التركيز على نموذج المستند (DOM) حاليًا.
getFocusManager()	static	تعرض هذه السمة FocusManager على مستوى الصفحة. يُضمن عدم تغيير العنصر الذي تم إرجاعه في جميع استدعاءات الدالة، ولكن قد يتغير في جميع عمليات تحميل الصفحة.
isRegistered(tree)		تعرض هذه الطريقة ما إذا كان قد تم تسجيل الشجرة المحدّدة في هذا المدير باستخدام registerTree ولم يتم إلغاء تسجيلها بعد باستخدام unregisterTree.
registerTree(tree, rootShouldBeAutoTabbable)		تسجّل هذه الطريقة IFocusableTree جديدًا لإدارة التركيز التلقائي. إذا كانت الشجرة تتضمّن حاليًا عنصرًا مع تركيز DOM، لن يؤثّر ذلك في الحالة الداخلية في هذه الأداة إلى أن يتغيّر التركيز إلى عنصر/عقدة جديدة يتم تتبّعها الآن. تعرض هذه الدالة خطأً إذا كانت الشجرة المقدَّمة مسجَّلة حاليًا في هذا المدير. استخدِم isRegistered للتحقّق في الحالات التي لا يمكن فيها التأكّد مما إذا تم تسجيل الشجرة. يمكن تخصيص تسجيل الشجرة لضبط مواضع التوقف التلقائي لعلامات التبويب. يوفّر ذلك تحديدًا إمكانية تنقّل المستخدم إلى جذر الشجرة باستخدام مفتاح Tab، ولكن فقط عندما لا تكون الشجرة في وضع التركيز النشط. في حال إيقاف هذه الوظيفة، سيتم تلقائيًا إتاحة التركيز على جذر الشجرة (ولكن ليس باستخدام مفتاح Tab) عند التركيز عليه لأول مرة بالطريقة نفسها التي يتم بها التركيز على أي عقدة أخرى يمكن التركيز عليها.
takeEphemeralFocus(focusableElement)		تستحوذ هذه الدالة مؤقتًا على التركيز لعنصر معيّن إلى أن يتم استدعاء تعبير lambda الذي تم عرضه. ومن المتوقّع أن يكون ذلك مفيدًا بشكل خاص في مسارات واجهة المستخدم المؤقتة، مثل مربّعات الحوار. ملاحظة مهمة: يجب استدعاء lambda المعروضة، وإلا لن يعمل التركيز التلقائي في أي مكان على الصفحة. يُنصح بشدة بربط استدعاء دالة lambda بإغلاق واجهة المستخدم المؤقتة المقابلة، حتى أنّه في حال تغيير الإدخال يدويًا إلى عنصر خارج واجهة المستخدم المؤقتة، يجب إغلاق واجهة المستخدم واستعادة الإدخال التلقائي. يُرجى العِلم أنّه يجب استدعاء هذه الدالة البرمجية مرة واحدة بالضبط، وأنّ عمليات الاستدعاء اللاحقة ستؤدي إلى ظهور خطأ. يُرجى العِلم أنّ المدير سيواصل تتبُّع إشارات إدخال DOM حتى عندما يكون التركيز المؤقت نشطًا، ولكنّه لن يغيّر حالة العقدة فعليًا إلى أن يتم استدعاء تعبير lambda الذي تم عرضه. بالإضافة إلى ذلك، يمكن تفعيل سياق تركيز مؤقت واحد فقط في أي وقت (محاولة تفعيل أكثر من واحد في الوقت نفسه ستؤدي إلى ظهور خطأ).
unregisterTree(tree)		يلغي تسجيل IFocusableTree من إدارة التركيز التلقائي. إذا كانت الشجرة تحتوي على عقدة تم التركيز عليها سابقًا، ستتم إزالة التمييز عنها. لا تغيّر هذه الدالة تركيز DOM. تعرض هذه الدالة خطأً إذا لم يتم تسجيل الشجرة المقدَّمة حاليًا في هذا المدير. ستعيد هذه الدالة ضبط tabindex لعنصر الجذر في الشجرة إذا تم تسجيل الشجرة باستخدام ميزة الإدارة التلقائية لعلامات التبويب.