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

Blockly یک رجیستری از میانبرهای صفحه کلید را نگهداری می‌کند که کلیدها (یا ترکیب کلیدهایی مانند ctrl-C ) را به اقدامات نگاشت می‌کند. این رجیستری با تعدادی میانبر، مانند ctrl-C و meta-C برای کپی، از قبل پر شده است. می‌توانید میانبرهایی را به رجیستری اضافه یا از آن حذف کنید.

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

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

1. رجیستری را بررسی می‌کند تا ببیند آیا میانبری برای کلید اعمال می‌شود یا خیر. اگر بیش از یک میانبر از کلید استفاده کند، میانبرها به ترتیب معکوس ثبت امتحان می‌شوند. یعنی، جدیدترین میانبر ثبت شده ابتدا امتحان می‌شود.

2. تابع preconditionFn مربوط به میانبر را فراخوانی می‌کند، که تعیین می‌کند آیا میانبر برای وضعیت فعلی اعمال می‌شود یا خیر. برای مثال، میانبر کپی برای بلوک‌ها اعمال می‌شود اما برای فضای کاری اعمال نمی‌شود. اگر میانبر اعمال نشود، Blockly میانبر بعدی را در لیست، در صورت وجود، امتحان می‌کند.

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);
  },
  // ...
};

یک میانبر می‌تواند این تابع را حذف کند اگر میانبر همیشه اعمال شود (غیرمعمول). میانبرها نباید این تابع را حذف کنند و سپس به صورت مشروط در callback اقدام کنند. انجام این کار مانع از انجام کارهایی مانند ساخت منوهای راهنمای متنی می‌شود که میانبرهای مربوطه را نشان می‌دهند.

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

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

• workspace : فایل WorkspaceSvg فعلی.
• e : Event که میانبر را آغاز کرده است.
• shortcut : خودِ KeyboardShortcut .
• scope : Scope که میانبر به آن اعمال می‌شود.

It returns true if it succeeds and false if it fails.

برای مثال:

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 را فراخوانی کنید. این روش رایج نیست.

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

اگر میانبر صفحه‌کلید شما با ترکیبی از کلیدها، مانند نگه داشتن همزمان 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 فعال می‌شوند. در مک، این میانبرهای صفحه کلید به جای آن از کلید 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's keyboard event handlers use the keycode property of KeyboardEvent even though it is deprecated.

allowCollision (اختیاری)

به طور پیش‌فرض، شما فقط می‌توانید یک میانبر برای یک کلید یا ترکیب کلید مشخص ثبت کنید. تنظیم این ویژگی روی true به شما امکان می‌دهد یک کلید (یا ترکیب کلید) ثبت کنید، حتی اگر میانبری با همان کلید (یا ترکیب کلید) قبلاً ثبت شده باشد.

توجه داشته باشید که این ویژگی فقط هنگام تلاش برای ثبت این میانبر اعمال می‌شود. این ویژگی مانع از استفاده سایر میانبرها از همان کلید (یا ترکیب کلید) نمی‌شود. اینکه آیا می‌توان آنها را ثبت کرد یا خیر، به مقدار ویژگی allowCollision آنها بستگی دارد.

صرف نظر از اینکه چند میانبر برای یک کلید یا ترکیب کلید مشخص ثبت شده است، حداکثر یکی از آنها با موفقیت اجرا خواهد شد. میانبرها به ترتیب معکوس ثبت (از آخرین ثبت شده به اولین ثبت شده) امتحان می‌شوند. پس از اینکه یکی از آنها از callback خود true را برگرداند، هیچ میانبر دیگری امتحان نمی‌شود.

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

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

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

برای افزودن یک میانبر صفحه کلید جدید، Blockly.ShortcutRegistry.registry.register را فراخوانی کنید:

Blockly.ShortcutRegistry.registry.register(logFieldsShortcut);

این تابع یک پارامتر دوم ( allowOverrides ) دارد که به شما امکان می‌دهد یک میانبر موجود را با نامی مشابه میانبر خود جایگزین کنید. توجه داشته باشید که این با KeyboardShortcut.allowCollision متفاوت است، که به شما امکان می‌دهد یک میانبر با نامی متفاوت اضافه کنید اما از همان کلید یا ترکیب کلید میانبر موجود استفاده می‌کند.

To delete a keyboard shortcut, call Blockly.ShortcutRegistry.registry.unregister and pass the name of the shortcut:

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);

میانبرهای پیش‌فرض

The shortcut registry is prepopulated with a number of shortcuts. You can find these in https://github.com/RaspberryPiFoundation/blockly/blob/main/core/shortcut_items.ts . The shortcuts are defined in the registerXxxx functions.

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

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