Shortcut Key

A Serrvice for creating keyboard shortcuts with support for modifier keys and key combinations. Perfect for implementing hotkeys, keyboard navigation, and accessibility features in web applications.

Features

• Flexible Key Combinations: Support for single keys, modifier keys, and complex combinations
• Modifier Keys: Support for Ctrl, Alt, Shift, and Meta (Cmd/Win) keys
• Multiple Main Keys: Handle combinations with multiple non-modifier keys
• Event Prevention: Automatically prevents default browser behavior
• Memory Management: Easy cleanup with destroy method
• TypeScript Support: Full TypeScript type definitions included
• Cross-platform: Works on Windows, Mac, and Linux

Service Reference

createShortCutKey

Creates a keyboard shortcut handler with automatic event listener management.

const createShortCutKey = (
    keyStructure: string, 
    callback: (e: KeyboardEvent) => void
) => {
    destroy: () => void;
}

Parameters

Parameter	Type	Description
keyStructure	string	The key combination string (e.g., "ctrl+s", "alt+shift+d")
callback	(e: KeyboardEvent) => void	Function to execute when shortcut is triggered

Returns

Object - An object with a destroy() method to remove event listeners

Key Structure Format

• Modifier Keys: ctrl, alt, shift, meta
• Separator: + (plus sign)
• Case Insensitive: Keys are automatically converted to lowercase
• Spaces: Automatically trimmed

Examples of Valid Key Structures

"ctrl+s"              // Ctrl + S
"alt+shift+d"         // Alt + Shift + D
"meta+c"              // Cmd/Win + C
"ctrl+alt+delete"     // Ctrl + Alt + Delete
"shift+f1"            // Shift + F1
"ctrl+shift+/"        // Ctrl + Shift + /
"alt+arrowup"         // Alt + Arrow Up
"ctrl+shift+escape"   // Ctrl + Shift + Escape

Usage Example

<template>
  <div class="app">
    <h1>Shortcut Key Demo</h1>
    <p>Press Ctrl+S to save</p>
    <p>Press Alt+N to create new item</p>
    <p>Status: {{ status }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { CreateShortCutKey } from 'dolphin-components';

const status = ref('Ready');

let saveShortcut: ReturnType<typeof CreateShortCutKey>;
let newItemShortcut: ReturnType<typeof CreateShortCutKey>;

onMounted(() => {
  // Save shortcut
  saveShortcut = CreateShortCutKey('ctrl+s', (e) => {
    status.value = 'Saving...';
    console.log('Save triggered!', e);
    
    // Simulate save operation
    setTimeout(() => {
      status.value = 'Saved!';
      setTimeout(() => status.value = 'Ready', 2000);
    }, 500);
  });

  // New item shortcut
  newItemShortcut = CreateShortCutKey('alt+n', (e) => {
    status.value = 'Creating new item...';
    console.log('New item triggered!', e);
    
    setTimeout(() => {
      status.value = 'New item created!';
      setTimeout(() => status.value = 'Ready', 2000);
    }, 300);
  });
});

onUnmounted(() => {
  // Cleanup shortcuts
  saveShortcut?.destroy();
  newItemShortcut?.destroy();
});
</script>

Common Key Names

Modifier Keys

• ctrl - Control key
• alt - Alt key
• shift - Shift key
• meta - Cmd (Mac) / Win (Windows) key

Function Keys

• f1, f2, f3, ..., f12

Arrow Keys

• arrowup, arrowdown, arrowleft, arrowright

Special Keys

• space, enter, escape, tab, backspace, delete
• home, end, pageup, pagedown
• insert, printscreen, scrolllock, pause

Alphanumeric Keys

• a-z, 0-9
• Special characters: /, \, [, ], ;, ', ,, ., etc.

Platform Differences

Windows/Linux

• Ctrl key for most shortcuts
• Alt key for menu access
• Delete key for deletion

macOS

• Meta key (Cmd) for most shortcuts
• Ctrl key for some specific functions
• Backspace key for deletion (mapped to delete event)

Best Practices

1. Use Standard Conventions: Follow platform-specific shortcut conventions
2. Avoid Conflicts: Don't override important browser shortcuts
3. Clean Up: Always call destroy() when components are unmounted
4. Test Across Platforms: Verify shortcuts work on different operating systems