# asai-vue-keyboard 中文文档

规范地址：https://npmcn.com/package/asai-vue-keyboard/

版本：0\.2\.29
npm 元数据更新时间：2026-11-03T02:41:34.147Z
中文译文更新时间：2026-11-03T03:56:32.276Z
软件包许可：ISC

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/asai-vue-keyboard
原文对照：https://npmcn.com/package/asai-vue-keyboard/?lang=original
源码仓库：https://gitee.com/guoyansai/asaiplug/asai-vue-keyboard

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：91.4 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-04-03T03:43:46.060Z
- 最新版本发布：2026-11-03T02:41:33.949Z
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

对你说

## 安装

```sh
npm install asai-vue-keyboard
```

也可以使用：`pnpm add asai-vue-keyboard`、`yarn add asai-vue-keyboard`、`bun add asai-vue-keyboard`

## README

# asai-vue-keyboard — 虚拟键盘组件

## 包信息

| 建议 npm 名 | 入口文件 | $fn / 注入键 | 类型 |
| --- | --- | --- | --- |
| `@estun/asai-vue-keyboard` | `src/index.ts` | `AsaiVueKeyboard` → `{ AsKeyBoardVue }` | Feature |

## 概述

`asai-vue-keyboard` 提供可拖拽、可缩放的**虚拟软键盘**，适用于触屏 HMI、机器人操作区与登录场景，通过 `$global.keyboard` 控制显示与布局。

## 集成方式

```typescript
// monorepo — webclient/src/App.vue（首屏同步）
import AsaiVueKeyboard from './plugs/asai-vue-keyboard/src/index';
// npm
// import AsaiVueKeyboard from '@estun/asai-vue-keyboard';

useProvide({ plugs: { AsaiVueKeyboard } });
```

```vue
<AsKeyBoardVue :ujt="ujt" :opt="{ pos: { auto: true }, scale: 1 }" />
```

## 独立性约束

-   **禁止** cross-import 其它 `plugs/*`。
-   `v-keyboard` 指令（host-directives）通过 `ujt` 运行时关联本组件，不在插件内 import directives。

## 主要 API / 导出

| 导出 | 说明 |
| --- | --- |
| `AsKeyBoardVue` | 键盘容器组件 |
| `useKeysConfig` | 按键映射初始化（内部） |
| Types | `KeyboardOpt`, `UjtContext`, `KeyPressParams` |

## 性能说明

-   **首屏同步**注册；键盘 UI 为单组件，体积适中。
-   窗口尺寸仅在 `onMounted` 读取一次；布局变更需业务侧监听 `resize`（若需要）。

## peerDependencies 建议

```json
{
  "peerDependencies": {
    "vue": "^3.4.0",
    "@estun/asai-vue-host-directives": "^1.0.0"
  }
}
```

* * *

## 配置参数

### opt

| 参数 | 说明 |
| --- | --- |
| `pos.auto` | 自动定位（底部居中） |
| `pos.x` / `pos.y` | 手动偏移 |
| `scale` | 缩放（配合 `v-popresizezoom`） |

### `$model.data.sys.keyboard`

| 参数 | 说明 |
| --- | --- |
| `cfg.size.*` | 宽高中限 |
| `mapkeys` / `bottomkeys` | 按键映射 |

### `$global.keyboard`

| 属性 | 说明 |
| --- | --- |
| `showkeyboard` | 显示/隐藏 |
| `areastyle` | 位置与尺寸 |
| `params.ot.style` | 外部样式覆盖 |

### Ctrl 组合键（仅软键盘，不监听物理键盘）

| 组合 | 行为 |
| --- | --- |
| Ctrl+X / C / V | 剪切 / 复制 / 粘贴（原有，未改） |
| Ctrl+F | 全屏 / 退出全屏（对齐 `$fn.As` / `$fn.AsFull`；`padteach*` 跳过） |
| Ctrl+R | 刷新页面（对齐 `$fn.As.localReload`） |
| Ctrl+Space | 键盘复位到原点（原有） |

Ctrl / Shift 为粘滞开关：软键盘展开后即可按下，**不要求焦点在文本框**。顶栏用系统图标 `represent/fullScreen`、`represent/refresh` 直接全屏/刷新（`padteach*` 隐藏全屏按钮）。无 Ctrl 时 F/R 仍只插入字母。中文拼音只对 Ctrl+F/R 让路，不改 x/c/v。

## 文件结构

```
asai-vue-keyboard/
├── src/
│   ├── index.ts
│   ├── components/AsKeyBoardVue.vue
│   └── components/_use/useKeysConfig.ts
└── README.md
```

## 技术细节

-   遮罩 `pointer-events: none`，不阻挡下方交互
-   集成 `v-popresizezoom` 实现拖拽缩放
-   超出视口自动修正位置
-   Backspace 在光标位置 0 时无操作（`backspaceEdit`），避免误删末尾字符
-   顶栏 Tab 为胶囊选中态；拖拽握把与收起按钮分区，减少误触
-   按键按语义分色（Enter / Space / 修饰键）；触屏补 `is-pressed` 与短震动（无 vibrate 则跳过）
-   中文候选为胶囊条；展开面板带阴影与安全区，不改入键门闩

## 测试

```bash
npx tsx --test .youmengyu/test/unit/webclient/plugs/asai-vue-keyboard/*.test.mjs
node .youmengyu/test/asaitest.mjs
```

## 常见问题

### asai-vue-keyboard 是什么？

对你说

### 如何安装 asai-vue-keyboard？

在项目目录运行 npm install asai-vue-keyboard，或使用 pnpm add / yarn add / bun add。

### asai-vue-keyboard 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### asai-vue-keyboard 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### asai-vue-keyboard 可以商用吗？

asai-vue-keyboard 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### asai-vue-keyboard 还在维护吗？

最新版本 0\.2\.29 发布于 2026/11/03（今天）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/04/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。