اختصارات لوحة المفاتيح

تحتفظ Blockly بسجلّ لاختصارات لوحة المفاتيح التي تربط المفاتيح (أو مجموعات المفاتيح مثل ctrl-C) بالإجراءات. يتم تعبئة السجلّ مسبقًا بعدد من الاختصارات، مثل ctrl-C وmeta-C للنسخ. يمكنك إضافة اختصارات إلى السجل وحذفها منه.

طريقة عمل اختصارات لوحة المفاتيح

يحتوي سجلّ الاختصارات على عناصر تحاكي اختصارات لوحة المفاتيح. عندما يضغط المستخدم على مفتاح (أو مجموعة مفاتيح)، ينفّذ Blockly ما يلي:

1. يتحقّق من قاعدة بيانات المسجّلين لمعرفة ما إذا كانت أي اختصارات تنطبق على المفتاح. إذا كان أكثر من اختصار واحد يستخدم المفتاح، تتم تجربة الاختصارات بترتيب عكسي لترتيب التسجيل. أي أنّه يتم تجربة الاختصار الذي تم تسجيله مؤخرًا أولاً.

2. يتم استدعاء الدالة preconditionFn الخاصة بالاختصار، والتي تحدّد ما إذا كان الاختصار ينطبق على الموقف الحالي. على سبيل المثال، ينطبق اختصار النسخ على البلوكات وليس على مساحة العمل. إذا لم يتم تطبيق الاختصار، سيحاول Blockly استخدام الاختصار التالي في القائمة، إذا كان متاحًا.

3. يتم استدعاء الدالة callback الخاصة بالاختصار، والتي تنفّذ الإجراء الخاص بالاختصار. على سبيل المثال، ينشئ اختصار النسخ نسخة من العنصر الذي يتم التركيز عليه حاليًا، مثل كتلة. إذا عرضت هذه الدالة true، تتوقّف المعالجة. إذا تم عرض false، سيحاول Blockly استخدام الاختصار التالي في القائمة، إن وُجد.

النطاق

يحدّد العنصر Scope مكوّن Blockly الذي يتم التركيز عليه حاليًا. يتم تمرير عناصر النطاق إلى preconditionFn وcallback، اللذين يستخدمانها لتحديد ما إذا كان الاختصار ينطبق على مكوّن معيّن، وإذا كان الأمر كذلك، كيفية تطبيقه.

لاستخدام عنصر Scope، استخدِم السمة focusedNode. هذا هو العنصر الذي ينفّذ IFocusableNode. يتم تنفيذ هذه الواجهة من خلال جميع مكوّنات Blockly التي يمكن للمستخدم التركيز عليها، بما في ذلك مساحات العمل والكتل والحقول والتعليقات والمكوّنات المخصّصة الخاصة بك. لمزيد من المعلومات، راجِع نظام التركيز.

على سبيل المثال، يمكن استخدام preconditionFn focusedNode للتأكّد من أنّ الاختصار ينطبق على الكتل فقط.

preconditionFn(workspace, scope) {
  return (scope.focusedNode instanceof Blockly.BlockSvg);
}

واجهة KeyboardShortcut

تنفّذ العناصر في سجلّ الاختصارات الواجهة KeyboardShortcut. يحتوي هذا العنصر على السمات التالية.

الاسم (مطلوب)

اسم فريد للاختصار لن يظهر هذا المعرّف للمستخدمين وليس من الضروري أن يكون قابلاً للقراءة. ويجب عدم ترجمته.

const logFieldsShortcut = {
  name: 'logFields',
  // ...
};

preconditionFn (اختياري)

يستدعي Blockly هذه الدالة لتحديد ما إذا كان الاختصار ينطبق على الحالة الحالية. إذا عرضت القيمة true، يستدعي Blockly الدالة callback. إذا عرضت false، سيتجاهل Blockly هذا الاختصار. على سبيل المثال:

const logFieldsShortcut = {
  // ...
  preconditionFn(workspace, scope) {
    // This shortcut only applies to blocks.
    return (scope.focusedNode instanceof Blockly.BlockSvg);
  },
  // ...
};

