arthur/ui
1
0
Fork 0
mirror of https://github.com/ArthurDanjou/ui.git synced 2026-01-23 08:20:39 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(content): move shortcuts into composables/

Browse Source
This commit is contained in:
Benjamin Canac
2024-07-10 17:22:42 +02:00
parent a889c054d3
commit 8e5547f26d
46 changed files with 50 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
docs/content/1.getting-started/6.shortcuts.md
View File

@@ -1,141 +0,0 @@
---
description: 'Learn how to display and define keyboard shortcuts in your app.'
---
Some components like [Dropdown](/components/dropdown), [Command Palette](/components/command-palette) and [Tooltip](/components/tooltip) support the display of keyboard shortcuts.
```vue
<UDropdown :items="[[{ label: 'Edit', shortcuts: ['E'] }]]" />
```
Shortcuts are displayed and styled through the [Kbd](/components/kbd) component.
```vue
<template>
<div class="flex items-center gap-0.5">
<UKbd>⌘</UKbd>
<UKbd>K</UKbd>
</div>
</template>
```
::callout{icon="i-heroicons-light-bulb"}
You will have a preview of how shortcuts are rendered in each component page.
::
## `defineShortcuts`
This module provides a `defineShortcuts` composable that allows you to define keyboard shortcuts in your app really easily.
```vue
<template>
<UModal v-model="isOpen" />
</template>
<script setup lang="ts">
const isOpen = ref(false)
defineShortcuts({
meta_k: {
usingInput: true,
handler: () => {
isOpen.value = !isOpen.value
}
}
})
</script>
```
Shortcuts keys are written as the literal keyboard key value. Combinations are made with `_` separator. Chained shortcuts are made with `-` separator.
Modifiers are also available:
- `meta`: acts as `Command` for MacOS and `Control` for others
- `ctrl`: acts as `Control`
- `shift`: acts as `Shift` and is only necessary for alphabetic keys
Examples of keys:
- `escape`: will trigger by hitting `Esc`
- `meta_k`: will trigger by hitting `⌘` and `K` at the same time on MacOS, and `Ctrl` and `K` on Windows and Linux
- `ctrl_k`: will trigger by hitting `Ctrl` and `K` at the same time on MacOS, Windows and Linux
- `shift_e`: will trigger by hitting `Shift` and `E` at the same time on MacOS, Windows and Linux
- `?`: will trigger by hitting `?` on some keyboard layouts, or for example `Shift` and `/`, which results in `?` on US Mac keyboards
- `g-d`: will trigger by hitting `g` then `d` with a maximum delay of 800ms by default
- `arrowleft`: will trigger by hitting `←` (also: `arrowright`, `arrowup`, `arrowdown`)
::callout{icon="i-heroicons-light-bulb"}
For a complete list of available shortcut keys, refer to the [`KeyboardEvent`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) API docs. Note the `KeyboardEvent.key` has to be written in lowercase.
::
### `usingInput`
Prop: `usingInput?: string | boolean`
By default, `usingInput` is `false`, meaning it will only trigger when no input is focused. When set to `true`, the shortcut will also trigger when any input is focused.
For a more advanced behavior, `usingInput` can be set to the name of an input, so it only triggers when focusing this specific input.
```vue
<template>
<UInput v-model="query" name="queryInput" />
</template>
<script setup lang="ts">
const query = ref('')
defineShortcuts({
enter: {
usingInput: 'queryInput',
handler: () => {
// TODO
}
}
})
</script>
```
_`enter` shortcut will only trigger when `queryInput` is focused._
### `whenever`
Prop: `whenever?: WatchSource<boolean>[]`
`whenever` allows to add constraints on the shortcut triggering behavior. This array can contain `Ref<boolean>`, `ComputedRef<boolean>` or `() => boolean`.
```ts
defineShortcuts({
meta_k: {
usingInput: true,
handler: () => { isOpen.value = !isOpen.value }
},
escape: {
usingInput: true,
whenever: [isOpen],
handler: () => { isOpen.value = false }
}
})
```
_`escape` shortcut will only trigger when `isOpen` is `true`._
### Simple shortcut
In case the shortcut does not need any config, it can be written as a function.
```ts
defineShortcuts({
'?': () => openHelpModal()
})
```
## `useShortcuts`
To display shortcuts in your app according to the user's OS, you can use the `useShortcuts` composable.
```vue
<script setup lang="ts">
const { metaSymbol } = useShortcuts()
</script>
<template>
<UKbd>{{ metaSymbol }}</UKbd>
</template>
```
_`metaSymbol` will display either `⌘` on MacOS or `Ctrl` on any other OS_