00:00:00TanStack 再次发布了一个新包，继续致力于修复 JavaScript 世界
00:00:03而这一次他们要修复的是热键（hotkeys）。如果你觉得这听起来
00:00:07很简单，甚至觉得 AI 现在就能帮你写出来，那你就想错了。TanStack Hotkeys
00:00:11能处理 AI 经常忽略的边缘情况，比如多种键盘布局、多种操作系统、
00:00:16热键冲突、作用域冲突等等，甚至还具备
00:00:20热键序列和热键录制等功能，同时保持类型安全且框架无关。
00:00:26相信我，如果你需要热键功能，直接用这个包，或者让你的 AI 代理去用。我的意思是
00:00:30既然是 TanStack 出品，开发者体验肯定没得说，那么话不多说，让我们直接
00:00:35看看它的实际表现吧。
00:00:41现在我直接进入代码部分，因为这一切都非常简单，我正在
00:00:45一个 React 应用中进行演示，所以我使用的是 TanStack React Hotkeys 包
00:00:49但他们目前也有原生 JavaScript 版本，并且
00:00:52很快会支持更多框架，但目前还处于 Alpha 阶段，所以可能
00:00:56偶尔会有一些 Bug，但对我的使用场景来说，它已经解决了所有问题。我们先从
00:01:01最基础的用例开始，也就是 useHotkey hook。你可以看到这里我们已经
00:01:05从包里导入了它，我们要做的就是定义热键是什么，以及
00:01:09当我们按下该热键时要运行的函数。在我的例子中，我设置的是
00:01:13按下热键时打开命令面板，这是一个非常常见的例子。
00:01:17你也可以看到下面有一个 Toast 提示，这样你就能看到我按了什么
00:01:20以及它具体执行了什么操作。如你所见，这个 hook 非常简单，它
00:01:24完全符合预期，但 TanStack 的魔力通常体现在开发者
00:01:28体验和类型安全上，这里也不例外。首先
00:01:32从我们的热键定义开始，在这个包中任何使用热键的地方都是类型安全的，
00:01:37这简直太疯狂了。它知道所有可能的按键以及它们的组合，
00:01:41所以我可以把它改为类似 “meta + s”，在 macOS 上这实际上是 “command + s”
00:01:46也许我正在为应用设置一个新的保存热键，你看它知道这是一个
00:01:50有效的组合，如果我打错了，它会抛出类型错误来提醒我们
00:01:54这个热键是无效的。关于热键定义的另一个酷炫之处是，目前
00:01:58我把它设为 “meta + k”，在 macOS 上就是 “command + k”，
00:02:02这在我的 macOS 上运行良好，但这套定义在
00:02:06Windows 或其他平台上将无法工作，因为那里没有 meta 键。所以
00:02:11我们可以做的是将这里的 “meta” 键替换为 “modifier” 键，
00:02:15这意味着在 macOS 上它会自动设置为 command 键，但在所有
00:02:19其他平台上，它会自动对应 control 键，这样你就立刻拥有了一个跨平台热键。
00:02:24最后，关于在这个包中定义热键的方式，
00:02:27如果你不喜欢字符串定义，你也可以使用对象定义，
00:02:31这和我们刚才的键位绑定完全一样，即 command k 或 control k。你看我们只需
00:02:35指明非修饰键是什么，然后根据需要将 modifier 设为 true，
00:02:38或者设置其他的修饰键。说完了热键的定义方式，
00:02:42接下来是 hook 的参数，即当我们按下热键时执行的
00:02:46实际函数，这显然非常简单，
00:02:50函数体里可以写任何你想执行的内容，但你也可以访问原始的键盘
00:02:54事件（event），如果需要的话，还可以获取上下文（context）。在这种情况下，上下文
00:02:58会直接以字符串形式返回按下的热键，或者你可以获取
00:03:02以对象定义的已传热键，就像我们刚才看到的那样。最后关于
00:03:05useHotkey hook，我想展示的功能还有很多，它的第三个
00:03:09参数是一些控制热键工作方式的选项。这些大部分都
00:03:13不言自明，我已经将它们设为了默认值。比如用于程序化控制
00:03:17热键开关的 “enabled”；用于设置在按键按下（down）或弹起（up）时
00:03:21触发的 “event type”。”require reset” 的意思是，目前
00:03:25如果它被设为 false，当我按住 command k 时，你可以看到它在不断地
00:03:29重复触发热键。然而，如果我将其设为 true，就意味着我们必须先
00:03:33松开热键，它才能再次触发。你看我现在一直按着，
00:03:37这次它只触发了一次。接着是 “ignore inputs”，这意味着如果我在
00:03:41输入框内按下 command k，你可以看到目前它是被完全忽略的，
00:03:45不会触发热键。当然，如果我们确实希望在输入框内热键
00:03:49依然有效，可以将其设为 false。最后我想介绍的一个
00:03:53选项是 “target”，它允许你创建具有作用域的热键。这具体意味着
00:03:57默认情况下它被设置为整个 document，也就是说我
00:04:00可以在页面的任何地方按 command k 来触发那个命令面板。
00:04:04但是，我可以把它改为某个特定元素或 React 的 ref。如果我把它
00:04:09改为 badgeRef，你可以看到当我在页面其他地方点击并按 command k 时，
00:04:13它不再触发。但如果我聚焦到下面的这个 command k 元素（即那个 badge），
00:04:17你可以看到它就可以触发了，所以我们现在有了一个局部作用域的热键。希望你
00:04:21已经明白为什么我非常喜欢这个包了，它总是有如此出色的细节关注、
00:04:25极佳的开发体验和完善的类型安全。而且我目前还只展示了
00:04:30一个 hook，让我们再看看其他的。接下来是 useHotkeySequences hook，
00:04:34它允许我们设置多键序列，比如我们可以实现类似 Vim 风格的导航。
00:04:38这个 hook 也很直观，和 useHotkey 类似，我们只需要
00:04:43定义按键序列是什么，然后定义序列输入完成后
00:04:47要运行的函数。这里我们也可以设置一些选项，注意 “timeout”
00:04:51本质上是每次按键之间的时间间隔，在此时间内按键仍会被注册为
00:04:54序列的一部分。目前我把其中一个设为 “gg”，功能是跳转到列表
00:04:59顶部。如果我现在到这里按下 “gg”，你可以看到它确实做到了。我还在下面
00:05:04设置了一个，如果我按下 “sub”，它会跳转到底部，顺便说一下，
00:05:09这拼出来是 “subscribe”（订阅），这也是你们绝对应该做的事情。接下来是一些更简单的
00:05:12hook，第一个是 useKeyHold。你只需要指定
00:05:16你想追踪哪个按键，它会返回一个布尔值，表示该键当前是否被
00:05:20按住。你可以看到我在这里监控了几个键，如果我按住 shift 和
00:05:24alt，你可以看到页面上的状态根据那个布尔值发生了变化。你还会
00:05:28注意到下面列出了我键盘上当前按住的所有键，这是通过
00:05:32第二个 hook 实现的，即 useHeldKeys，它会简单地返回一个
00:05:36当前被按住的键的数组。同样，当我按住 “sub” 时，你可以看到它们出现在
00:05:40数组中。在进入那些很酷的
00:05:43工具函数之前，我想展示的最后一个 hook 是 useHotkeyRecorder。这实际上可以让你
00:05:47创建键盘快捷键自定义 UI，它是一个非常好用的辅助 hook。你可以看到它
00:05:52用起来非常简单。我们可以从 useHotkeyRecorder 中获取一些值，
00:05:56比如当前是否正在录制、录制到的热键本身、开始录制的函数
00:06:00以及取消录制的函数。然后在 hook 的选项中，我们
00:06:05还可以注册当热键成功录制后想要执行的操作。在我的例子中，
00:06:09我只是简单地将面板热键设置为用户选定的任何热键。一旦我们将
00:06:14所有这些连接到一个按钮上，我们就能得到类似这样的 UI。目前 command K
00:06:17会打开我的命令面板，但如果我按下录制，它现在就开始使用我的 hook，监听
00:06:21我的键盘。如果我按下 command + backspace，你可以看到这成了我打开
00:06:26命令面板的新热键。显然你可能想把它存入数据库，这样它就能
00:06:29持久保存在用户的设置中。这真是一个超级棒的辅助 hook，
00:06:33和我们看过的其他 hook 一样，它使用简单，甚至还有一些很棒的默认设置，
00:06:37比如如果他们在 macOS 上录制热键并使用了 command 键，它会自动
00:06:42将其转换为 “modifier” 键，这样当他们切换到 Windows 或 Linux 时，就会对应 control 键。
00:06:46除了这些 hook，关于这个包我还有几件事想给你们展示，
00:06:49第一个是帮助你进行格式化的函数。你看我们有
00:06:53一个叫 “formatForDisplay” 的函数，它来自 TanStack Hotkeys。它
00:06:57允许我们输入类似 “modifier + backspace” 的热键，它会自动将其转换为
00:07:02用户所在的平台格式，然后转换为图标。在这个例子中，它显示为 command backspace。
00:07:06如果我在 Windows 上，它会显示为 control backspace。接着我们还有
00:07:10“formatWithLabels” 函数，它的作用基本完全一样，除了它会将我们的
00:07:14修饰键转换为正确的文字标签而不是图标。在这个例子中是
00:07:18“command backspace”，但在 Windows 上它会显示为 “control backspace”。最后，
00:07:22我喜欢 TanStack 的原因之一是它的开发者工具（DevTools），这个包也不例外。如果我们打开
00:07:27DevTools，我们可以看到页面上注册的所有热键以及
00:07:30序列。我们可以看到有关状态的信息，以及它们被触发了多少次。
00:07:33你可以看到它是在按键按下还是弹起时触发，可以看到它是在监听
00:07:37整个 document 还是某个特定元素。在里面你甚至可以看到更多细节，
00:07:41比如为该热键或序列配置的选项，甚至可以进行
00:07:45手动触发。此外，在顶部你可以看到页面当前按下的键。
00:07:49如果你在设置时不知道某个键的值是什么，只需
00:07:52来这里按下它，你就能看到精确的值。我知道这听起来可能
00:07:56有点像老生常谈，但 TanStack 确实非常懂开发者体验，我真的
00:08:00很高兴在 AI 编程的时代我们依然能拥有这样的工具。如果你有需求，我强烈建议
00:08:05你试试这个包，并在下方的评论区
00:08:08告诉我你的看法。顺便订阅一下，我们下期视频再见。