BizShortcutInput 快捷键录入

组合键录入与展示件：点击进入录制态捕获按下组合，修饰键标准化（ctrl / alt / shift / meta 顺序统一、键帽展示）、主键必含修饰键可配、冲突清单比对红警、Esc 取消 / 退格清空、只读回显 kbd 键帽。适用于系统快捷键设置、命令面板配置、大屏 / 收银快捷操作绑定。

基础用法

点击录制快捷键

当前值：（未设置）

点击盒子进入录制态 → 按 Ctrl+K 生成键帽；Esc 取消。

<script setup lang="ts">
/** 基础用法：点击进入录制态，按下组合键（如 Ctrl+K）生成键帽 */
import { ref } from 'vue'
import { BizShortcutInput } from 'vue3-ep-biz-lib'

const combo = ref('')
</script>

<template>
  <div>
    <BizShortcutInput v-model="combo" />
    <p style="margin: 8px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">当前值：{{ combo || '（未设置）' }}</p>
  </div>
</template>

显示代码

预设回显

CtrlShiftP

v-model 规范串（ctrl+shift+p）直接渲染键帽。

<script setup lang="ts">
/** 预设回显：v-model 规范串直接渲染键帽（ctrl+shift+p） */
import { ref } from 'vue'
import { BizShortcutInput } from 'vue3-ep-biz-lib'

const combo = ref('ctrl+shift+p')
</script>

<template>
  <BizShortcutInput v-model="combo" />
</template>

显示代码

冲突检测

点击录制快捷键

已占用：ctrl+k / ctrl+shift+p / alt+f4（试试录制 Ctrl+K）

conflicts 传入已占用清单，撞车红框 + 「与已有快捷键冲突」并外抛 conflict。

<script setup lang="ts">
/** 冲突检测：与已占用清单撞车时红框 + 「与已有快捷键冲突」提示并外抛 conflict */
import { ref } from 'vue'
import { BizShortcutInput } from 'vue3-ep-biz-lib'

const combo = ref('')
const occupied = ['ctrl+k', 'ctrl+shift+p', 'alt+f4']
</script>

<template>
  <div>
    <BizShortcutInput v-model="combo" :conflicts="occupied" />
    <p style="margin: 8px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      已占用：{{ occupied.join(' / ') }}（试试录制 Ctrl+K）
    </p>
  </div>
</template>

显示代码

允许单键

f2

require-modifier=false，单个字母 / F 键（如 F2）也可作为快捷键。

<script setup lang="ts">
/** 允许单键：require-modifier=false，单个字母 / F 键也可作为快捷键 */
import { ref } from 'vue'
import { BizShortcutInput } from 'vue3-ep-biz-lib'

const combo = ref('f2')
</script>

<template>
  <BizShortcutInput v-model="combo" :require-modifier="false" />
</template>

显示代码

只读回显

CtrlAltDel

帮助文档 / 快捷键速查：纯展示键帽，不可录制不可清空。

<script setup lang="ts">
/** 只读回显：纯展示键帽，不可录制不可清空（帮助文档 / 快捷键速查） */
import { BizShortcutInput } from 'vue3-ep-biz-lib'
</script>

<template>
  <BizShortcutInput model-value="ctrl+alt+delete" readonly />
</template>

显示代码

禁用

CtrlS

置灰不可交互。

<script setup lang="ts">
/** 禁用：置灰不可交互 */
import { BizShortcutInput } from 'vue3-ep-biz-lib'
</script>

<template>
  <BizShortcutInput model-value="ctrl+s" disabled />
</template>

显示代码

清空

AltEnter

录制态按退格清空；非录制态悬停清空图标一键清除。

<script setup lang="ts">
/** 清空：录制态按退格清空，非录制态悬停清空图标一键清除 */
import { ref } from 'vue'
import { BizShortcutInput } from 'vue3-ep-biz-lib'

const combo = ref('alt+enter')
</script>

<template>
  <BizShortcutInput v-model="combo" />
</template>

显示代码

事件流

点击录制快捷键

change / conflict / record-start / record-end 日志。

<script setup lang="ts">
/** 事件流：change / conflict / record-start / record-end 日志 */
import { ref } from 'vue'
import { BizShortcutInput } from 'vue3-ep-biz-lib'

