# ticktype

**Repository Path**: tick_3/ticktype

## Basic Information

- **Project Name**: ticktype
- **Description**: 支持键盘鼠标升级。。。
- **Primary Language**: JavaScript
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TickType 键盘配置器

## 🚀 快速开始

```bash
npm install
npm run dev
```

## 📦 构建

```bash
npm run build        # 原来的网页构建，仍然保留
npm run build:exe    # 构建 Windows exe 安装包
```

---

# 📋 项目概述

**TickType** 是一个基于 Web 的**键盘配置器应用**，专门用于配置和管理机械键盘（特别是霍尔效应键盘）的各种参数。项目使用 GPL-3.0 开源协议。

## 🏗️ 技术栈

### 核心框架
- **React 18.2** + **TypeScript** - 主框架
- **Vite 5.2** - 构建工具
- **Redux Toolkit 2.2** - 状态管理
- **Styled Components 6.1** - CSS-in-JS 样式方案
- **Wouter 3.3** - 轻量级路由
- **i18next** - 国际化（支持中文、英文、日文、韩文）

### 特色依赖
- **WebHID API** - 通过浏览器直接与 USB HID 设备通信
- **@ijprest/kle-serial** - 键盘布局编辑器序列化
- **Framer Motion** - 动画库
- **React Draggable** - 拖拽功能

## 📁 工程结构

```
ticktype/
├── src/
│   ├── main.tsx                    # 应用入口
│   ├── App.tsx                     # 根组件
│   ├── components/                 # UI 组件
│   │   ├── configure/             # 配置相关组件
│   │   │   ├── configure.tsx      # 配置主页面
│   │   │   ├── home/              # 首页（设备连接）
│   │   │   ├── keyboard/          # 键盘配置页面
│   │   │   ├── calibration/       # 校准页面
│   │   │   ├── setting/           # 设置页面
│   │   │   ├── lighting/          # RGB 灯效配置
│   │   │   ├── performance/       # 性能配置（AP/RT）
│   │   │   ├── adv-key/           # 高级按键功能
│   │   │   ├── custom-key/        # 自定义按键
│   │   │   └── side/              # 侧边栏
│   │   ├── common/                # 通用组件（菜单、弹窗等）
│   │   ├── form/                  # 表单组件
│   │   └── icons/                 # 图标组件
│   ├── store/                     # Redux 状态管理
│   │   ├── store.ts               # Store 配置
│   │   ├── deviceSlice.ts         # 设备状态
│   │   ├── configureSlice.ts      # 配置状态
│   │   ├── keymapSlice.ts         # 键位映射
│   │   ├── actuationSlice.ts      # 触发点配置
│   │   ├── advkeySlice.ts         # 高级按键
│   │   ├── rgbSlice.ts            # RGB 灯效
│   │   ├── macroSlice.ts          # 宏功能
│   │   ├── firmwareSlice.ts       # 固件管理
│   │   └── ...
│   ├── utils/                     # 工具函数
│   │   ├── hid-api.ts             # HID 通信 API
│   │   ├── keyboard-service.ts    # 键盘服务
│   │   ├── actuation-api.ts       # 触发点 API
│   │   ├── keycodes.ts            # 键码定义
│   │   ├── advanced-keys.ts       # 高级按键逻辑
│   │   └── ...
│   ├── types/                     # TypeScript 类型定义
│   │   ├── types.ts               # 通用类型
│   │   └── via.ts                 # VIA 协议类型
│   ├── locales/                   # 国际化资源
│   │   ├── common/                # 通用翻译
│   │   ├── setting/               # 设置翻译
│   │   ├── rgb/                   # RGB 翻译
│   │   └── advkey/                # 高级按键翻译
│   └── assets/                    # 静态资源
│       ├── keycodes-*.json        # 键码配置
│       └── mock-devices/          # 模拟设备数据
├── kbconfigs/                     # 键盘配置文件
│   ├── configs/                   # 配置 JSON
│   └── definitions/               # 键盘定义
└── scripts/                       # 构建脚本
    └── build-configs.js           # 配置构建脚本
```

## 🔑 核心业务逻辑

### 1. 设备连接与管理

- 使用 **WebHID API** 检测和连接 USB 键盘设备
- 支持三种模式：
  - `normal` - 正常模式（真实设备）
  - `mock` - 模拟模式（开发测试）
  - `edit` - 编辑模式
- 监听设备的连接/断开事件
- 设备信息包括：vendorId、productId、固件版本、序列号等

