【Mac】which-key.nvimの使い方と設定方法

こんにちは。ナミレリです。この記事ではNeovimの作業効率が劇的に向上するwhich-key.nvimの使い方と設定方法を紹介します。

which-key.nvimは、キー入力の途中で候補を下のキャプチャ画像の様にポップアップ表示してくれるNeovimのプラグインです。例えば、<leader>キーを押すと、それに続くキーの一覧がポップアップ表示され、どのキーに何が割り当てられているのかを直感的に把握できます。

which-key.nvimのポップアップ

この記事はこんな人にオススメ

複雑なキーマッピングを覚えきれずに困っている方
カスタムキーマッピングを多用している方
プラグインを多数導入している方
キーボードを積極的に使っている方
キーマッピングを「覚える」より「探したい」方
操作効率を高めたい方
UIやUXにもこだわりたいNeovimユーザー
時間短縮・ミス削減を重視する方

この記事のMac環境

M4 MacBook Air 13インチ
macOS Sequoia 15.5
NVIM v0.11.2
Parallels Desktop 20 for Mac バージョン 20.3.2 (55975)

Parallels Desktop 20 for Macの無料トライアルもありますので、ぜひダウンロードして試してみてください。M1/M2/M3のMac上で快適にMacやUbuntu、Windowsが動作します。

はじめに

Neovimのキーマッピングは非常に強力ですが、「どのキーに何を割り当てたのかわからない」という状態になってしまうことがしばしばあります。多くの方がそうだと思いますが、たくさんのプラグインをインストールしていて、個別にキーマッピングをカスタマイズしている場合に、どのキーがどの機能に紐づいているかを思い出すのが困難になります。

そこで登場するのがwhich-key.nvimです。この記事ではNeovimプラグインwhich-key.nvimについて、インストール方法や設定、活用法などを紹介していきます。

which-key.nvimとは？

which-key.nvimは、キー入力中に利用可能なキーバインドの候補をポップアップ表示してくれるNeovimのプラグインです。

例えば、<leader>キーを押すと、下のキャプチャのようにそれに続くキーの一覧が画面下部に表示され、どのキーに何が割り当てられているのかを確認することができます。ポップアップのインタフェースもかっこ良くモチベ上がります。

which-key.nvimのポップアップ

主な機能をまとめると以下のようになります。

キー入力に連動して、続けて押せるキーとその説明をアイコンとテキストを使って表示
リーダーキーに続く複数のマッピングを、グループとして可視化することができる
シンプルで見やすく、配色テーマに馴染みやすい

which-key.nvimのインストール

早速インストールしていきます。以下は、lazy.nvimを使用した例です。


{
  "folke/which-key.nvim",
  event = "VeryLazy",
  opts = {},
  keys = {
    {
      "?",
      function()
        require("which-key").show({ global = false })
      end,
      desc = "Buffer Local Keymaps (which-key)",
    },
  },
}

このような設定だけで、キーマップの設定が自動で反映されます。

ちなみに、この設定は、Neovimで?キーを押したときに現在のバッファのキーマッピング（buffer local keymaps）をwhich-keyで表示するためのカスタムキーマップを追加しています。global = trueにすると、グローバルキーマップも含めて表示されます。

Neovimを起動後、:checkhealth which-keyで状態を確認してみます。

自動的に設定が反映される仕組み

which-key.nvimは、which-key.nvimのために個別に設定しなくても、自動的に設定されているキーマップを反映してくれます。

例えば、which-key.nvimを上記のようにインストール・設定し、特別な設定をしなくても、dやc、y、<や>などのオペレーターを入してみると、それに続くモーションがポップアップで表示されているはずです。

主なオペレーター

オペレータ	説明
d	削除
c	変更
y	ヤンク
>	右にインデント
<	左にインデント

オペレーターとモーションのコンボ例

オペレータ	数字	モーション	説明
c		e	`ce`：単語の終わりまで変更
c	2	e	`c2e`：2つの単語の終わりまでを変更
c		$	`c$`：行の残りを変更

オペレーターやモーションについてざっくり知りたい方は、以下の記事をご覧ください。