const combo = ref('')
const logs = ref<string[]>([])
const log = (msg: string): void => {
  logs.value = [`[${new Date().toLocaleTimeString()}] ${msg}`, ...logs.value].slice(0, 5)
}
</script>

<template>
  <div>
    <BizShortcutInput
      v-model="combo"
      :conflicts="['ctrl+k']"
      @change="(c) => log(`change → ${c}`)"
      @conflict="(c) => log(`conflict → ${c}`)"
      @record-start="log('record-start')"
      @record-end="(a) => log(`record-end applied=${a}`)"
    />
    <p v-for="l in logs" :key="l" style="margin: 4px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">{{ l }}</p>
  </div>
</template>

显示代码

特殊键

Ctrl↑

试试录制 Ctrl+↓、Alt+F3、Shift+Space

方向键 / F1~F12 / Space / Enter 均可录制（展示 ↑ ↓ F3 Space Enter）。

<script setup lang="ts">
/** 特殊键：方向键 / F1~F12 / Space / Enter 均可录制（展示为 ↑ ↓ F3 Space Enter） */
import { ref } from 'vue'
import { BizShortcutInput } from 'vue3-ep-biz-lib'

const combo = ref('ctrl+up')
</script>

<template>
  <div>
    <BizShortcutInput v-model="combo" />
    <p style="margin: 8px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      试试录制 Ctrl+↓、Alt+F3、Shift+Space
    </p>
  </div>
</template>

显示代码

设置表场景

多条快捷键互为冲突清单，录制撞车即时红警。

<script setup lang="ts">
/** 设置表场景：多条快捷键互为冲突清单（录制撞车即时红警） */
import { ref } from 'vue'
import { ElTable, ElTableColumn } from 'element-plus'
import { BizShortcutInput } from 'vue3-ep-biz-lib'

const items = ref([
  { id: 1, name: '全局搜索', combo: 'ctrl+k' },
  { id: 2, name: '命令面板', combo: 'ctrl+shift+p' },
  { id: 3, name: '刷新数据', combo: '' },
])

const conflictsOf = (id: number): string[] =>
  items.value.filter((x) => x.id !== id && x.combo).map((x) => x.combo)
</script>

<template>
  <ElTable :data="items" size="small" style="width: 100%">
    <ElTableColumn prop="name" label="功能" width="120" />
    <ElTableColumn label="快捷键" min-width="260">
      <template #default="{ row }">
        <BizShortcutInput v-model="row.combo" :conflicts="conflictsOf(row.id)" size="small" />
      </template>
    </ElTableColumn>
  </ElTable>
</template>

显示代码

Props

属性名	类型	默认值	说明
v-model	string	''	组合键规范串（ctrl+shift+p；空串未设置）
require-modifier	boolean	true	主键必须搭配 Ctrl / Alt / Win 修饰键
conflicts	string[]	[]	已占用快捷键清单（撞车红警 + conflict 外抛）
placeholder	string	'点击录制快捷键'	占位提示
disabled	boolean	false	禁用（不可录制）
readonly	boolean	false	只读回显
size	'small' | 'default' | 'large'	'default'	尺寸

Events

事件名	参数	说明
change	(combo: string)	组合键确认（含清空）
conflict	(combo: string)	与 conflicts 清单撞车
record-start	—	进入录制态
record-end	(applied: boolean)	退出录制态（是否已落值）

Expose

属性/方法	说明
toggleRecord	() => void 编程开启 / 关闭录制

口径说明

• 规范串：小写、+ 连接、修饰键固定顺序 ctrl → alt → shift → meta（如 ctrl+alt+enter）；单字符主键小写、方向键 up/down/left/right、空格 space。
• 键帽展示：修饰键 Ctrl / Alt / Shift / Win，字母大写、方向键箭头符号；meta 按 Windows 语义展示为 Win（macOS 场景可自行映射 ⌘）。
• 录制约束：纯修饰键按下不落值等待组合；require-modifier=true 时 shift 单独修饰不算（需 Ctrl / Alt / Win 至少其一）；Esc 取消录制、退格清空当前值。