yjx-sdk-mouse 0.1.9 → 0.1.13

package/README.md

@@ -1,336 +1,334 @@
-# yjx-sdk-mouse
-
-永佳新鼠标 WebHID SDK，用于在浏览器中连接兼容设备，并读取或写入 DPI、回报率、灯效、休眠策略、按键映射和宏配置。
-
-## 安装
-
-```bash
-npm install yjx-sdk-mouse
-```
-
-也可以使用 pnpm：
-
-```bash
-pnpm add yjx-sdk-mouse
-```
-
-## 使用条件
-
-- 运行环境需要提供 WebHID，即存在 `navigator.hid`。
-- 页面需要运行在安全上下文中，例如 HTTPS 或本地开发环境。
-- 首次选择设备必须由用户操作触发，因此请在按钮点击等事件中调用 `requestDevices()`。
-- SDK 是 ESM 包，请使用 `import` 引入。
-
-```ts
-if (!('hid' in navigator)) {
-  throw new Error('当前浏览器不支持 WebHID');
-}
-```
-
-## 快速开始
-
-```ts
-import { createMouse } from 'yjx-sdk-mouse';
-
-const mouse = createMouse();
-
-document.querySelector('#connect')?.addEventListener('click', async () => {
-  // 首次连接时弹出浏览器设备选择框。
-  const selected = await mouse.requestDevices();
-  const device = selected[0];
-
-  if (!device) {
-    console.log('未选择设备');
-    return;
-  }
-
-  await mouse.init(device.id);
-  console.log('已连接：', mouse.currentDevice);
-
-  const dpi = await mouse.dpi.get();
-  console.log('DPI 配置：', dpi);
-});
-```
-
-浏览器已经授权过设备时，可以先用 `getDevices()` 静默读取：
-
-```ts
-const devices = await mouse.getDevices();
-if (devices[0]) {
-  await mouse.init(devices[0].id);
-}
-```
-
-使用完毕后关闭设备：
-
-```ts
-await mouse.closeDevice();
-```
-
-## 创建设备实例
-
-### 使用默认设备参数
-
-`createMouse()` 和 `Mouse.createDefault()` 都会使用 SDK 内置的有线、2.4G 接收器设备过滤参数。
-
-```ts
-import Mouse, { createMouse } from 'yjx-sdk-mouse';
-
-const mouse1 = createMouse();
-const mouse2 = Mouse.createDefault();
-```
-
-### 自定义 VID、PID 和 HID Collection
-
-```ts
-import { createMouse } from 'yjx-sdk-mouse';
-
-const mouse = createMouse({
-  configs: [
-    {
-      vendorId: 0xa8a5,
-      productId: 0x2255,
-      usagePage: 0xff01,
-      usage: 0x10,
-    },
-  ],
-  timeout: 3000,
-});
-```
-
-## DPI
-
-```ts
-const profile = await mouse.dpi.get();
-// { currentIndex, pollRate, levels }
-
-// 切换到第 2 档，索引从 0 开始。
-await mouse.dpi.setCurrentIndex(1);
-
-// 修改第 1 档 DPI。
-await mouse.dpi.setLevel(0, 1600);
-
-// 一次写入完整配置。
-await mouse.dpi.set({
-  currentIndex: 0,
-  pollRate: 1000,
-  levels: [800, 1200, 1600, 2400, 3200, 5000],
-});
-```
-
-如果界面中维护了尚未写入的本地配置，请使用 `setCurrentIndexFrom()` 或 `setLevelFrom()`，避免先执行 `get()` 而覆盖本地修改：
-
-```ts
-const draft = await mouse.dpi.get();
-draft.levels[0] = 1200;
-
-await mouse.dpi.setLevelFrom(draft, 1, 1600);
-```
-
-## 性能设置
-
-```ts
-const settings = await mouse.performance.get();
-console.log(settings);
-
-await mouse.performance.set({
-  pollRate: 1000,
-  sleepMinutes: 10,
-  neverSleep: false,
-  scrollReverse: false,
-  wakeOnMove: true,
-});
-
-await mouse.performance.setPollRate(500);
-```
-
-支持的回报率为 `125 | 250 | 500 | 1000` Hz。
-
-## 灯效
-
-灯效通过完整 `0x0F` 配置包写入，协议字节在 `packet[9]`，写入时会保留当前 DPI、回报率等其它配置。
-
-| 协议字节 | 三档机型 | 五档机型 |
-| --- | --- | --- |
-| `0` | 循环呼吸 `breath` | 波浪 `wave` |
-| `1` | 常亮 `steady` | 霓虹 `neon` |
-| `2` | 灭灯 `off` | 巡回闪 `chase` |
-| `3` | — | YOYO球 `yoyo` |
-| `4` | — | 单向闪 `oneWayFlash` |
-
-```ts
-import { LightMode } from 'yjx-sdk-mouse';
-
-const light = await mouse.light.get();
-// { effect: 'breath' | 'steady' | 'off' | 'yoyo' | 'oneWayFlash', mode: 0 | 1 | 2 | 3 | 4 }
-
-await mouse.light.set('wave');
-await mouse.light.set(LightMode.Neon);
-await mouse.light.setYoyo();
-await mouse.light.setOneWayFlash();
-```
-
-便捷方法：`setBreath()`、`setSteady()`、`setOff()`、`setWave()`、`setNeon()`、`setChase()`、`setYoyo()`、`setOneWayFlash()`。
-
-## 按键映射
-
-```ts
-import { KEY_PRESETS } from 'yjx-sdk-mouse';
-
-const mapping = await mouse.button.get();
-console.log(mapping);
-
-const mutePreset = KEY_PRESETS.find((item) => item.id === 'mute');
-if (mutePreset) {
-  await mouse.button.setSlot('back', mutePreset);
-}
-
-const volumeDown = KEY_PRESETS.find((item) => item.id === 'volume-down');
-if (volumeDown) {
-  await mouse.button.setSlot('scrollLeft', volumeDown);
-  await mouse.button.setSlot('scrollRight', volumeDown);
-  await mouse.button.setSlot('extra', volumeDown);
-}
-
-await mouse.button.resetSlot('scrollLeft');
-await mouse.button.resetSlot('extra');
-await mouse.button.resetAll();
-```
-
-可通过以下导出项构建按键配置界面：
-
-- `KEY_PRESETS`：全部预设。
-- `KEYBOARD_PRESETS`：键盘按键预设。
-- `COMMAND_PRESETS`：系统和组合命令预设。
-- `COMMAND_PRESET_GROUPS`：已分组的命令预设。
-- `BUTTON_SLOTS`、`BUTTON_SLOT_LABEL`：鼠标按键槽位和显示名称（含 `extra` 附加键、`scrollLeft` 左滚、`scrollRight` 右滚）。
-- `scroll-left` / `scroll-right` / `disable`：左右滚动和禁用预设。
-
-## 宏
-
-`macroIndex` 范围是 `0..31`。键盘的 `keyCode` 使用 USB HID Keyboard Usage，例如字母 A 为 `0x04`。
-
-```ts
-import type { MouseMacro } from 'yjx-sdk-mouse';
-
-const macros: MouseMacro[] = [
-  {
-    actions: [
-      { type: 'keyboard', keyCode: 0x04, action: 'keydown', delay: 20 },
-      { type: 'keyboard', keyCode: 0x04, action: 'keyup', delay: 20 },
-      { type: 'mouse', button: 'left', action: 'mousedown', delay: 20 },
-      { type: 'mouse', button: 'left', action: 'mouseup', delay: 20 },
-    ],
-  },
-];
-
-// 写入 profile 0，并把第 0 个宏分配给后退键。
-await mouse.macro.setAndAssign(
-  'back',
-  macros,
-  {
-    macroIndex: 0,
-    repeat: 1,
-    triggerMode: 0,
-  },
-  0,
-);
-```
-
-也可以分开写入和分配：
-
-```ts
-await mouse.macro.set(macros, 0);
-await mouse.macro.assignButton('back', { macroIndex: 0 });
-```
-
-## 设备信息和事件
-
-```ts
-const info = await mouse.getDeviceInfo();
-console.log(info.boardId, info.firmwareVersion);
-
-const battery = await mouse.getBatteryStatus();
-console.log(`电量 ${battery.level}%`, battery.usbConnected ? 'USB 已连接' : '无线连接');
-
-const sleepStatus = await mouse.getSleepStatus();
-console.log('当前状态：', sleepStatus.sleeping ? '休眠' : '唤醒');
-
-mouse.on('sleepChange', (event) => {
-  console.log(event.state === 'sleep' ? '设备进入休眠' : '设备已唤醒');
-});
-
-mouse.on('statusChange', (event) => {
-  console.log('DPI 档位：', event.dpiIndex);
-  console.log('回报率：', event.pollRate);
-});
-
-mouse.on('usbChange', (event) => {
-  console.log('USB 状态：', event.type);
-});
-```
-
-取消监听：
-
-```ts
-const handleStatus = (event: { dpiIndex: number }) => {
-  console.log(event.dpiIndex);
-};
-
-mouse.on('statusChange', handleStatus);
-mouse.off('statusChange', handleStatus);
-```
-
-## 恢复出厂设置
-
-此操作会重置性能、DPI、按键和宏配置：
-
-```ts
-const result = await mouse.other.factoryReset();
-console.log(result);
-```
-
-## 原始协议调用
-
-只有在需要扩展设备协议时才建议使用：
-
-```ts
-const response = await mouse.sendRaw(new Uint8Array(64));
-await mouse.sendRawNoResponse(new Uint8Array(64));
-```
-
-## 主要 API
-
-| API | 说明 |
-| --- | --- |
-| `getDevices()` | 获取浏览器已经授权的兼容设备 |
-| `requestDevices()` | 打开浏览器设备选择器 |
-| `init(id)` | 打开设备并执行连接握手 |
-| `closeDevice()` | 关闭当前设备 |
-| `getDeviceInfo()` | 获取板卡和固件信息 |
-| `getFirmwareVersion(refresh?)` | 获取固件版本，可选择强制刷新 |
-| `getBatteryStatus()` / `getBattery()` | 通过 0x30 获取电量百分比和 USB 状态 |
-| `getSleepStatus()` | 通过 0xED 主动查询当前休眠/唤醒状态 |
-| `on('sleepChange', handler)` | 监听 0xED 休眠和唤醒主动上报 |
-| `dpi` | DPI 档位读取和写入 |
-| `performance` | 回报率、休眠、滚轮和唤醒设置 |
-| `light` | 灯效读取和写入（循环呼吸 / 常亮 / 灭灯 / 波浪 / 霓虹 / 巡回闪 / YOYO球 / 单向闪） |
-| `button` | 按键映射读取和写入 |
-| `macro` | 宏数据写入和按键分配 |
-| `other.factoryReset()` | 恢复出厂设置 |
-
-## 错误处理
-
-所有设备操作都返回 Promise，建议统一使用 `try/catch`：
-
-```ts
-try {
-  const devices = await mouse.requestDevices();
-  if (devices[0]) {
-    await mouse.init(devices[0].id);
-  }
-} catch (error) {
-  console.error('鼠标连接失败：', error);
-}
-```
-
+# yjx-sdk-mouse
+
+永佳新鼠标 WebHID SDK，用于在浏览器中连接兼容设备，并读取或写入 DPI、回报率、灯效、休眠策略、按键映射和宏配置。
+
+## 安装
+
+```bash
+npm install yjx-sdk-mouse
+```
+
+也可以使用 pnpm：
+
+```bash
+pnpm add yjx-sdk-mouse
+```
+
+## 使用条件
+
+- 运行环境需要提供 WebHID，即存在 `navigator.hid`。
+- 页面需要运行在安全上下文中，例如 HTTPS 或本地开发环境。
+- 首次选择设备必须由用户操作触发，因此请在按钮点击等事件中调用 `requestDevices()`。
+- SDK 是 ESM 包，请使用 `import` 引入。
+
+```ts
+if (!('hid' in navigator)) {
+  throw new Error('当前浏览器不支持 WebHID');
+}
+```
+
+## 快速开始
+
+```ts
+import { createMouse } from 'yjx-sdk-mouse';
+
+const mouse = createMouse();
+
+document.querySelector('#connect')?.addEventListener('click', async () => {
+  // 首次连接时弹出浏览器设备选择框。
+  const selected = await mouse.requestDevices();
+  const device = selected[0];
+
+  if (!device) {
+    console.log('未选择设备');
+    return;
+  }
+
+  await mouse.init(device.id);
+  console.log('已连接：', mouse.currentDevice);
+
+  const dpi = await mouse.dpi.get();
+  console.log('DPI 配置：', dpi);
+});
+```
+
+浏览器已经授权过设备时，可以先用 `getDevices()` 静默读取：
+
+```ts
+const devices = await mouse.getDevices();
+if (devices[0]) {
+  await mouse.init(devices[0].id);
+}
+```
+
+使用完毕后关闭设备：
+
+```ts
+await mouse.closeDevice();
+```
+
+## 创建设备实例
+
+### 使用默认设备参数
+
+`createMouse()` 和 `Mouse.createDefault()` 都会使用 SDK 内置的有线、2.4G 接收器设备过滤参数。
+
+```ts
+import Mouse, { createMouse } from 'yjx-sdk-mouse';
+
+const mouse1 = createMouse();
+const mouse2 = Mouse.createDefault();
+```
+
+### 自定义 VID、PID 和 HID Collection
+
+```ts
+import { createMouse } from 'yjx-sdk-mouse';
+
+const mouse = createMouse({
+  configs: [
+    {
+      vendorId: 0xa8a5,
+      productId: 0x2255,
+      usagePage: 0xff01,
+      usage: 0x10,
+    },
+  ],
+  timeout: 3000,
+});
+```
+
+## DPI
+
+```ts
+const profile = await mouse.dpi.get();
+// { currentIndex, pollRate, levels }
+
+// 切换到第 2 档，索引从 0 开始。
+await mouse.dpi.setCurrentIndex(1);
+
+// 修改第 1 档 DPI。
+await mouse.dpi.setLevel(0, 1600);
+
+// 一次写入完整配置。
+await mouse.dpi.set({
+  currentIndex: 0,
+  pollRate: 1000,
+  levels: [800, 1200, 1600, 2400, 3200, 5000],
+});
+```
+
+如果界面中维护了尚未写入的本地配置，请使用 `setCurrentIndexFrom()` 或 `setLevelFrom()`，避免先执行 `get()` 而覆盖本地修改：
+
+```ts
+const draft = await mouse.dpi.get();
+draft.levels[0] = 1200;
+
+await mouse.dpi.setLevelFrom(draft, 1, 1600);
+```
+
+## 性能设置
+
+```ts
+const settings = await mouse.performance.get();
+console.log(settings);
+
+await mouse.performance.set({
+  pollRate: 1000,
+  sleepMinutes: 10,
+  neverSleep: false,
+  scrollReverse: false,
+  wakeOnMove: true,
+});
+
+await mouse.performance.setPollRate(500);
+```
+
+支持的回报率为 `125 | 250 | 500 | 1000` Hz。
+
+## 灯效
+
+灯效通过完整 `0x0F` 配置包写入，协议字节在 `packet[9]`，写入时会保留当前 DPI、回报率等其它配置。
+
+| 协议字节 | 三档机型 | 五档机型 |
+| --- | --- | --- |
+| `0` | 循环呼吸 `breath` | 波浪 `wave` |
+| `1` | 常亮 `steady` | 霓虹 `neon` |
+| `2` | 灭灯 `off` | 巡回闪 `chase` |
+| `3` | — | YOYO球 `yoyo` |
+| `4` | — | 单向闪 `oneWayFlash` |
+
+```ts
+import { LightMode } from 'yjx-sdk-mouse';
+
+const light = await mouse.light.get();
+// { effect: 'breath' | 'steady' | 'off' | 'yoyo' | 'oneWayFlash', mode: 0 | 1 | 2 | 3 | 4 }
+
+await mouse.light.set('wave');
+await mouse.light.set(LightMode.Neon);
+await mouse.light.setYoyo();
+await mouse.light.setOneWayFlash();
+```
+
+便捷方法：`setBreath()`、`setSteady()`、`setOff()`、`setWave()`、`setNeon()`、`setChase()`、`setYoyo()`、`setOneWayFlash()`。
+
+## 按键映射
+
+```ts
+import { KEY_PRESETS } from 'yjx-sdk-mouse';
+
+const mapping = await mouse.button.get();
+console.log(mapping.scrollLeft, mapping.scrollRight, mapping.extra);
+
+const mutePreset = KEY_PRESETS.find((item) => item.id === 'mute');
+if (mutePreset) {
+  await mouse.button.setSlot('back', mutePreset);
+
+  // 支持扩展槽位的机型：滚轮左倾、滚轮右倾、附加键。
+  await mouse.button.setSlot('scrollLeft', mutePreset);
+  await mouse.button.setSlot('scrollRight', mutePreset);
+  await mouse.button.setSlot('extra', mutePreset);
+}
+
+await mouse.button.resetSlot('back');
+await mouse.button.resetAll();
+```
+
+可通过以下导出项构建按键配置界面：
+
+- `KEY_PRESETS`：全部预设。
+- `KEYBOARD_PRESETS`：键盘按键预设。
+- `COMMAND_PRESETS`：系统和组合命令预设。
+- `COMMAND_PRESET_GROUPS`：已分组的命令预设。
+- `BUTTON_SLOTS`、`BUTTON_SLOT_LABEL`：鼠标按键槽位和显示名称；扩展槽位为 `scrollLeft`、`scrollRight`、`extra`。
+
+扩展槽位在协议中的索引分别为：`extra=6`、`scrollLeft=7`、`scrollRight=8`；索引 `5` 为设备内部 DPI 键，设置其他槽位时 SDK 会自动保留。
+
+## 宏
+
+`macroIndex` 范围是 `0..31`。键盘的 `keyCode` 使用 USB HID Keyboard Usage，例如字母 A 为 `0x04`。
+
+```ts
+import type { MouseMacro } from 'yjx-sdk-mouse';
+
+const macros: MouseMacro[] = [
+  {
+    actions: [
+      { type: 'keyboard', keyCode: 0x04, action: 'keydown', delay: 20 },
+      { type: 'keyboard', keyCode: 0x04, action: 'keyup', delay: 20 },
+      { type: 'mouse', button: 'left', action: 'mousedown', delay: 20 },
+      { type: 'mouse', button: 'left', action: 'mouseup', delay: 20 },
+    ],
+  },
+];
+
+// 写入 profile 0，并把第 0 个宏分配给后退键。
+await mouse.macro.setAndAssign(
+  'back',
+  macros,
+  {
+    macroIndex: 0,
+    repeat: 1,
+    triggerMode: 0,
+  },
+  0,
+);
+```
+
+也可以分开写入和分配：
+
+```ts
+await mouse.macro.set(macros, 0);
+await mouse.macro.assignButton('back', { macroIndex: 0 });
+```
+
+## 设备信息和事件
+
+```ts
+const info = await mouse.getDeviceInfo();
+console.log(info.boardId, info.firmwareVersion);
+
+const battery = await mouse.getBatteryStatus();
+console.log(`电量 ${battery.level}%`, battery.usbConnected ? 'USB 已连接' : '无线连接');
+
+const sleepStatus = await mouse.getSleepStatus();
+console.log('当前状态：', sleepStatus.sleeping ? '休眠' : '唤醒');
+
+mouse.on('sleepChange', (event) => {
+  console.log(event.state === 'sleep' ? '设备进入休眠' : '设备已唤醒');
+});
+
+mouse.on('statusChange', (event) => {
+  console.log('DPI 档位：', event.dpiIndex);
+  console.log('回报率：', event.pollRate);
+});
+
+mouse.on('usbChange', (event) => {
+  console.log('USB 状态：', event.type);
+});
+```
+
+取消监听：
+
+```ts
+const handleStatus = (event: { dpiIndex: number }) => {
+  console.log(event.dpiIndex);
+};
+
+mouse.on('statusChange', handleStatus);
+mouse.off('statusChange', handleStatus);
+```
+
+## 恢复出厂设置
+
+此操作会重置性能、DPI、按键和宏配置：
+
+```ts
+const result = await mouse.other.factoryReset();
+console.log(result);
+```
+
+## 原始协议调用
+
+只有在需要扩展设备协议时才建议使用：
+
+```ts
+const response = await mouse.sendRaw(new Uint8Array(64));
+await mouse.sendRawNoResponse(new Uint8Array(64));
+```
+
+## 主要 API
+
+| API | 说明 |
+| --- | --- |
+| `getDevices()` | 获取浏览器已经授权的兼容设备 |
+| `requestDevices()` | 打开浏览器设备选择器 |
+| `init(id)` | 打开设备并执行连接握手 |
+| `closeDevice()` | 关闭当前设备 |
+| `getDeviceInfo()` | 获取板卡和固件信息 |
+| `getFirmwareVersion(refresh?)` | 获取固件版本，可选择强制刷新 |
+| `getBatteryStatus()` / `getBattery()` | 通过 0x30 获取电量百分比和 USB 状态 |
+| `getSleepStatus()` | 通过 0xED 主动查询当前休眠/唤醒状态 |
+| `on('sleepChange', handler)` | 监听 0xED 休眠和唤醒主动上报 |
+| `dpi` | DPI 档位读取和写入 |
+| `performance` | 回报率、休眠、滚轮和唤醒设置 |
+| `light` | 灯效读取和写入（循环呼吸 / 常亮 / 灭灯 / 波浪 / 霓虹 / 巡回闪 / YOYO球 / 单向闪） |
+| `button` | 按键映射读取和写入 |
+| `macro` | 宏数据写入和按键分配 |
+| `other.factoryReset()` | 恢复出厂设置 |
+
+## 错误处理
+
+所有设备操作都返回 Promise，建议统一使用 `try/catch`：
+
+```ts
+try {
+  const devices = await mouse.requestDevices();
+  if (devices[0]) {
+    await mouse.init(devices[0].id);
+  }
+} catch (error) {
+  console.error('鼠标连接失败：', error);
+}
+```
+