کلید های میانبر صفحه کلید

Blockly maintains a registry of keyboard shortcuts that map keys (or key combinations like ctrl-C ) to actions. The registry is prepopulated with a number of shortcuts, such as ctrl-C and meta-C for copy. You can add shortcuts to and delete shortcuts from the registry.

نحوه عملکرد میانبرهای صفحه کلید

رجیستری میانبرها شامل اشیایی است که میانبرهای صفحه کلید را مدل‌سازی می‌کنند. وقتی کاربر یک کلید (یا ترکیبی از کلیدها) را فشار می‌دهد، Blockly:

1. Checks the registry to see if any shortcuts apply to the key. If more than one shortcut uses the key, the shortcuts are tried in reverse order of registration. That is, the most recently registered shortcut is tried first.

2. Calls the shortcut's preconditionFn function, which determines whether the shortcut applies to the current situation. For example, the copy shortcut applies to blocks but not to the workspace. If the shortcut doesn't apply, Blockly tries the next shortcut in the list, if any.

3. Calls the shortcut's callback function, which executes the shortcut's action. For example, the copy shortcut makes a copy of the currently focused object, such as a block. If this function returns true , processing stops. If it returns false , Blockly tries the next shortcut in the list, if any.

دامنه

A Scope object identifies the Blockly component that currently has focus. Scope objects are passed to preconditionFn and callback , which use them to decide whether a shortcut applies to a particular component and, if so, how to apply it.

To use a Scope object, use its focusedNode property. This is an object that implements IFocusableNode . This interface is implemented by all Blockly components that the user can focus on, including workspaces, blocks, fields, comments, and your own custom components; for more information, see Focus system .

برای مثال، یک preconditionFn ممکن است از focusedNode استفاده کند تا اطمینان حاصل شود که یک میانبر فقط برای بلوک‌ها اعمال می‌شود.

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

رابط کاربری میانبر صفحه‌کلید

اشیاء موجود در رجیستری میانبر، رابط KeyboardShortcut را پیاده‌سازی می‌کنند. این رابط شامل ویژگی‌های زیر است.

نام (الزامی)

یک نام منحصر به فرد برای میانبر. این نام به کاربران نشان داده نمی‌شود و نیازی به خوانایی توسط انسان ندارد. نباید ترجمه شود.

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

پیش‌شرطFn (اختیاری)

Blockly این تابع را فراخوانی می‌کند تا تصمیم بگیرد که آیا یک میانبر برای وضعیت فعلی اعمال می‌شود یا خیر. اگر مقدار true را برگرداند، Blockly تابع callback را فراخوانی می‌کند. اگر مقدار false را برگرداند، Blockly این میانبر را نادیده می‌گیرد. برای مثال:

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

A shortcut can omit this function if the shortcut always applies (uncommon). Shortcuts should not omit this function and then take action conditionally in callback . Doing so prevents Blockly from doing things like building contextual help menus that show applicable shortcuts.

تماس مجدد (اختیاری)

این تابع، عملی را که با میانبر مرتبط است، اجرا می‌کند. این تابع فقط در صورتی فراخوانی می‌شود که preconditionFn true برگرداند یا وجود نداشته باشد. پارامترهای آن عبارتند از:

• 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 اختیاری است، اما عموماً دلیلی برای عدم پیاده‌سازی آن وجود ندارد.

کدهای کلیدی (اختیاری)

آرایه‌ای از کلیدها (یا ترکیبی از کلیدها) که این میانبر را فعال می‌کنند. برای شناسایی کلیدها، از کدهای کلید موجود در Blockly.utils.KeyCodes استفاده کنید. برای مثال:

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

اگر می‌خواهید کلیدهای اضافی را به یک میانبر موجود نگاشت کنید -- برای مثال، می‌خواهید کلیدهایی را به یک میانبر پیش‌فرض اضافه کنید -- می‌توانید Blockly.ShortcutRegistry.registry.addKeyMapping را فراخوانی کنید. این روش رایج نیست.

ترکیبات کلیدی

If your keyboard shortcut is activated by a combination of keys, such as holding Control and C simultaneously, create a serialized keycode by calling 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
  // ...
};

کنترل و متا

On Windows, many shortcuts are activated with the Control key. On Mac, these keyboard shortcuts use the Command key instead, which is recognized as the META keycode. To support both operating systems, register your shortcuts with both the CTRL keycode and the META keycode.

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 (اختیاری)

By default, you can only register one shortcut for a given key or key combination. Setting this property to true lets you register a key (or key combination) even if a shortcut with the same key (or key combination) has already been registered.

Note that this property only applies when attempting to register this shortcut. It does not prevent other shortcuts from using the same key (or key combination). Whether they can be registered depends on the value of their allowCollision property.

Regardless of how many shortcuts are registered for a given key or key combination, at most one will be successfully executed. Shortcuts are tried in the reverse order of registration (from last registered to first registered). After one of them returns true from their callback, no other shortcuts are tried.

فراداده (اختیاری)

این یک شیء دلخواه است که حاوی اطلاعات اضافی می‌باشد. می‌توان از طریق پارامتر shortcut آن را callback .

اضافه کردن، حذف کردن و تغییر دادن میانبرها

برای افزودن یک میانبر صفحه کلید جدید، 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/RaspberryPiFoundation/blockly/blob/master/core/shortcut_items.ts پیدا کنید. میانبرها در توابع registerXxxx تعریف شده‌اند.

میانبرهای ناوبری صفحه کلید

افزونه‌ی ناوبری صفحه‌کلید شامل میانبرهایی است که به کاربران اجازه می‌دهد با استفاده از صفحه‌کلید، مانند استفاده از کلیدهای جهت‌نما، در Blockly پیمایش کنند. ناوبری صفحه‌کلید برای کاربرانی که نمی‌توانند از ماوس استفاده کنند، مانند افرادی که دارای اختلالات حرکتی یا بینایی هستند، ضروری است. همچنین برای کاربران حرفه‌ای که ممکن است بخواهند برای کارایی بیشتر از میانبرهای صفحه‌کلید استفاده کنند، مفید است.