轴体版本识别（无限轴体） 简要描述: 通过轴体列表判断设备轴体体系版本：当 getAxisList().list.length === 0 时，代表为“无限轴体（v2）”。
使用示例 typescriptasync function getAxisVersion(): Promise
const result = await ServiceKeyboard.getAxisList();
const { list } = result;
const isAxisStatus = list.length === 0 ? 'v2' : 'v1';
return isAxisStatus === 'v1' ? list : [];
}注意事项 TIP
list.length === 0 表示为“无限轴体（v2）”。在 v2 模式下，请在 getPerformance 中读取并在 setPerformance 中设置以下三项： axisV2IdaxisRangeMaxaxisCoefficient获取轴体列表 V3 httpService.getAxisListV3()
简要描述: 通过网络 GET 请求获取轴体列表数据，包含轴体品牌、型号、参数等详细信息。
请求类型: GET
实际接口 URL:https://api.sparklinkplayjoy.com/api/v1/getAxisListV3
请求示例:https://api.sparklinkplayjoy.com/api/v1/getAxisListV3?board_id=00300001&vid=1ca6&pid=3001&t=1764816395732
参数 参数名称类型描述是否必需默认值paramsobject一个包含设备信息和时间戳的对象。是无params.board_idstring设备板 ID，需转换为 16 进制并补零至 8 位字符串。是无params.vidstring设备厂商 ID (Vendor ID)，需转换为 16 进制并补零至 4 位字符串。是无params.pidstring设备产品 ID (Product ID)，需转换为 16 进制并补零至 4 位字符串。是无params.tnumber当前时间戳（毫秒），用于防止缓存。是无返回值 总体类型: Promise
js[
{
"type_id": 166,
"type_name": "佳达隆",
"type_name_en": "GATERON",
"type_sort": 0,
"list": []
},
{
"type_id": 167,
"type_name": "正牌科电",
"type_name_en": "TTC",
"type_sort": 0,
"list": []
},
{
"type_id": 168,
"type_name": "其它",
"type_name_en": "other",
"type_sort": 0,
"list": [
{
"axis_id": 794,
"axis_name": "天青轴Pro",
"axis_range_max": 3610,
"magnetic_flux": 500,
"axis_color": "#74e1fd",
"image_url": "#",
"brand": "other",
"type_id": 168,
"type_name": "其它",
"type_name_en": "other",
"type_sort": 0,
"aixsDetail": [
{
"axis_id": 12704,
"axis_range_max": 3610,
"axis_coefficient": 18100
}
]
}
]
}
]使用示例 typescriptasync function getAxisListV3Data() {
try {
// 从设备存储中获取必要信息
const boardId = deviceStore.info?.boardId.toString(16).padStart(8, '0');
const vid = deviceStore.device?.vendorId.toString(16).padStart(4, '0');
const pid = deviceStore.device?.productId.toString(16).padStart(4, '0');
// 构建参数
const params = {
board_id: boardId,
vid,
pid,
t: Date.now()
};
// 调用接口获取轴体列表
const result = await httpService.getAxisListV3(params);
console.log('轴体列表 V3 数据:', result);
// 处理轴体数据
result.forEach(brand => {
console.log(`品牌: ${brand.type_name} (${brand.type_name_en})`);
brand.list.forEach(axis => {
console.log(` 轴体: ${axis.axis_name}`);
console.log(` 最大行程: ${axis.axis_range_max}`);
console.log(` 颜色: ${axis.axis_color}`);
axis.aixsDetail.forEach(param => {
console.log(` 参数 ID: ${param.axis_id}`);
console.log(` 系数: ${param.axis_coefficient}`);
});
});
});
return result;
} catch (error) {
console.error('获取轴体列表 V3 失败:', error);
return [];
}
}
// 获取轴体列表 V3 数据
getAxisListV3Data();注意事项 TIP
此接口为网络 GET 请求，需确保设备网络连接正常。参数中的 board_id、vid、pid 需要转换为 16 进制格式并补零至指定长度。返回的轴体数据可用于设置按键的轴体类型和参数。不同的轴体 ID 和参数代表不同的轴体型号和特性。键盘性能设置 获取按键性能配置 ServiceKeyboard.getPerformance()
简要描述: 获取指定按键的所有性能相关配置信息，包括模式、行程值、死区等参数。
参数 参数名称类型描述是否必需默认值paramsobject一个包含按键位置信息的对象。是无params.rownumber按键在键盘矩阵中的行号。是无params.colnumber按键在键盘矩阵中的列号。是无返回值 总体类型: Promise
js// v1（有限轴体）：含 axis（索引），不含 v2 字段
{
"mode": 0,
"normalPress": 2,
"normalRelease": 2,
"rtFirstTouch": 0.5,
"rtPress": 0.3,
"rtRelease": 0.3,
"pressDeadStroke": 0.2,
"releaseDeadStroke": 0.2,
"axis": 0,
"calibrate": 0
}
// v2（无限轴体）：不含 axis（索引），增加 v2 三项
{
"mode": 0,
"normalPress": 2,
"normalRelease": 2,
"rtFirstTouch": 0.5,
"rtPress": 0.3,
"rtRelease": 0.3,
"pressDeadStroke": 0.2,
"releaseDeadStroke": 0.2,
"axisV2Id": 1001,
"axisRangeMax": 4,
"axisCoefficient": 1,
"calibrate": 0
}使用示例 typescriptasync function getKeyPerformance(row: number, col: number) {
try {
const result = await ServiceKeyboard.getPerformance({ row, col });
console.log('按键性能配置:', result);
} catch (error) {
console.error('获取按键性能配置失败:', error);
}
}
// 示例：获取第5行第14列的按键性能配置
getKeyPerformance(5, 14);注意事项 TIP
v1：通过 axis（索引）指向 getAxisList().list 中的某个轴体。v2（无限轴体）：不再使用 axis 索引，改为使用 axisV2Id、axisRangeMax、axisCoefficient 三项描述轴体。设置按键性能配置 ServiceKeyboard.setPerformance()
简要描述: 设置指定按键的所有性能相关配置信息，包括触发方式、行程值、死区等参数。
参数 参数名称类型描述是否必需默认值paramsobject一个包含按键性能配置信息的对象。是无params.rownumber按键在键盘矩阵中的行号是无params.colnumber按键在键盘矩阵中的列号是无params.modenumber触发方式是无params.normalPressnumber普通触发按下行程是无params.normalReleasenumber普通触发释放行程是无params.rtFirstTouchnumberRT触发首次触发行程是无params.rtPressnumberRT首次触发按下行程是无params.rtReleasenumberRT首次触发释放行程是无params.pressDeadStrokenumber按下死区是无params.releaseDeadStrokenumber抬起死区是无params.axisnumber轴体索引（v1 时必填；v2 不使用）否无params.axisV2Idnumber轴体ID（v2 时必填；v1 不使用）否无params.axisRangeMaxnumber轴体最大行程范围（v2 时必填）否无params.axisCoefficientnumber轴体系数（v2 时必填）否无params.axisnumber获取的轴体列表索引是无params.calibratenumber校准标志是无参数示例:
js// v1（有限轴体）示例
{
"row": 4,
"col": 5,
"mode": 0,
"normalPress": 1.506,
"normalRelease": 1.506,
"rtFirstTouch": 0.5,
"rtPress": 0.3,
"rtRelease": 0.3,
"pressDeadStroke": 0.2,
"releaseDeadStroke": 0.2,
"axis": 0,
"calibrate": 0
}
// v2（无限轴体）示例
{
"row": 4,
"col": 5,
"mode": 0,
"normalPress": 1.506,
"normalRelease": 1.506,
"rtFirstTouch": 0.5,
"rtPress": 0.3,
"rtRelease": 0.3,
"pressDeadStroke": 0.2,
"releaseDeadStroke": 0.2,
"axisV2Id": 1001,
"axisRangeMax": 4,
"axisCoefficient": 1,
"calibrate": 0
}返回值 总体类型: Promise
js{
row: number;
col: number;
mode: number; // 触发方式
normalPress: number; // 普通触发按下行程
normalRelease: number; // 普通触发释放行程
rtFirstTouch: number; // RT触发首次触发行程
rtPress: number; // RT首次触发按下行程
rtRelease: number; // RT首次触发释放行程
pressDeadStroke: number; // 按下死区
releaseDeadStroke: number; // 抬起死区
axis?: number; // v1 有效
axisV2Id?: number; // v2 有效
axisRangeMax?: number; // v2 有效
axisCoefficient?: number; // v2 有效
calibrate: number; // 校准标志
}使用示例 typescriptasync function setKeyPerformance() {
try {
// v1 或 v2 请根据 getAxisList().list.length 判断，并填入对应字段
const params = {
row: 4,
col: 5,
mode: 0,
normalPress: 1.506,
normalRelease: 1.506,
rtFirstTouch: 0.5,
rtPress: 0.3,
rtRelease: 0.3,
pressDeadStroke: 0.2,
releaseDeadStroke: 0.2,
// v1: axis: 0,
// v2: axisV2Id: 1001, axisRangeMax: 4, axisCoefficient: 1,
calibrate: 0,
} as any;
const result = await ServiceKeyboard.setPerformance(params);
console.log('设置按键性能配置结果:', result);
} catch (error) {
console.error('设置按键性能配置失败:', error);
}
}
setKeyPerformance();注意事项 TIP
如果 ServiceKeyboard.getAxisList().list.length === 0，表示为 v2（无限轴体），setPerformance 需设置 axisV2Id、axisRangeMax、axisCoefficient。如果为 v1，请设置 axis（索引）并忽略 v2 三项。设置完成后，建议使用 getPerformance 校验配置是否生效。获取ADC采样数据 ServiceKeyboard.getADCSample()
简要描述: 获取指定行的ADC采样数据，用于分析按键的物理状态。
参数 参数名称类型描述是否必需默认值paramsobject一个包含行号信息的对象。是无params.rownumber要获取ADC采样数据的行号。是无返回值 总体类型: Promise
js{
"adc": 0,
"row": 3,
"data": [
2715,
2700,
2686,
2693,
2704,
2772,
2674,
2688,
2688,
2684,
2692,
2680,
0,
2684,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
}使用示例 typescriptasync function getADCSampleData(row: number) {
try {
const result = await ServiceKeyboard.getADCSample({
row: row
});
console.log('ADC采样数据:', result);
console.log('行号:', result.row);
console.log('采样数据:', result.data);
} catch (error) {
console.error('获取ADC采样数据失败:', error);
}
}
// 示例：获取第3行的ADC采样数据
getADCSampleData(3);注意事项 TIP
row 的值需要根据键盘的实际矩阵布局来确定。data 数组中的值表示每个按键的ADC采样值，0表示该位置没有按键或无效数据。ADC采样值可用于分析按键的物理状态和触发情况。获取路由数据 ServiceKeyboard.getRoute()
简要描述: 获取指定行的按键按下的行程距离数据，用于分析按键的触发状态。
参数 参数名称类型描述是否必需默认值paramsobject一个包含行号信息的对象。是无params.rownumber要获取路由数据的行号。是无返回值 总体类型: Promise
js{
"route": 1,
"row": 3,
"data": [
0,
0,
0,
0,
0,
343,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
}使用示例 typescriptasync function getRouteData(row: number) {
try {
const result = await ServiceKeyboard.getRoute({
row: row
});
console.log('路由数据:', result);
console.log('行号:', result.row);
console.log('路由值:', result.route);
console.log('数据:', result.data);
} catch (error) {
console.error('获取路由数据失败:', error);
}
}
// 示例：获取第3行的路由数据
getRouteData(3);注意事项 TIP
row 的值需要根据键盘的实际矩阵布局来确定。data 数组中的值表示每个按键的路由值，0表示该位置没有按键或无效数据。路由值可用于分析按键的触发状态和信号传输情况。开始校准 ServiceKeyboard.calibrationStart
简要描述: 开始设备的校准流程。
参数 此方法不需要参数。
返回值 总体类型: Promise
try {
// 确保设备已初始化
// await ServiceKeyboard.init(deviceId);
const calibrationStatus = await ServiceKeyboard.calibrationStart();
console.log('校准已开始:', calibrationStatus);
// 根据 calibrationStatus 进行后续操作或UI更新
} catch (error) {
console.error('开始校准失败:', error);
}
}
// beginCalibration();结束校准 ServiceKeyboard.calibrationEnd
简要描述: 结束设备的校准流程。
参数 此方法不需要参数。
返回值 总体类型: Promise
try {
// 确保设备已初始化且校准已开始
// await ServiceKeyboard.init(deviceId);
// await ServiceKeyboard.calibrationStart();
const calibrationResult = await ServiceKeyboard.calibrationEnd();
console.log('校准已结束:', calibrationResult);
// 根据 calibrationResult 进行后续操作或UI更新
} catch (error) {
console.error('结束校准失败:', error);
}
}
// finishCalibration();获取校准状态 ServiceKeyboard.getCalibrationStatus()
简要描述: 获取指定行的按键校准状态信息。
参数 参数名称类型描述是否必需默认值paramsobject一个包含行号信息的对象。是无params.rownumber要获取校准状态的行号。是无返回值 总体类型: Promise
js{
"calibrate": 2,
"row": 3,
"data": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
}使用示例 typescriptasync function getCalibrationStatusData(row: number) {
try {
const result = await ServiceKeyboard.getCalibrationStatus({
row: row
});
console.log('校准状态:', result);
console.log('行号:', result.row);
console.log('校准状态值:', result.calibrate);
console.log('状态数据:', result.data);
} catch (error) {
console.error('获取校准状态失败:', error);
}
}
// 示例：获取第3行的校准状态
getCalibrationStatusData(3);注意事项 TIP
row 的值需要根据键盘的实际矩阵布局来确定。data 数组中的值表示每个按键的校准状态，0表示该位置没有按键或未校准。校准状态值可用于判断按键是否需要校准或校准是否完成。获取轴体列表 ServiceKeyboard.getAxisList()
简要描述: 获取键盘支持的所有轴体类型列表。
参数 此方法不需要参数。
返回值 总体类型: Promise
js{
"total": 4,
"list": [
54,
24,
1,
69
]
}使用示例 typescriptasync function getAxisListData() {
try {
const result = await ServiceKeyboard.getAxisList();
console.log('轴体列表:', result);
console.log('轴体总数:', result.total);
console.log('轴体类型列表:', result.list);
} catch (error) {
console.error('获取轴体列表失败:', error);
}
}
// 获取轴体列表
getAxisListData();注意事项 TIP
返回的轴体类型ID可用于设置按键的轴体类型。不同的轴体类型ID代表不同的轴体型号或特性。在使用 setPerformance 接口设置轴体时，应使用此列表中的有效ID。全局功能轴体库查询 简要描述: 键盘支持轴体库
注意事项 TIP
轴体库的具体接口请联系我们获取。导入轴体库前，请确保数据格式正确。获取防自显开关状态 ServiceKeyboard.getShakeOptimizationSwitch()
简要描述: 获取设备的防自显开关状态，用于控制键盘的震动优化功能。
参数 此方法不需要参数。
返回值 总体类型: Promise
js{
"enabled": false,
"status": 0
}使用示例 typescriptasync function getShakeOptimizationStatus() {
try {
const result = await ServiceKeyboard.getShakeOptimizationSwitch();
const { enabled, status } = result;
console.log('防自显开关状态:', enabled ? '开启' : '关闭');
console.log('操作状态码:', status);
return enabled;
} catch (error) {
console.error('获取防自显开关状态失败:', error);
return false;
}
}
// 获取防自显开关状态
getShakeOptimizationStatus();注意事项 TIP
防自显功能用于优化键盘的震动响应，防止误触发。开关状态将影响键盘的整体震动性能。设置防自显开关状态 ServiceKeyboard.setShakeOptimizationSwitch()
简要描述: 设置设备的防自显开关状态，用于控制键盘的震动优化功能。
参数 参数名称类型描述是否必需默认值enablednumber防自显开关状态值，1表示开启，0表示关闭。是无参数说明:
1: 开启防自显功能0: 关闭防自显功能返回值 总体类型: Promise
try {
await ServiceKeyboard.setShakeOptimizationSwitch(enabled ? 1 : 0);
console.log('防自显开关状态已设置为:', enabled ? '开启' : '关闭');
} catch (error) {
console.error('设置防自显开关状态失败:', error);
}
}
// 示例：开启防自显功能
setShakeOptimizationStatus(true);
// 示例：关闭防自显功能
setShakeOptimizationStatus(false);注意事项 TIP
防自显功能用于优化键盘的震动响应，防止误触发。设置后立即生效，无需额外操作。建议根据实际使用场景调整此设置以获得最佳体验。