يمكن للاختصار حذف هذه الدالة إذا كان الاختصار ينطبق دائمًا (وهذا أمر غير شائع). يجب ألا تحذف الاختصارات هذه الدالة ثم تتّخذ إجراءً بشكل مشروط في callback. ويمنع ذلك Blockly من تنفيذ إجراءات مثل إنشاء قوائم مساعدة حسب السياق تعرض الاختصارات المناسبة.

معاودة الاتصال (اختياري)

تنفّذ هذه الدالة الإجراء المرتبط باختصار لوحة المفاتيح. يتم استدعاء هذه الدالة فقط إذا عرضت الدالة preconditionFn القيمة true أو إذا لم تكن الدالة preconditionFn متوفّرة. المَعلمات هي:

• ‫workspace: WorkspaceSvg الحالي
• ‫e: Event الذي بدأ الاختصار.
• shortcut: KeyboardShortcut نفسه
• scope: Scope الذي ينطبق عليه الاختصار

تعرض هذه الدالة true في حال نجاح العملية وfalse في حال تعذُّرها.

على سبيل المثال:

const logFieldsShortcut = {
  // ...
  callback(workspace, event, shortcut, scope) {
    // preconditionFn required focusedNode to be a BlockSvg.
    for (input of scope.focusedNode.inputList) {
      // Log the values of all named fields. (Label fields usually don't have names.)
      for (field of input.fieldRow) {
        if (field.name) {
          console.log(field.name + ': ' + field.getText());
        }
      }
    }
    return true;
  },
  // ...
};

على الرغم من أنّ callback هو سمة اختيارية، ليس هناك بشكل عام أي سبب لعدم تنفيذها.

keyCodes (اختيارية)

مجموعة من المفاتيح (أو مجموعات من المفاتيح) التي تفعّل هذا الاختصار. لتحديد المفاتيح، استخدِم رموز المفاتيح في Blockly.utils.KeyCodes. على سبيل المثال:

const logFieldsShortcut = {
  // ...
  keyCodes: [Blockly.utils.KeyCodes.L],
  // ...
};

إذا أردت ربط مفاتيح إضافية باختصار حالي، مثلاً إذا أردت إضافة مفاتيح إلى اختصار تلقائي، يمكنك استدعاء Blockly.ShortcutRegistry.registry.addKeyMapping. وهذا ليس شائعًا.

مجموعات المفاتيح

إذا تم تفعيل اختصار لوحة المفاتيح من خلال مجموعة من المفاتيح، مثل الضغط مع الاستمرار على Control وC في الوقت نفسه، أنشئ رمز مفتاح تسلسليًا من خلال استدعاء Blockly.ShortcutRegistry.registry.createSerializedKey:

const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,       // Keycode of main key
  [Blockly.utils.KeyCodes.CTRL],  // Array of modifier keys
);

const copyShortcut = {
  // ...
  keyCodes: [ctrlC], // Use the serialized keycode
  // ...
};

مفتاحا Control وMeta

في نظام التشغيل Windows، يتم تفعيل العديد من الاختصارات باستخدام المفتاح Control. على أجهزة Mac، تستخدم اختصارات لوحة المفاتيح هذه المفتاح Command بدلاً من ذلك، ويتم التعرّف عليه كرمز المفتاح META. لإتاحة استخدام الاختصارات على نظامَي التشغيل، سجِّل الاختصارات باستخدام رمز المفتاح CTRL ورمز المفتاح META.

const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,
  [Blockly.utils.KeyCodes.CTRL],
);
const metaC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,
  [Blockly.utils.KeyCodes.META],
);

const copyShortcut = {
  // ...
  keyCodes: [ctrlC, metaC],
  // ...
};

ملاحظة التنفيذ

تستخدم معالِجات أحداث لوحة المفاتيح في Blockly السمة keycode الخاصة بالعنصر KeyboardEvent، على الرغم من أنّها متوقّفة نهائيًا.

allowCollision (اختياري)

