electron-trackpad-utils

Включайте тактильный отклик трекпада и отслеживайте «начало/конец» прокрутки и «форс-клик» в Electron на macOS. Плюс — управляемые из кода варианты виброотклика.

⚠️ Поддерживается только macOS (встроенный трекпад MacBook или Magic Trackpad).

📦 Пакет на npm: electron-trackpad-utils-v2
🗂 Репозиторий: GitLab – electron-trackpad-utils-v2

Установка

npm install electron-trackpad-utils-v2
# если используете Electron — обязательно пересоберите нативный модуль под вашу версию
npx electron-rebuild   # или node-gyp rebuild c правильными флагами

API

onTrackpadScrollBegan(callback)

Вызывается, когда пользователь начал жест прокрутки на трекпаде.

• callback: () => void

onTrackpadScrollEnded(callback)

Вызывается, когда касания завершились во время прокрутки.
Важно: это не всегда совпадает с «визуальным окончанием инерционной прокрутки» в браузере.

• callback: () => void

onForceClick(callback)

Вызывается при форс-клике (глубокое нажатие с NSPressureBehaviorPrimaryDeepClick).

• callback: () => void

Можно отключить обработчик, передав null/ничего:

trackpadUtils.onForceClick(null); // перестать слушать

triggerFeedback()

Мгновенно проигрывает один импульс тактильного отклика (по умолчанию — системный паттерн).

• Без аргументов.

performHaptic(pattern)

Проигрывает один импульс заданного паттерна.

• pattern: 'generic' | 'alignment' | 'levelChange'

trackpadUtils.performHaptic('alignment');

performBurst(options)

Проигрывает серию импульсов («burst»), создавая ощущение «сильнее».

• options: {
  • pattern?: 'generic' | 'alignment' | 'levelChange' — по умолчанию 'generic'
  • count?: number — количество импульсов, по умолчанию 2
  • gapMs?: number — задержка перед первым импульсом (мс), по умолчанию 0
  • gapStepMs?: number — шаг между импульсами (мс), по умолчанию 15 }

// «усиленный» клик из 3 импульсов
trackpadUtils.performBurst({ pattern: 'generic', count: 3, gapMs: 0, gapStepMs: 15 });

Замечание: уровень/«сила» отклика трекпада не управляются программно публичным API macOS. Эффект «сильнее» достигается именно серии импульсов. На восприятие влияет системная настройка Trackpad → Click (Light/Medium/Firm) и «Silent clicking».

Быстрый пример (main process)

// main.js
const { app, BrowserWindow, ipcMain } = require('electron');
const path = require('path');
const trackpadUtils = require('electron-trackpad-utils');

function createWindow() {
  const win = new BrowserWindow({
    width: 800,
    height: 500,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false,
    },
  });

  win.loadFile('index.html');
}

// Системные колбэки трекпада → в рендерер (если нужно)
trackpadUtils.onTrackpadScrollBegan(() => {
  BrowserWindow.getAllWindows()[0]?.webContents.send('fromMain', { command: 'onTrackpadScrollBegan' });
});
trackpadUtils.onTrackpadScrollEnded(() => {
  BrowserWindow.getAllWindows()[0]?.webContents.send('fromMain', { command: 'onTrackpadScrollEnded' });
});
trackpadUtils.onForceClick(() => {
  BrowserWindow.getAllWindows()[0]?.webContents.send('fromMain', { command: 'onForceClick' });
});

// Команды из UI → нативный модуль
ipcMain.on('toMain', (_event, command, data) => {
  switch (command) {
    case 'triggerFeedback':
      trackpadUtils.triggerFeedback();
      break;
    case 'performHaptic':
      trackpadUtils.performHaptic(data?.pattern || 'generic');
      break;
    case 'performBurst':
      trackpadUtils.performBurst(data || {});
      break;
    default:
      console.warn('Unknown command:', command);
  }
});

app.whenReady().then(createWindow);
app.on('window-all-closed', () => app.quit());

preload.js

const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('api', {
  send: (command, data) => ipcRenderer.send('toMain', command, data),
  onMain: (fn) => ipcRenderer.on('fromMain', (_e, ...args) => fn(...args)),
});

renderer (пример вызовов)

<button onclick="window.api.send('performHaptic', { pattern: 'generic' })">Generic</button>
<button onclick="window.api.send('performHaptic', { pattern: 'alignment' })">Alignment</button>
<button onclick="window.api.send('performHaptic', { pattern: 'levelChange' })">LevelChange</button>
<button onclick="window.api.send('performBurst', { pattern: 'generic', count: 2, gapStepMs: 15 })">Burst</button>

<script>
  window.api.onMain((msg) => console.log('fromMain:', msg));
</script>

Пример «линейки» с хаптиком на отсечках

(… текст и код, см. выше …)

Как запустить демо

После клонирования:

npm install
npm rebuild
cd demo
npm install
npm start

Подсказки и ограничения

• Убедитесь, что в System Settings → Trackpad включено Force Click and haptic feedback.
  В режиме «Silent clicking» субъективно отклик слабее.
• Вызывайте тактильный отклик с главного потока (аддон делает это за вас).
• «Силу»/амплитуду отклика macOS менять нельзя; используйте performBurst(...) для «усиленного» ощущения.
• Если используете IPC — слушайте события через ipcMain (не webContents.ipc).

Лицензия

MIT License