Neovimのキーマッピング情報を動的に取得

which-key.nvimは、Neovimに登録されているすべてのキーマッピング情報を、vim.api.nvim_get_keymap()などのAPIを通じて動的に取得します。そのため、自分で設定したキーマップや、他のプラグインによって追加されたキーマップであっても、which-key.nvimはしっかりポップアップしてくれます。

leaderキーやローカルマップもサポート

さらに、<leader>や<localleader>にも対応しており、これらにバインドされたコマンド群をグループとして扱うこともできて、見やすいUIを実現しています。

登録順にソート・カテゴリ表示

マッピングが多くなると混乱しがちですが、which-keyは自動でカテゴリ化・整形し、わかりやすく表示してくれます。たとえば、<leader>fにファイル操作を、<leader>gにgit操作を、といったように頭で覚えるよりも視覚的に操作できるようになります。

avante.nvimについては下の記事をご覧ください。

ラベルについて

明示的にwhich-key.registerで名前をつけなくても、Neovimに登録されたマッピングのdesc属性から自動的に説明を表示してくれます。例えば、以下のようにキーマップが定義されている場合、


vim.keymap.set("n", "ff", ":Telescope find_files", { desc = "Find Files" })

which-keyはFind Filesという説明を自動的に拾って表示してくれます。個別に設定している全てのキーマップに、わかりやすくdesc属性を追加するようにすると便利です。

which-key.nvimの基本的な使い方

leaderキーに対応するコマンドを確認

上でも紹介しましたが、何も設定しなくても、<leader>を押すと次のように表示されます。

which-key.registerを使った明示的な定義

以下のように、明示的にグループ名をつけて定義することもできます。

例：Telescope連携で検索操作を集約


local wk = require("which-key")

wk.register({
  f = {
    name = "ファイル/検索",
    f = { "Telescope find_files", "ファイル検索" },
    g = { "Telescope live_grep", "文字列検索" },
    b = { "Telescope buffers", "バッファ切替" },
    h = { "Telescope help_tags", "ヘルプ" },
  },
}, { prefix = "" })

例：LSP操作をグループ化して見やすくする


local wk = require("which-key")

wk.register({
  l = {
    name = "LSP",
    d = { "Telescope lsp_definitions", "定義へジャンプ" },
    r = { "Telescope lsp_references", "参照を検索" },
    a = { vim.lsp.buf.code_action, "コードアクション" },
    R = { vim.lsp.buf.rename, "リネーム" },
    f = { vim.lsp.buf.format, "フォーマット" },
  },
}, { prefix = "" })

レイアウトのカスタマイズ

which-key.nvimのレイアウト関連の設定項目では、ポップアップウィンドウの幅や高さ、余白、位置などを調整できます。以下に主なレイアウト設定項目をまとめます。

設定項目	型	説明
height	number	表示される最大行数（デフォルト: 10）
width	number	最大列数（メニューの最大横幅）
spacing	number	キーとその説明の間隔
align	“left” / “center”	キーと説明の整列方法
min_width	number	最小の横幅（必要に応じて自動拡張）
max_width	number	最大横幅（数値または関数で指定）
min_height	number	最小縦幅
max_height	number	最大縦幅
column_spacing	number	複数列表示時の列間のスペース
position	“bottom” / “top” / “left” / “right”	ウィンドウの表示位置

レイアウトの設定例


opt = {
  layout = {
    height = 12,       -- 表示される最大行数
    width = 50,        -- 最大列数
    spacing = 6,       -- キーと説明の間隔
    align = "center",  -- 整列方法（中央揃えにする）
    column_spacing = 8,-- 複数列間のスペース
    position = "bottom" -- 画面下部に表示
  },
},

レイアウトの設定例


opts = {
  layout = {
    height = 12,
    width = 50,
    spacing = 6,
    align = "center",
    position = "bottom",
  },
  win = {
    border = "single",
  },
  plugins = {
    marks = true,
    registers = true,
    spelling = {
      enabled = true,
      suggestions = 20,
    },
  },
}

上記はあくまで設定例です。デフォルトの状態がとても見やすいです。