🖼️ image.nvim

这个插件尝试为Neovim添加图像支持。

它与Kitty + Tmux配合使用效果非常好，能够处理在缓冲区中给定位置渲染图像、滚动、窗口等复杂问题。

它内置了Markdown和Neorg集成，您现在就可以使用。

它还可以将打开的图像文件直接渲染为图像。

加入Discord: https://discord.gg/GTwbCxBNgz

https://github.com/3rd/image.nvim/assets/59587503/9a9a1792-6476-4d96-8b8e-d3cdd7f5759e

安装

这个插件需要一些外部依赖。以下是列表，下面有针对特定插件管理器的说明。

必需依赖：

ImageMagick - 请参阅安装ImageMagick
magick LuaRock

您需要选择以下之一：

Kitty >= 28.0 - 用于kitty后端
ueberzugpp - 用于ueberzug后端

完全可选：

curl - 用于远程图像

安装插件和Rock

从Lazy v11.*版本开始支持rockspec，因此不需要额外的插件vhyrro/luarocks.nvim

<details> <summary><b>Lazy >= v11.* [(由于问题已禁用)](https://github.com/3rd/image.nvim/issues/191)</b></summary>

{
    "3rd/image.nvim",
    config = function()
        -- ...
    end
}

</details> <details> <summary><b>Lazy < v11.x</b></summary>

注意： 别忘了安装ImageMagick系统包，详见下文

使用Lazy时，建议使用vhyrro/luarocks.nvim为Neovim安装luarocks。但您也可以手动安装。

使用luarocks.nvim： **请阅读luarocks.nvim的README，**它目前有一个外部依赖。

{
    "vhyrro/luarocks.nvim",
    priority = 1001, -- 该插件需要在其他插件之前运行
    opts = {
        rocks = { "magick" },
    },
},
{
    "3rd/image.nvim",
    dependencies = { "luarocks.nvim" },
    config = function()
        -- ...
    end
}

</details>

或不使用luarocks.nvim：

您必须手动安装luarock。

通过系统包管理器在系统上安装luarocks
运行luarocks --local --lua-version=5.1 install magick

-- 配置Neovim加载用户安装的Lua rocks的示例：
package.path = package.path .. ";" .. vim.fn.expand("$HOME") .. "/.luarocks/share/lua/5.1/?/init.lua"
package.path = package.path .. ";" .. vim.fn.expand("$HOME") .. "/.luarocks/share/lua/5.1/?.lua"

-- lazy代码片段
{
    "3rd/image.nvim",
    config = function()
        -- ...
    end
}

</details> <details> <summary>Rocks.nvim</summary>

注意： 别忘了安装ImageMagick系统包，详见下文

:Rocks install image.nvim

</details> <details> <summary>NixOS</summary>

NixOS用户需要安装imagemagick和luajitPackages.magick （感谢@donovanglover的贡献）。

建议您可以使用这些包构建Neovim，如下所示：

<details> <summary>使用home-manager</summary>

感谢@wuliuqii在#13中的贡献

{ pkgs, ... }:

{
  programs.neovim = {
    enable = true;
    extraLuaPackages = ps: [ ps.magick ];
    extraPackages = ps: [ ps.imagemagick ];
    # ... 其他配置
  };
}

</details> <details> <summary>原生NixOS</summary>

# https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/neovim/utils.nix#L27
{ pkgs, neovimUtils, wrapNeovimUnstable, ... }:

let
  config = pkgs.neovimUtils.makeNeovimConfig {
    extraLuaPackages = p: [ p.magick ];
    extraPackages = p: [ p.imagemagick ];
    # ... 其他配置
  };
in {
  nixpkgs.overlays = [
    (_: super: {
      neovim-custom = pkgs.wrapNeovimUnstable
        (super.neovim-unwrapped.overrideAttrs (oldAttrs: {
          buildInputs = oldAttrs.buildInputs ++ [ super.tree-sitter ];
        })) config;
    })
  ];
  environment.systemPackages = with pkgs; [ neovim-custom ];
}

</details> </details>

安装ImageMagick

magick luarock提供了ImageMagick的MagickWand绑定，因此我们还需要安装该包。

Ubuntu: sudo apt install libmagickwand-dev
MacOS: brew install imagemagick
- 默认情况下，brew安装在一个奇怪的位置，所以您必须将$(brew --prefix)/lib添加到 DYLD_LIBRARY_PATH中，方法是在shell配置文件（可能是.zshrc或.bashrc）中添加类似 export DYLD_LIBRARY_PATH="$(brew --prefix)/lib:$DYLD_LIBRARY_PATH" 的内容
Fedora: sudo dnf install ImageMagick-devel
Arch: sudo pacman -Syu imagemagick

配置

-- 默认配置
require("image").setup({
  backend = "kitty",
  integrations = {
    markdown = {
      enabled = true,
      clear_in_insert_mode = false,
      download_remote_images = true,
      only_render_image_at_cursor = false,
      filetypes = { "markdown", "vimwiki" }, -- markdown扩展（如quarto）可以放在这里
    },
    neorg = {
      enabled = true,
      clear_in_insert_mode = false,
      download_remote_images = true,
      only_render_image_at_cursor = false,
      filetypes = { "norg" },
    },
    html = {
      enabled = false,
    },
    css = {
      enabled = false,
    },
  },
  max_width = nil,
  max_height = nil,
  max_width_window_percentage = nil,
  max_height_window_percentage = 50,
  window_overlap_clear_enabled = false, -- 当窗口重叠时切换图像
  window_overlap_clear_ft_ignore = { "cmp_menu", "cmp_docs", "" },
  editor_only_render_when_focused = false, -- 当编辑器获得/失去焦点时自动显示/隐藏图像
  tmux_show_only_in_active_window = false, -- 在正确的Tmux窗口中自动显示/隐藏图像（需要关闭visual-activity）
  hijack_file_patterns = { "*.png", "*.jpg", "*.jpeg", "*.gif", "*.webp", "*.avif" }, -- 打开时将图像文件渲染为图像
})

Tmux

您必须使用tmux >= 3.3并设置：set -gq allow-passthrough on
如果您希望在切换窗口时自动隐藏/显示图像（tmux_show_only_in_active_window = true），请设置：set -g visual-activity off

使用最小设置尝试

从此仓库的根目录下载minimal-setup.lua，然后运行演示：

nvim --clean -c ":luafile minimal-setup.lua"

后端

所有后端都支持在Tmux内渲染。

kitty - 同类最佳，运行良好且非常流畅
ueberzug - 由ueberzugpp支持，支持任何终端，但性能较低
- 支持多个图像，感谢@jstkdng。

集成

markdown - 使用tree-sitter-markdown，支持任何基于Markdown的语法（Quarto, VimWiki Markdown）
neorg - 使用tree-sitter-norg（另请查看https://github.com/nvim-neorg/neorg/issues/971）

您可以通过向resolve_image_path传递函数来配置每个集成的图像搜索位置，如下所示：

require('image').setup({
  integrations = {
    markdown = {
      resolve_image_path = function(document_path, image_path, fallback)
        -- document_path是包含图像的文件的路径
        -- image_path是图像的潜在相对路径。对于
        -- markdown，它是`![](https://raw.githubusercontent.com/3rd/image.nvim/master/this text)`

        -- 您可以调用fallback函数来获取默认行为
        return fallback(document_path, image_path)
      end,
    }
  }
})

API

查看 types.lua 以获得关于所有内容建模方式的更好概览。

local api = require("image")

-- 从文件加载（绝对路径）
local image = api.from_file("/path/to/image.png", {
  id = "my_image_id", -- 可选，默认为随机字符串
  window = 1000, -- 可选，将图像绑定到窗口及其边界
  buffer = 1000, -- 可选，将图像绑定到缓冲区（与窗口绑定配对）
  with_virtual_padding = true, -- 可选，使用extmarks垂直填充，默认为false

  -- 可选，将图像绑定到它所跟随的extmark。当`with_virtual_padding`为true时强制为true。默认为false。
  inline = true,

  -- 几何参数（可选）
  x = 1,
  y = 1,
  width = 10,
  height = 10
})

-- 从URL加载
api.from_url("https://gist.ro/s/remote.png", {
    -- 所有上述相同的选项
}, function(img)
    -- 对图像进行操作
end
)

image:render() -- 渲染图像
image:render(geometry) -- 更新图像几何参数并渲染
image:clear()

image:move(x, y) -- 移动图像
image:brightness(value) -- 改变亮度
image:saturation(value) -- 改变饱和度
image:hue(value) -- 改变色调