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

«راهنمای میان‌برهای صفحه‌کلید» به کاربران امکان می‌دهد میان‌برهای صفحه‌کلید را برای پلاتفرم و برنامه‌های باز کاوش کنند. میان‌برهای برنامه‌تان را در «راهنمای میان‌برهای صفحه‌کلید» منتشر کنید تا بهره‌وری کاربر و سهولت استفاده را بهبود بخشید.

کاربران با فشار دادن Meta+/ صفحه میان‌برهای صفحه‌کلید را باز می‌کنند که در Android نسخه ۷.۰ (سطح میانای برنامه‌سازی کاربردی ۲۴) و بالاتر دردسترس است.

برنامه‌ای در دستگاه باز است و میان‌برهای سیستم را نشان می‌دهد.
شکل ۱. راهنمای میان‌برهای صفحه‌کلید.

ارائه میان‌برها به «راهنمای میان‌برهای صفحه‌کلید»

می‌توانید با لغو کردن فراخوان پنجره onProvideKeyboardShortcuts()، فهرست‌های میان‌بر صفحه‌کلید دردسترس را به «راهنمای میان‌برهای صفحه‌کلید» ارائه دهید. تکه‌کد زیر پیاده‌سازی onProvideKeyboardShortcuts() را برای افزودن گروهی از چهار میان‌بر نشان می‌دهد:

class MainActivity : ComponentActivity() {
    // Activity codes such as overridden onStart method.

    override fun onProvideKeyboardShortcuts(
        data: MutableList<KeyboardShortcutGroup>?,
        menu: Menu?,
        deviceId: Int
    ) {
        val shortcutGroup =
            KeyboardShortcutGroup(
                "Cursor movement",
                listOf(
                    KeyboardShortcutInfo("Up", KeyEvent.KEYCODE_P, KeyEvent.META_CTRL_ON),
                    KeyboardShortcutInfo("Down", KeyEvent.KEYCODE_N, KeyEvent.META_CTRL_ON),
                    KeyboardShortcutInfo("Forward", KeyEvent.KEYCODE_F, KeyEvent.META_CTRL_ON),
                    KeyboardShortcutInfo("Backward", KeyEvent.KEYCODE_B, KeyEvent.META_CTRL_ON),
                )
            )
        data?.add(shortcutGroup)
    }
}

KeyboardShortcutInfo میان‌بر صفحه‌کلید را توصیف می‌کند. فهرست میان‌برهای صفحه‌کلید به‌عنوان شیء KeyboardShortcutGroup بسته‌بندی شده است. برنامه‌ها میان‌برهای صفحه‌کلید دردسترس را با افزودن اشیاء KeyboardShortcutGroup به فهرست تغییرپذیر ارسال‌شده به‌عنوان اولین پارامتر روش، به «راهنمای میان‌برهای صفحه‌کلید» اطلاع می‌دهند.

سازمان‌دهی میان‌برهای صفحه‌کلید با گروه‌ها

«راهنمای میان‌برهای صفحه‌کلید» میان‌برهای صفحه‌کلید را در گروه‌های جداگانه نمایش می‌دهد تا کاربران بتوانند میان‌برها را براساس مورد استفاده یا برای صفحه‌های برنامه شما پیدا کنند. شکل ۲ میان‌برهای صفحه‌کلید را نشان می‌دهد که به دو گروه دسته‌بندی شده‌اند: حرکت مکان‌نما و ویرایش پیام.

برنامه در دستگاهی باز است و گروه‌های میان‌بر را نشان می‌دهد.
شکل ۲. دسته‌ها در «راهنمای میان‌برهای صفحه‌کلید».

برنامه شما با ایجاد یک شیء KeyboardShortcutGroup برای هر گروه، دو یا چند گروه میان‌بر صفحه‌کلید را ثبت می‌کند. در قطعه کد زیر، دو شیء KeyboardShortCutGroup به فهرست تغییرپذیر ارسال‌شده به روش onProvideKeyboardShortcuts() اضافه شده است. همان‌طور که در شکل ۲ نشان داده شده است، اشیا به‌صورت دسته‌هایی در «راهنمای میان‌برهای صفحه‌کلید» نمایش داده می‌شوند.

override fun onProvideKeyboardShortcuts(
    data: MutableList<KeyboardShortcutGroup>?,
    menu: Menu?,
    deviceId: Int
) {
    val cursorMovement = KeyboardShortcutGroup(
        "Cursor movement",
        listOf(
            KeyboardShortcutInfo("Up", KeyEvent.KEYCODE_P, KeyEvent.META_CTRL_ON),
            KeyboardShortcutInfo("Down", KeyEvent.KEYCODE_N, KeyEvent.META_CTRL_ON),
            KeyboardShortcutInfo("Forward", KeyEvent.KEYCODE_F, KeyEvent.META_CTRL_ON),
            KeyboardShortcutInfo("Backward", KeyEvent.KEYCODE_B, KeyEvent.META_CTRL_ON),
        )
    )

    val messageEdit = KeyboardShortcutGroup(
        "Message editing",
        listOf(
            KeyboardShortcutInfo("Select All", KeyEvent.KEYCODE_A, KeyEvent.META_CTRL_ON),
            KeyboardShortcutInfo(
                "Send a message",
                KeyEvent.KEYCODE_ENTER,
                KeyEvent.META_SHIFT_ON
            )
        )
    )

    data?.add(cursorMovement)
    data?.add(messageEdit)
}

باز کردن «راهنمای میان‌برهای صفحه‌کلید» از کد

برنامه‌ها صفحه میان‌برهای صفحه‌کلید را با فراخوانی روش requestShowKeyboardShortcuts() نمایش می‌دهند. در قطعه کد زیر، وقتی کاربران روی دکمه ضربه می‌زنند یا کلیک می‌کنند یا کلید ورود را فشار می‌دهند، «راهنمای میان‌برهای صفحه‌کلید» باز می‌شود.

val activity = LocalActivity.current

Button(
    onClick = {
        activity?.requestShowKeyboardShortcuts()
    }
) {
    Text(text = "Show keyboard shortcuts")
}