BetterTouchTool

BetterTouchTool 是一款 macOS 自动化应用，可用于自定义手势、快捷键、Touch Bar 控件、Stream Deck 按钮、菜单栏项目以及其他系统级工作流。

使用方式

有两种使用此库的方式：

按需导入（On-Demand）：从子路径导入支持 tree-shaking，保持较小的打包体积。
完整导入（Full Import）：从根包导入更方便，但会包含所有应用模块。

生产构建建议选择按需导入；快速脚本或演示可以使用完整导入。

选择安装方式

按需加载

推荐使用。生产环境优化。

全量导入

使用便捷。适合快速脚本。

触发命名触发器

运行命名触发器，向它传入 BetterTouchTool 变量，或取消它的延迟执行。

On-Demand

import { triggerNamed } from 'protocol-launcher/bettertouchtool'

const reviewUrl = triggerNamed({
  triggerName: 'Daily Review',
})

const projectUrl = triggerNamed({
  triggerName: 'Open Project',
  variables: {
    projectName: 'Protocol Launcher',
  },
})

const cancelUrl = triggerNamed({
  triggerName: 'Daily Review',
  cancelDelayed: 1,
})

运行 Daily Review 带变量打开项目取消延迟的 Daily Review

异步触发命名触发器

异步运行命名触发器，不等待响应。

On-Demand

import { triggerNamedAsyncWithoutResponse } from 'protocol-launcher/bettertouchtool'

const url = triggerNamedAsyncWithoutResponse({
  triggerName: 'Refresh Dashboard',
})

异步刷新 Dashboard

取消延迟触发器执行

取消一个命名触发器的待执行延迟触发。

On-Demand

import { cancelDelayedNamedTriggerExecution } from 'protocol-launcher/bettertouchtool'

const url = cancelDelayedNamedTriggerExecution({
  triggerName: 'Daily Review',
})

取消待执行的 Daily Review

执行触发器已分配动作

执行指定 UUID 触发器的全部已分配动作。

On-Demand

import { executeAssignedActionsForTrigger } from 'protocol-launcher/bettertouchtool'

const url = executeAssignedActionsForTrigger({
  uuid: '0E2F7963-E64C-403A-8591-C3725D4D9ADC',
})

执行触发器动作

触发预定义动作

通过动作 JSON 运行 BetterTouchTool 预定义动作。

On-Demand

import { triggerAction } from 'protocol-launcher/bettertouchtool'

const url = triggerAction({
  json: {
    BTTPredefinedActionType: 153,
    BTTPredefinedActionName: 'Move Mouse To Position',
    BTTMoveMouseToPosition: '{100, 10}',
    BTTMoveMouseRelative: '6',
  },
})

移动鼠标到指定位置

刷新脚本小组件

执行脚本 widget 上分配的全部脚本并更新其内容。

On-Demand

import { refreshWidget } from 'protocol-launcher/bettertouchtool'

const url = refreshWidget({
  uuid: 'CC46E199-B07D-4BF7-AC36-48AAE558540B',
})

刷新状态 Widget

更新触控栏脚本小组件

更新 Touch Bar Script Widget 的内容。

On-Demand

import { updateTouchBarWidget } from 'protocol-launcher/bettertouchtool'

const url = updateTouchBarWidget({
  uuid: 'CC46E199-B07D-4BF7-AC36-48AAE558540B',
  text: 'Build passed',
  iconPath: '/Users/andi/Desktop/status.png',
  backgroundColor: '200,200,100,255',
})

在 Touch Bar 显示构建状态

更新控制台小组件

更新 Stream Deck widget 的内容。

On-Demand

import { updateStreamDeckWidget } from 'protocol-launcher/bettertouchtool'

const url = updateStreamDeckWidget({
  uuid: 'CC46E199-B07D-4BF7-AC36-48AAE558540B',
  text: 'Deploy',
})

更新 Stream Deck 部署按钮

更新菜单栏项目

更新菜单栏项目的内容。

On-Demand

import { updateMenubarItem } from 'protocol-launcher/bettertouchtool'

const url = updateMenubarItem({
  uuid: 'CC46E199-B07D-4BF7-AC36-48AAE558540B',
  text: 'Ready',
})

更新菜单栏状态

更新触发器

更新指定触发器的配置。

On-Demand

import { updateTrigger } from 'protocol-launcher/bettertouchtool'

const url = updateTrigger({
  uuid: '0E2F7963-E64C-403A-8591-C3725D4D9ADC',
  json: {
    BTTTouchBarButtonName: 'New Name2',
    BTTTriggerConfig: {
      BTTTouchBarItemIconHeight: 30,
    },
  },
})

重命名 Touch Bar 触发器

添加新触发器

通过触发器 JSON 向 BetterTouchTool 添加新触发器。

On-Demand

import { addNewTrigger } from 'protocol-launcher/bettertouchtool'

const url = addNewTrigger({
  json: {
    BTTTriggerClass: 'BTTTriggerTypeKeyboardShortcut',
    BTTPredefinedActionType: 5,
    BTTPredefinedActionName: 'Mission Control',
    BTTAdditionalConfiguration: '1179658',
    BTTTriggerOnDown: 1,
    BTTEnabled: 1,
    BTTShortcutKeyCode: 2,
    BTTShortcutModifierKeys: 1179648,
    BTTOrder: 3,
  },
})

添加 Mission Control 快捷键

删除触发器

通过 UUID 删除 BetterTouchTool 触发器。

On-Demand

import { deleteTrigger } from 'protocol-launcher/bettertouchtool'

const url = deleteTrigger({
  uuid: '0E2F7963-E64C-403A-8591-C3725D4D9ADC',
})