يمكنك تلقائيًا تسجيل اختصار واحد فقط لمفتاح أو مجموعة مفاتيح معيّنة. يسمح لك ضبط هذه السمة على true بتسجيل مفتاح (أو مجموعة مفاتيح) حتى إذا تم تسجيل اختصار باستخدام المفتاح نفسه (أو مجموعة المفاتيح نفسها).

يُرجى العِلم أنّ هذه السمة تنطبق فقط عند محاولة تسجيل هذا الاختصار. ولا يمنع اختصارات أخرى من استخدام المفتاح نفسه (أو مجموعة المفاتيح نفسها). ويعتمد إمكانية تسجيلها على قيمة السمة allowCollision.

وبغض النظر عن عدد الاختصارات المسجّلة لمفتاح أو مجموعة مفاتيح معيّنة، سيتم تنفيذ اختصار واحد بنجاح على الأكثر. يتم تجربة الاختصارات بترتيب عكسي لترتيب التسجيل (من آخر اختصار تم تسجيله إلى أول اختصار تم تسجيله). بعد أن يعرض أحدها true من رد الاتصال، لن يتم تجربة أي اختصارات أخرى.

البيانات الوصفية (اختيارية)

هذا عنصر عشوائي يحتوي على معلومات إضافية. وهي متاحة لـ callback من خلال المَعلمة shortcut.

إضافة الاختصارات وحذفها وتعديلها

لإضافة اختصار جديد للوحة المفاتيح، استخدِم الأمر Blockly.ShortcutRegistry.registry.register:

Blockly.ShortcutRegistry.registry.register(logFieldsShortcut);

تتضمّن هذه الدالة مَعلمة ثانية (allowOverrides) تتيح لك استبدال اختصار حالي باسم الاختصار نفسه. يُرجى العِلم أنّ هذا الإجراء يختلف عن KeyboardShortcut.allowCollision، الذي يتيح لك إضافة اختصار باسم مختلف ولكن باستخدام المفتاح أو مجموعة المفاتيح نفسها التي يستخدمها اختصار حالي.

لحذف اختصار لوحة مفاتيح، استدعِ الدالة Blockly.ShortcutRegistry.registry.unregister ومرِّر اسم الاختصار:

Blockly.ShortcutRegistry.registry.unregister('logFields');

لا يمكنك تعديل اختصار لوحة المفاتيح في مكانه. بدلاً من ذلك، عليك حذف الاختصار الحالي وإضافة اختصار جديد. على سبيل المثال:

// Get the existing shortcut. getRegistry returns an object keyed by shortcut name.
const allShortcuts = Blockly.ShortcutRegistry.registry.getRegistry();
const modLogFieldsShortcut = allShortcuts[logFieldsShortcut.name];
// Apply the shortcut only to math blocks,
modLogFieldsShortcut.preconditionFn = function (workspace, scope) {
  return (scope.focusedNode instanceof Blockly.BlockSvg &&
          scope.focusedNode.type.startsWith('math_'));
}
// Delete the existing shortcut and add the modified shortcut.
Blockly.ShortcutRegistry.registry.unregister(logFieldsShortcut.name);
Blockly.ShortcutRegistry.registry.register(modLogFieldsShortcut);

الاختصارات الافتراضية

يتم ملء سجلّ الاختصارات مسبقًا بعدد من الاختصارات. يمكنك العثور على هذه العناصر في https://github.com/google/blockly/blob/master/core/shortcut_items.ts. يتم تحديد الاختصارات في دوال registerXxxx.

اختصارات التنقّل باستخدام لوحة المفاتيح

يحتوي مكوّن التنقّل باستخدام لوحة المفاتيح على اختصارات تتيح للمستخدمين التنقّل في Blockly باستخدام لوحة المفاتيح، مثلاً باستخدام مفاتيح الأسهم. يُعدّ التنقّل باستخدام لوحة المفاتيح أمرًا ضروريًا للمستخدمين الذين لا يمكنهم استخدام الماوس، مثل الأشخاص الذين يعانون من مشاكل في الحركة أو مشاكل بصرية. وهي مفيدة أيضًا للمستخدمين المتقدّمين الذين يريدون استخدام اختصارات لوحة المفاتيح لزيادة الكفاءة.