chinese-keyboard.js
Version:
中文键盘：支持VUE2、VUE3、REACT、以及原生JS
317 lines (251 loc) • 8.02 kB
Markdown
# 🎹 Chinese Keyboard.js
一个轻量级的中文虚拟键盘组件，支持拼音输入、多种主题和多框架集成。
## ✨ 特性
- 🇨🇳 **智能拼音输入** - 支持全拼输入，智能候选词
- 🎨 **多种主题** - 深色、浅色、中国红三套主题
- 📱 **响应式设计** - 完美适配桌面和移动端
- 🔧 **多框架支持** - 支持 Vue2、Vue3、React 以及原生 JS
- 📝 **自定义词库** - 支持添加自定义拼音词库
- ⚡ **轻量级** - 无依赖，体积小巧
## 🚀 快速开始
### 基本用法
```javascript
// 创建键盘实例
const keyboard = new ChineseKeyboard();
```
### 完整配置
```javascript
const keyboard = new ChineseKeyboard({
// 目标容器元素（可选）
target: document.getElementById("my-container"),
// 或者使用 container（与 target 等效）
container: document.getElementById("my-container"),
// 自动显示键盘（默认: true）
autoShow: true,
// 自动隐藏键盘（默认: true）
autoHide: true,
// 默认输入模式（默认: "chinese"）
mode: "chinese", // "chinese" | "english" | "symbol"
// 回调函数
onInput: function (text) {
console.log("输入内容:", text);
},
onModeChange: function (mode) {
console.log("模式切换:", mode);
},
onShow: function () {
console.log("键盘显示");
},
onHide: function () {
console.log("键盘隐藏");
},
});
```
## 📖 配置选项 (Options)
| 参数 | 类型 | 默认值 | 说明 |
| ---------------------- | ----------- | --------- | -------------------------------------------- |
| `target` / `container` | HTMLElement | null | 键盘容器元素，不指定则自动创建 |
| `autoShow` | Boolean | true | 是否在输入框获得焦点时自动显示键盘 |
| `autoHide` | Boolean | true | 是否在输入框失去焦点时自动隐藏键盘 |
| `mode` | String | "chinese" | 默认输入模式：`chinese`、`english`、`symbol` |
| `onInput` | Function | null | 输入回调函数，参数为输入的文本 |
| `onModeChange` | Function | null | 模式切换回调函数，参数为当前模式 |
| `onShow` | Function | null | 键盘显示回调函数 |
| `onHide` | Function | null | 键盘隐藏回调函数 |
## 🛠️ 主要方法
### 显示/隐藏键盘
```javascript
// 显示键盘
keyboard.show();
// 隐藏键盘
keyboard.hide();
```
### 自定义词库
```javascript
// 添加自定义拼音词库
keyboard.addCustomDictionary("hd", ["好的", "互动", "后端", "很多"]);
keyboard.addCustomDictionary("zt", ["载体", "状态", "昨天", "主题"]);
```
## 🎨 主题配置
项目提供三套预设主题，在 HTML 中引入对应的 CSS 文件：
```html
<!-- 深色主题 -->
<link rel="stylesheet" href="src/keyboard-dark.css" />
<!-- 浅色主题 -->
<link rel="stylesheet" href="src/keyboard-light.css" />
<!-- 中国红主题 -->
<link rel="stylesheet" href="src/keyboard-china-red.css" />
```
## 📁 文件结构
```
chinese-keyboard/
├── src/
│ ├── keyboard.js # 核心键盘逻辑
│ ├── simplified.js # 简体中文拼音字库
│ ├── keyboard-dark.css # 深色主题样式
│ ├── keyboard-light.css # 浅色主题样式
│ └── keyboard-china-red.css # 中国红主题样式
├── demo.html # 完整演示示例
└── README.md
```
## 📦 安装
### NPM 安装
```bash
npm install chinese-keyboard.js
```
### CDN 引入
```html
<!-- 引入键盘脚本 -->
<script src="https://cdn.jsdelivr.net/npm/chinese-keyboard.js/src/keyboard.js"></script>
<!-- 引入主题样式 -->
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/chinese-keyboard.js/src/keyboard-dark.css"
/>
```
## 🌟 框架集成示例
### 🟢 Vue 3 示例
```js
// 在main.js引入键盘以及样式并创建即可，其余的可以不需要写任何代码
// 如果使用 npm 安装
import ChineseKeyboard from "chinese-keyboard.js";
/* 引入键盘样式 */
import "chinese-keyboard.js/src/keyboard-dark.css";
const keyboard = new ChineseKeyboard();
```
### 🟨 原生 JavaScript 示例
```html
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>原生 JS 中文键盘示例</title>
<!-- 通过 CDN 引入样式 -->
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/chinese-keyboard.js/src/keyboard-dark.css"
/>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, sans-serif;
max-width: 600px;
margin: 50px auto;
padding: 20px;
background: #f5f5f5;
}
.container {
background: white;
padding: 30px;
border-radius: 12px;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}
.input-group {
margin-bottom: 20px;
}
label {
display: block;
margin-bottom: 8px;
font-weight: 600;
color: #333;
}
input,
textarea {
width: 100%;
padding: 12px;
font-size: 16px;
border: 2px solid #ddd;
border-radius: 8px;
transition: border-color 0.3s;
box-sizing: border-box;
}
input:focus,
textarea:focus {
outline: none;
border-color: #007bff;
}
.status {
background: #e3f2fd;
padding: 15px;
border-radius: 8px;
margin: 20px 0;
}
.controls {
display: flex;
gap: 10px;
flex-wrap: wrap;
}
button {
padding: 10px 20px;
border: none;
border-radius: 6px;
background: #007bff;
color: white;
font-size: 14px;
cursor: pointer;
transition: background 0.3s;
}
button:hover {
background: #0056b3;
}
</style>
</head>
<body>
<div class="container">
<h1>🎹 原生 JavaScript 中文键盘</h1>
<div class="input-group">
<label for="text-input">单行输入框:</label>
<input type="text" id="text-input" placeholder="点击开始输入中文..." />
</div>
<div class="input-group">
<label for="textarea-input">多行文本框:</label>
<textarea
id="textarea-input"
rows="4"
placeholder="在这里输入更多内容..."
></textarea>
</div>
</div>
<!-- 通过 CDN 引入键盘脚本 -->
<script src="https://cdn.jsdelivr.net/npm/chinese-keyboard.js/src/keyboard.js"></script>
<script>
// 全局变量
let keyboard = null;
// 初始化键盘
function initKeyboard() {
keyboard = new ChineseKeyboard();
// 添加自定义词库
keyboard.addCustomDictionary("js", [
"JavaScript",
"前端开发",
"编程语言",
]);
keyboard.addCustomDictionary("web", [
"网页",
"网站",
"Web开发",
"前端",
]);
keyboard.addCustomDictionary("code", [
"代码",
"编程",
"开发",
"程序员",
]);
}
</script>
</body>
</html>
```
## 📖 更多示例
想了解更多功能和用法，请参考 **[demo.html](demo.html)** 文件，其中包含：
- 📝 输入框和文本域的完整测试
- 🎨 主题切换演示
- 🔧 高级配置示例
- 📱 响应式布局展示
## 📄 许可证
MIT License
## 👤 作者
叶 1 福建
---
⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！