入门
快捷键
了解如何在你的应用中显示和定义键盘快捷键。
一些组件，例如 下拉菜单、命令面板 和 工具提示 支持显示键盘快捷键。
<UDropdown :items="[[{ label: 'Edit', shortcuts: ['E'] }]]" />
快捷键通过 键盘 组件进行显示和样式化。
<template>
<div class="flex items-center gap-0.5">
<UKbd>⌘</UKbd>
<UKbd>K</UKbd>
</div>
</template>
你将可以在每个组件页面预览快捷键的渲染方式。
defineShortcuts
此模块提供了一个 defineShortcuts 可组合函数，允许你非常轻松地在应用中定义键盘快捷键。
<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>
快捷键键值以实际的键盘键值表示。组合使用 _ 分隔符。链式快捷键使用 - 分隔符。
修饰键也可用
meta：在 macOS 上充当Command，在其他系统上充当Controlctrl：充当Controlshift：充当Shift，仅在字母键上必要
键示例
escape：按Esc键触发meta_k：在 macOS 上按⌘和K键同时触发，在 Windows 和 Linux 上按Ctrl和K键同时触发ctrl_k：在 macOS、Windows 和 Linux 上按Ctrl和K键同时触发shift_e：在 macOS、Windows 和 Linux 上按Shift和E键同时触发?：在某些键盘布局上按?键触发，例如，在 US Mac 键盘上，按Shift和/键，会得到?g-d：按g键然后按d键触发，默认情况下，最大延迟为 800 毫秒arrowleft：按←键触发（也包括：arrowright、arrowup、arrowdown）
有关可用快捷键的完整列表，请参阅
KeyboardEvent API 文档。请注意，KeyboardEvent.key 必须小写。usingInput
属性：usingInput?: string | boolean
默认情况下，usingInput 为 false，这意味着它仅在没有输入框处于焦点状态时触发。设置为 true 时，快捷键也会在任何输入框处于焦点状态时触发。
为了实现更高级的行为，usingInput 可以设置为输入框的名称，因此它仅在聚焦此特定输入框时触发。
<template>
<UInput v-model="query" name="queryInput" />
</template>
<script setup lang="ts">
const query = ref('')
defineShortcuts({
enter: {
usingInput: 'queryInput',
handler: () => {
// TODO
}
}
})
</script>
enter 快捷键仅在 queryInput 处于焦点状态时触发。
whenever
属性：whenever?: WatchSource<boolean>[]
whenever 允许对快捷键触发行为添加约束。此数组可以包含 Ref<boolean>、ComputedRef<boolean> 或 () => boolean。
defineShortcuts({
meta_k: {
usingInput: true,
handler: () => { isOpen.value = !isOpen.value }
},
escape: {
usingInput: true,
whenever: [isOpen],
handler: () => { isOpen.value = false }
}
})
escape 快捷键仅在 isOpen 为 true 时触发。
简单快捷键
如果快捷键不需要任何配置，则可以将其写为函数。
defineShortcuts({
'?': () => openHelpModal()
})
useShortcuts
为了根据用户的操作系统显示应用中的快捷键，你可以使用 useShortcuts 可组合函数。
<script setup lang="ts">
const { metaSymbol } = useShortcuts()
</script>
<template>
<UKbd>{{ metaSymbol }}</UKbd>
</template>
metaSymbol 将在 macOS 上显示 ⌘，在其他任何操作系统上显示 Ctrl