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

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

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

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

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

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

3. تابع callback میانبر را فراخوانی می کند که عمل میانبر را اجرا می کند. به عنوان مثال، میانبر کپی یک کپی از شی متمرکز شده فعلی، مانند یک بلوک، ایجاد می کند. اگر این تابع true را برگرداند، پردازش متوقف می شود. اگر false را برگرداند، Blockly میانبر بعدی را در لیست، در صورت وجود، امتحان می‌کند.

دامنه

یک شی Scope مؤلفه Blockly را که در حال حاضر فوکوس دارد، شناسایی می کند. اشیاء Scope به preconditionFn و callback ارسال می شوند، که از آنها برای تصمیم گیری در مورد اعمال میانبر برای یک مؤلفه خاص و اگر چنین است، نحوه اعمال آن استفاده می شود.

برای استفاده از یک شی Scope ، از ویژگی focusedNode آن استفاده کنید. این یک شی است که IFocusableNode را پیاده سازی می کند. این رابط توسط تمام مؤلفه‌های Blockly که کاربر می‌تواند روی آنها تمرکز کند، از جمله فضاهای کاری، بلوک‌ها، فیلدها، نظرات و مؤلفه‌های سفارشی خود پیاده‌سازی می‌شود. برای اطلاعات بیشتر، به سیستم فوکوس مراجعه کنید.

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

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

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

اشیاء در رجیستری میانبر رابط KeyboardShortcut را پیاده سازی می کنند. این شامل خواص زیر است.

نام (الزامی)

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

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

preconditionFn (اختیاری)

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

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

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

پاسخ به تماس (اختیاری)

این تابع عمل مربوط به میانبر را اجرا می کند. فقط در صورتی فراخوانی می شود که 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 را فراخوانی کنید. این رایج نیست.

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

اگر میانبر صفحه کلید شما با ترکیبی از کلیدها، مانند نگه داشتن همزمان 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 از ویژگی keycode KeyboardEvent استفاده می‌کنند، حتی اگر منسوخ شده باشد.

allowCollision (اختیاری)

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

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

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

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

این یک شی دلخواه حاوی اطلاعات اضافی است. از طریق پارامتر 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/google/blockly/blob/master/core/shortcut_items.ts بیابید. میانبرها در توابع registerXxxx تعریف شده اند.

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

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