删除触发器

在界面中定位元素

打开 BetterTouchTool 配置界面并通过 UUID 定位到元素。

On-Demand

import { revealElementInUi } from 'protocol-launcher/bettertouchtool'

const url = revealElementInUi({
  uuid: '0E2F7963-E64C-403A-8591-C3725D4D9ADC',
})

在 BetterTouchTool 中显示触发器

导出预设

将 BetterTouchTool preset 导出到文件。

On-Demand

import { exportPreset } from 'protocol-launcher/bettertouchtool'

const url = exportPreset({
  name: 'Focus Mode',
  outputPath: '/Users/andi/Desktop/FocusMode.bttpreset',
  compress: 1,
})

导出 Focus Mode Preset

导入预设

从文件路径导入 BetterTouchTool preset。

On-Demand

import { importPreset } from 'protocol-launcher/bettertouchtool'

const url = importPreset({
  path: '/Users/andi/Desktop/FocusMode.bttpreset',
})

const keepExistingUrl = importPreset({
  path: '/Users/andi/Desktop/FocusMode.bttpreset',
  replaceExisting: 0,
})

导入 Focus Mode Preset 导入但保留已有 Preset

运行快捷指令

按名称运行 Apple Shortcuts 快捷指令并等待结果。

On-Demand

import { runShortcut } from 'protocol-launcher/bettertouchtool'

const url = runShortcut({
  shortcutName: 'Start Focus',
  input: 'Protocol Launcher',
})

运行 Start Focus 快捷指令

异步运行快捷指令

异步运行 Apple Shortcuts 快捷指令，不等待响应。

On-Demand

import { runShortcutAsyncWithoutResponse } from 'protocol-launcher/bettertouchtool'

const url = runShortcutAsyncWithoutResponse({
  shortcutName: 'Log Break',
  input: '5 minutes',
})

异步记录休息时间

设置持久字符串变量

设置一个会在 BetterTouchTool 重新启动后保留的字符串变量。

On-Demand

import { setPersistentStringVariable } from 'protocol-launcher/bettertouchtool'

const url = setPersistentStringVariable({
  variableName: 'currentProject',
  to: 'Protocol Launcher',
})

保存当前项目

设置字符串变量

设置一个仅在 BetterTouchTool 运行期间存在的字符串变量。

On-Demand

import { setStringVariable } from 'protocol-launcher/bettertouchtool'

const url = setStringVariable({
  variableName: 'sessionState',
  to: 'reviewing',
})

设置会话状态

设置持久数字变量

设置一个会在 BetterTouchTool 重新启动后保留的数字变量。

On-Demand

import { setPersistentNumberVariable } from 'protocol-launcher/bettertouchtool'

const url = setPersistentNumberVariable({
  variableName: 'focusGoalMinutes',
  to: 45,
})

保存专注目标

设置数字变量

设置一个仅在 BetterTouchTool 运行期间存在的数字变量。

On-Demand

import { setNumberVariable } from 'protocol-launcher/bettertouchtool'

const url = setNumberVariable({
  variableName: 'currentPomodoro',
  to: 2,
})

设置当前番茄钟数量

通过链接导入预设

通过下载 URL 导入 BetterTouchTool preset，并可使用官方文档中的 unzip 路径。

On-Demand

import { importViaUrl } from 'protocol-launcher/bettertouchtool'

const url = importViaUrl({
  url: 'https://example.com/btt-presets/focus-mode.bttpreset',
})

const unzipUrl = importViaUrl({
  url: 'https://example.com/btt-presets/focus-mode.zip',
  unzip: true,
})

通过 URL 导入 Focus Mode 通过 URL 导入压缩的 Focus Mode

通过编码触发器数据导入

通过 URL 中的 base64 编码 JSON 字符串导入触发器。

On-Demand

import { jsonImport } from 'protocol-launcher/bettertouchtool'

const url = jsonImport({
  encodedJson: 'BASE64_ENCODED_TRIGGER_JSON',
})

const uncompressUrl = jsonImport({
  encodedJson: 'BASE64_ENCODED_COMPRESSED_TRIGGER_JSON',
  uncompress: true,
})

导入编码后的触发器 JSON 导入压缩后的触发器 JSON

官方文档

BetterTouchTool Custom URL Scheme

BetterTouchTool ​

使用方式 ​

选择安装方式

触发命名触发器 ​

异步触发命名触发器 ​

取消延迟触发器执行 ​

执行触发器已分配动作 ​

触发预定义动作 ​

刷新脚本小组件 ​

更新触控栏脚本小组件 ​

更新控制台小组件 ​

更新菜单栏项目 ​

更新触发器 ​

添加新触发器 ​

删除触发器 ​

在界面中定位元素 ​

导出预设 ​

导入预设 ​

运行快捷指令 ​

异步运行快捷指令 ​

设置持久字符串变量 ​

设置字符串变量 ​

设置持久数字变量 ​

设置数字变量 ​

通过链接导入预设 ​

通过编码触发器数据导入 ​

官方文档 ​

BetterTouchTool

使用方式

触发命名触发器

异步触发命名触发器

取消延迟触发器执行

执行触发器已分配动作

触发预定义动作

刷新脚本小组件

更新触控栏脚本小组件

更新控制台小组件

更新菜单栏项目

更新触发器

添加新触发器

删除触发器

在界面中定位元素

导出预设

导入预设

运行快捷指令

异步运行快捷指令

设置持久字符串变量

设置字符串变量

设置持久数字变量

设置数字变量

通过链接导入预设

通过编码触发器数据导入

官方文档