### 2. HID 通信协议

实现了完整的 VIA 协议通信：

**核心命令**：
- `GET_PROTOCOL_VERSION` - 获取协议版本
- `DYNAMIC_KEYMAP_*` - 键位映射相关
- `CUSTOM_GET/SET_VALUE` - 自定义值读写
- `TAB_ACTUATION` - 触发点配置
- `TAB_BLOCKS` - 固件更新、文件传输

**通信特点**：
- 命令队列机制，确保顺序执行
- 支持分块传输大数据（宏、固件等）
- 错误处理和重试机制

### 3. 键盘配置功能

#### 主要配置页面：

**a) Keyboard（键盘配置）**
- **Actuation Point (AP)** - 触发点调整（0.1-4.0mm）
- **Rapid Trigger (RT)** - 快速触发（动态触发点）
- **Remap** - 按键重映射
- **Advanced Keys** - 高级按键功能：
  - DKS (Dynamic Keystroke) - 动态按键
  - MPT (Multi-Point Trigger) - 多点触发
  - MT (Mod-Tap) - 修饰键/点击
  - END (Enhanced Delay) - 增强延迟
  - TGL (Toggle) - 切换键
  - SOCD (Simultaneous Opposite Cardinal Directions) - 同时相反方向处理
  - AT (Auto Tap) - 自动点击
  - RS (Rapid Strike) - 快速连击
- **RGB Effects** - RGB 灯效配置
- **Profile** - 配置文件管理

**b) Calibration（校准）**
- 霍尔传感器校准
- 轴体行程校准
- 死区调整

**c) Settings（设置）**
- NKRO（全键无冲）
- 固件更新
- 语言切换
- 其他系统设置

### 4. 状态管理架构

使用 Redux Toolkit 管理 14 个 Slice：

```typescript
{
  counter,        // 计数器
  settings,       // 应用设置
  configure,      // 配置状态
  device,         // 设备信息
  definitions,    // 键盘定义
  keymap,         // 键位映射
  macro,          // 宏
  configureMenu,  // 配置菜单
  tabConfig,      // 标签配置
  actuation,      // 触发点
  firmware,       // 固件
  advkey,         // 高级按键
  rgb,            // RGB 灯效
}
```

### 5. 配置文件系统

**ProfileFile 结构**：
```typescript
{
  name: string,              // 键盘名称
  profileName: string,       // 配置文件名
  vendorProductId: number,   // VID/PID
  layers: string[][],        // 多层键位映射
  layoutOptions: number[],   // 布局选项
  macros: string[],          // 宏定义
  encoders: [string, string][][], // 旋钮配置
  actuation: ActuationData[], // 触发点数据
  advkey: AdvanceKey[][],    // 高级按键
  menuData: CustomMenuData,  // 自定义菜单
  rgbMatrix: string[],       // RGB 矩阵
}
```

支持：
- 本地存储（LocalStorage）
- 导入/导出 JSON 文件
- 多配置文件切换
- 云端分享（通过 API）

### 6. 国际化支持

- 自动检测浏览器语言
- 支持 4 种语言：中文、英文、日文、韩文
- 动态加载语言包
- 根据语言切换字体

### 7. 霍尔效应键盘特性

项目专门针对霍尔效应键盘（如 NAJA68 HE）优化：

- **模拟量检测** - 实时监测按键行程
- **可调触发点** - 0.1mm 精度调整
- **快速触发** - 基于行程变化触发
- **多点触发** - 一个按键多个触发点
- **动态按键** - 根据行程执行不同动作

## 🔄 数据流

```
用户操作 → React 组件 → Redux Action → 
→ Thunk/Async → HID API → USB 设备 →
→ 设备响应 → Redux State 更新 → UI 重新渲染
```

## 🎯 项目特点

1. **直接硬件通信** - 无需驱动，浏览器直接与键盘通信
2. **实时配置** - 修改立即生效，无需重启
3. **可视化编辑** - 图形化键盘布局，直观操作
4. **专业功能** - 支持高级玩家需求（宏、多层、高级按键）
5. **跨平台** - 基于 Web，支持 Windows/Mac/Linux
6. **开源生态** - 兼容 VIA 协议，支持多种键盘

## 📊 适用场景

- 机械键盘爱好者自定义配置
- 电竞玩家优化按键响应
- 程序员自定义工作流快捷键
- 键盘厂商提供配置工具

## 📄 许可证

GPL-3.0 License