本页目录

PIN（核心指南）

处理 OneKey 设备 PIN 码的基本规则。

关键要点

设备锁定机制：当设备锁定时，受保护的调用会触发 UI_REQUEST.REQUEST_PIN 事件。
Pro/Touch/Pro 2/Neo：PIN 码只能在硬件设备上输入（不支持软件输入）。
其他型号的软件盲输 PIN 能力取决于固件，读取 inputPinOnSoftware.support 后再提供入口；支持时优先让用户在设备上输入。

支持矩阵（软件 PIN 输入）

下表用于了解输入方式；实际入口应结合当前设备、固件能力及 UI 请求决定。设备端输入可用时优先使用，仅在当前设备支持且确有需要时提供宿主盲输。

设备	软件端 PIN 输入	仅设备端输入
OneKey Classic / 1s / 1s Pure / Mini	取决于固件；检查 `inputPinOnSoftware.support`	宿主输入流程可能提供设备输入选项
OneKey Touch	不支持	是
OneKey Pro	不支持	是
OneKey Pro 2 / Neo	不支持	是

UI 预期

仅显示当前设备、固件与 UI 请求支持的输入方式。两种方式均可用时，可在同一提示中提供：
- 在设备上输入（默认）
- 在此屏幕上盲输 — 使用固定的 3x3 键盘（1-9），掩码显示，不回显真实数字
收到 UI_REQUEST.CLOSE_UI_PIN_WINDOW / CLOSE_UI_WINDOW 或原操作结束时关闭提示，并使待提交回调失效。

PIN 位置映射（软件键盘）

收集完整的位置序列，校验后一次性回复；不要每点击一个键就提交一次 PIN。盲输键盘采用固定的 3×3 布局，不回显真实数字。


import { UI_RESPONSE } from "@onekeyfe/hd-core";
 
// Completed sequence of host keypad positions, numbered 1..9.
declare const selectedPositions: number[];
// Copy this from the current REQUEST_PIN event.
declare const responseCorrelation: { interactionId: string; deviceId: string } | undefined;
const BLIND_KEYBOARD_MAP = ['7','8','9','4','5','6','1','2','3'];
if (!selectedPositions.length || selectedPositions.some(position =>
  !Number.isInteger(position) || position < 1 || position > 9
)) throw new Error('Invalid PIN keypad sequence');
 
HardwareSDK.uiResponse({
  ...responseCorrelation,
  type: UI_RESPONSE.RECEIVE_PIN,
  payload: selectedPositions.map(position => BLIND_KEYBOARD_MAP[position - 1]).join(''),
});

事件到响应


import { UI_EVENT, UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hd-core';
 
HardwareSDK.on(UI_EVENT, (msg) => {
  if (msg.type === UI_REQUEST.REQUEST_PIN) {
    if (msg.payload.deviceOnly || msg.payload.type === 'ButtonRequest_PinEntry' || msg.payload.type === 'ButtonRequest_AttachPin') {
      // Show the device prompt and wait; this notification does not need a reply.
      return;
    }
    HardwareSDK.uiResponse({
      ...msg.payload.responseCorrelation,
      type: UI_RESPONSE.RECEIVE_PIN,
      payload: '@@ONEKEY_INPUT_PIN_IN_DEVICE',
    });
  }
});