Rofi 缩略图系统rofi-thumbnails完整指南XDG Thumbnailer、-preview-cmd 自定义命令与 AppArmor 排障【免费下载链接】rofiRofi: A window switcher, application launcher and dmenu replacement项目地址: https://gitcode.com/gh_mirrors/ro/rofirofi窗口切换器、应用启动器与 dmenu 替代品从 1.7 系列开始支持为所有存在 XDG 兼容 thumbnailer 的文件类型显示缩略图。本文基于仓库中的 mkdocs/docs/1.7.6/rofi-thumbnails.5.markdown 手册页深入讲解thumbnail://前缀协议、.thumbnailer文件格式与缓存目录机制、-preview-cmd自定义缩略图生成命令以及 Ubuntu/Debian 等发行版上的 AppArmor 问题与解决方案。读完本文你将能够在 filebrowser/recursivebrowser 模式、dmenu 模式及自定义脚本中完整配置并调优 rofi 的缩略图显示能力。概述rofi 如何显示文件缩略图手册页开篇即说明核心能力rofi 现在可以为系统中存在 XDG 兼容 thumbnailer 的所有文件类型显示缩略图**rofi** is now able to show thumbnails for all file types where an XDG compatible thumbnailer is present in the system。在 filebrowser文件浏览器和 recursivebrowser递归文件浏览器模式下只要以-show-icons参数启动 rofi缩略图显示就会默认启用。从源码实现看这一行为由 source/modes/filebrowser.c 的_get_icon()函数体现若文件本身是图片通过rofi_icon_fetcher_file_is_image()判断直接按路径查询图标若文件是普通文件则构造thumbnail://前缀的查询名g_strconcat(thumbnail://, dr-path, NULL)交给图标抓取器目录等类型则使用类型图标名。而在自定义用户脚本或 dmenu 模式中你可以通过给\0icon\x1f后指定的文件名加上thumbnail://前缀利用 XDG thumbnailer 生成条目图标。下面是手册页给出的完整可运行示例echo -en EntryName\0icon\x1fthumbnail://path/to/file\n | rofi -dmenu -show-icons-show-icons选项在 doc/rofi.1.markdown 中定义为「加载并在默认主题中显示图标」默认值为关闭见 config/config.c 中的.show_icons FALSE在 source/xrmoptions.c 中注册为命令行/XResources 可配置项。同时还可搭配-icon-theme指定图标主题默认使用桌面环境主题Adwaita与gnome作为回退主题见 source/rofi-icon-fetcher.c。XDG Thumbnailer 详解.thumbnailer 文件格式与存放位置XDG thumbnailer 是后缀为.thumbnailer的文件结构类似用于启动应用的.desktop文件。它们存放在/usr/share/thumbnailers/系统级$HOME/.local/share/thumbnailers/用户级文件中包含一组 mimetype 列表针对这些类型可以生成缩略图以及一条生成图片的命令字符串。手册页给出的librsvg.thumbnailer使用 librsvg 处理 svg 文件的 thumbnailer完整示例[Thumbnailer Entry] TryExec/usr/bin/gdk-pixbuf-thumbnailer Exec/usr/bin/gdk-pixbuf-thumbnailer -s %s %u %o MimeTypeimage/svgxml;image/svgxml-compressed;其中关键字段字段含义[Thumbnailer Entry]组名源码中以THUMBNAILER_ENTRY_GROUP宏定义source/rofi-icon-fetcher.cTryExec探测性可执行文件用于判断 thumbnailer 是否可用Exec实际生成缩略图的命令模板MimeType以分号分隔的 MIME 类型列表该 thumbnailer 可处理这些类型Exec中的占位符会被 rofi 在运行时替换见 source/rofi-icon-fetcher.c 的setup_thumbnailer_command()占位符替换内容%i输入文件名%u输入文件的 URI 编码形式%o缩略图输出路径%s请求的缩略图尺寸缩略图缓存目录与命名规则生成的图片以输入文件的 md5 哈希值命名并根据尺寸放入 XDG 缩略图目录$HOME/.cache/thumbnails/normal/ ≤128px $HOME/.cache/thumbnails/large/ ≤256px $HOME/.cache/thumbnails/x-large/ ≤512px $HOME/.cache/thumbnails/xx-large/ 512px这一逻辑在 source/rofi-icon-fetcher.c 的rofi_icon_fetcher_get_thumbnail()中实现对条目名计算 MD5按requested_size选择目录128/256/512/1024 四档文件名为md5.png并自动创建目录g_mkdir_with_parents(thumb_dir, 0700)。这些缩略图既被 rofi 作为条目图标加载也可被 Thunar、Caja、KDE Dolphin 等文件管理器复用。反向同样成立如果缩略图目录中已存在某个文件对应的缩略图无论由 rofi 还是文件管理器生成rofi 会直接加载已有缩略图而不重新调用 thumbnailer手册页明确说明源码中体现为 source/rofi-icon-fetcher.c 的g_file_test(icon_path, G_FILE_TEST_EXISTS)检查。如果某个文件找不到合适的 thumbnailerrofi 会回退到图标主题中对应的 mimetype 图标——源码中表现为将 mimetype 中的/替换为-后作为图标名查询如text/plain→text-plain见 source/rofi-icon-fetcher.c。加载与执行流程源码视角thumbnailer 的加载与调用链路清晰地位于 source/rofi-icon-fetcher.c初始化加载rofi_icon_fetcher_init()L273-L319通过rofi_icon_fetcher_load_thumbnailers()遍历用户数据目录g_get_user_data_dir()与系统数据目录g_get_system_data_dirs()找到所有.thumbnailer后缀文件解析Exec与MimeType建立mimetype → 命令的哈希表L105-L159。图标请求界面线程通过rofi_icon_fetcher_query_advanced()L752 起发起查询将任务推入线程池g_thread_pool_push避免阻塞 UI。工作线程处理rofi_icon_fetcher_worker()L528-L750检测到thumbnail://前缀后L539截取前缀之后的真实路径sentry-entry-name[12]thumbnail://恰好 12 个字符按请求尺寸查找或生成缩略图。命令执行rofi_icon_fetcher_create_thumbnail()L223-L247从哈希表取出命令展开占位符后由exec_thumbnailer_command()L204-L221以g_spawn_sync同步执行值得注意的是命令前会附加nice -n 19将缩略图生成进程的优先级降到最低L173-L178避免影响系统交互性能。图标渲染生成的 PNG 经gdk_pixbuf_new_from_file_at_scale()按请求尺寸加载为 pixbuf再转换为 cairo surface 供界面绘制L702-L750。使用 -preview-cmd 自定义缩略图生成命令对于通用条目名例如一个脚本需要根据 URL 下载图标、或根据输入选择不同图标可以放弃 XDG thumbnailer改用自定义命令。手册页给出的语法rofi ... -preview-cmd path/to/script_or_cmd {input} {output} {size}rofi 调用该脚本/命令时依次替换三个占位符占位符替换内容{input}输入条目图标名即\0icon\x1fthumbnail://之后的部分{output}缩略图输出文件名{size}请求的缩略图尺寸脚本/命令负责生成缩略图尽可能尊重请求的尺寸并保存到{output}指定的文件。也就是说-preview-cmd完全接管了「如何把输入变成一个图片文件」这一步输出结果仍会进入上述 XDG 缩略图缓存体系。源码支撑位于 source/rofi-icon-fetcher.c当条目名带thumbnail://前缀且config.preview_cmd ! NULL时工作线程计算目标缩略图路径若文件不存在则通过helper_parse_setup()将{input}、{output}、{size}替换为真实值构造命令参数并调用exec_thumbnailer_command()执行。配置项默认值为 NULL见 config/config.c通过 source/xrmoptions.c 注册命令行选项对应结构体字段在 include/settings.h。一个典型的自定义脚本示意可以是#!/bin/bash # thumbnail-cmd.sh —— 被 rofi -preview-cmd 调用的自定义缩略图生成器 input$1 # {input}: 图标名 / 条目名 output$2 # {output}: 输出缩略图路径 size$3 # {size}: 请求尺寸 # 例从 URL 下载图片并缩放后写入 $output curl -fsSL $input | convert - -resize ${size}x${size} $output使用时rofi -dmenu -show-icons -preview-cmd /path/to/thumbnail-cmd.sh {input} {output} {size}。处理 AppArmor 限制在启用了 AppArmor 的发行版如 Ubuntu、Debian上默认规则可能导致缩略图生成失败。手册页提供了两种解决路径。方案一直接停用 AppArmorsudo systemctl stop apparmor sudo systemctl disable apparmor该方案简单但会全局关闭 AppArmor 保护仅适合不依赖该安全模块的环境。方案二为 rofi 编写专属 AppArmor 策略推荐将以下配置文件保存为/etc/apparmor.d/usr.bin.rofi手册页原文为 rofi 授予读写主目录、访问缩略图缓存及 NFS 所需的网络能力#vim:syntaxapparmor # AppArmor policy for rofi #include tunables/global /usr/bin/rofi { #include abstractions/base # TCP/UDP network access for NFS network inet stream, network inet6 stream, network inet dgram, network inet6 dgram, /usr/bin/rofi mr, {HOME}/ r, {HOME}/** rw, owner {HOME}/.cache/thumbnails/** rw, }随后重载规则apparmor_parser -r /etc/apparmor.d/usr.bin.rofi要点说明该策略假设 rofi 二进制位于/usr/bin/rofi标准包安装即为此路径若为自定义编译安装需相应调整路径段{HOME}/.cache/thumbnails/** rw权限与上文缩略图缓存目录$HOME/.cache/thumbnails/{normal,large,x-large,xx-large}相对应确保 rofi 能读取已有缓存并写入新生成的缩略图网络访问规则服务于通过 NFS 共享的文件系统场景。配置速查与注意事项将本文涉及的核心配置汇总如下均可在命令行或 XResources 中设置注册位置见 source/xrmoptions.c配置项作用默认值-show-icons加载并在默认主题中显示图标false-icon-theme指定图标主题缺省用 DE 主题回退 Adwaita/gnome系统默认-preview-cmd自定义缩略图生成命令占位符{input}/{output}/{size}未设置实战注意点filebrowser/recursivebrowser 模式图片文件直接以原图路径查询普通文件走thumbnail://协议目录用类型图标——这三类分支的处理见 source/modes/filebrowser.c缓存复用只要$HOME/.cache/thumbnails/下已存在对应 md5 的缩略图rofi 便不会重新调用 thumbnailer因此文件管理器与 rofi 之间可以共享缓存、互相加速低优先级执行thumbnailer 进程会以nice -n 19运行大量文件首次浏览时缩略图会分批异步生成界面不会卡顿回退机制没有合适 thumbnailer 时自动使用 mimetype 图标保证列表仍然可读AppArmor遇到缩略图不生成、日志中出现权限拒绝类错误时优先检查是否命中默认 AppArmor 限制并采用上述专属策略而非全局禁用。通过thumbnail://协议、XDG thumbnailer 标准、-preview-cmd扩展与缓存复用机制rofi 的图标体系既能开箱即用地服务于文件浏览又能被 dmenu 脚本和自定义启动器深度定制形成一套完整、可预测的缩略图工作流。【免费下载链接】rofiRofi: A window switcher, application launcher and dmenu replacement项目地址: https://gitcode.com/gh_mirrors/ro/rofi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rofi 缩略图系统（rofi-thumbnails）完整指南：XDG Thumbnailer、-preview-cmd 自定义命令与 AppArmor 排障
Rofi 缩略图系统rofi-thumbnails完整指南XDG Thumbnailer、-preview-cmd 自定义命令与 AppArmor 排障【免费下载链接】rofiRofi: A window switcher, application launcher and dmenu replacement项目地址: https://gitcode.com/gh_mirrors/ro/rofirofi窗口切换器、应用启动器与 dmenu 替代品从 1.7 系列开始支持为所有存在 XDG 兼容 thumbnailer 的文件类型显示缩略图。本文基于仓库中的 mkdocs/docs/1.7.6/rofi-thumbnails.5.markdown 手册页深入讲解thumbnail://前缀协议、.thumbnailer文件格式与缓存目录机制、-preview-cmd自定义缩略图生成命令以及 Ubuntu/Debian 等发行版上的 AppArmor 问题与解决方案。读完本文你将能够在 filebrowser/recursivebrowser 模式、dmenu 模式及自定义脚本中完整配置并调优 rofi 的缩略图显示能力。概述rofi 如何显示文件缩略图手册页开篇即说明核心能力rofi 现在可以为系统中存在 XDG 兼容 thumbnailer 的所有文件类型显示缩略图**rofi** is now able to show thumbnails for all file types where an XDG compatible thumbnailer is present in the system。在 filebrowser文件浏览器和 recursivebrowser递归文件浏览器模式下只要以-show-icons参数启动 rofi缩略图显示就会默认启用。从源码实现看这一行为由 source/modes/filebrowser.c 的_get_icon()函数体现若文件本身是图片通过rofi_icon_fetcher_file_is_image()判断直接按路径查询图标若文件是普通文件则构造thumbnail://前缀的查询名g_strconcat(thumbnail://, dr-path, NULL)交给图标抓取器目录等类型则使用类型图标名。而在自定义用户脚本或 dmenu 模式中你可以通过给\0icon\x1f后指定的文件名加上thumbnail://前缀利用 XDG thumbnailer 生成条目图标。下面是手册页给出的完整可运行示例echo -en EntryName\0icon\x1fthumbnail://path/to/file\n | rofi -dmenu -show-icons-show-icons选项在 doc/rofi.1.markdown 中定义为「加载并在默认主题中显示图标」默认值为关闭见 config/config.c 中的.show_icons FALSE在 source/xrmoptions.c 中注册为命令行/XResources 可配置项。同时还可搭配-icon-theme指定图标主题默认使用桌面环境主题Adwaita与gnome作为回退主题见 source/rofi-icon-fetcher.c。XDG Thumbnailer 详解.thumbnailer 文件格式与存放位置XDG thumbnailer 是后缀为.thumbnailer的文件结构类似用于启动应用的.desktop文件。它们存放在/usr/share/thumbnailers/系统级$HOME/.local/share/thumbnailers/用户级文件中包含一组 mimetype 列表针对这些类型可以生成缩略图以及一条生成图片的命令字符串。手册页给出的librsvg.thumbnailer使用 librsvg 处理 svg 文件的 thumbnailer完整示例[Thumbnailer Entry] TryExec/usr/bin/gdk-pixbuf-thumbnailer Exec/usr/bin/gdk-pixbuf-thumbnailer -s %s %u %o MimeTypeimage/svgxml;image/svgxml-compressed;其中关键字段字段含义[Thumbnailer Entry]组名源码中以THUMBNAILER_ENTRY_GROUP宏定义source/rofi-icon-fetcher.cTryExec探测性可执行文件用于判断 thumbnailer 是否可用Exec实际生成缩略图的命令模板MimeType以分号分隔的 MIME 类型列表该 thumbnailer 可处理这些类型Exec中的占位符会被 rofi 在运行时替换见 source/rofi-icon-fetcher.c 的setup_thumbnailer_command()占位符替换内容%i输入文件名%u输入文件的 URI 编码形式%o缩略图输出路径%s请求的缩略图尺寸缩略图缓存目录与命名规则生成的图片以输入文件的 md5 哈希值命名并根据尺寸放入 XDG 缩略图目录$HOME/.cache/thumbnails/normal/ ≤128px $HOME/.cache/thumbnails/large/ ≤256px $HOME/.cache/thumbnails/x-large/ ≤512px $HOME/.cache/thumbnails/xx-large/ 512px这一逻辑在 source/rofi-icon-fetcher.c 的rofi_icon_fetcher_get_thumbnail()中实现对条目名计算 MD5按requested_size选择目录128/256/512/1024 四档文件名为md5.png并自动创建目录g_mkdir_with_parents(thumb_dir, 0700)。这些缩略图既被 rofi 作为条目图标加载也可被 Thunar、Caja、KDE Dolphin 等文件管理器复用。反向同样成立如果缩略图目录中已存在某个文件对应的缩略图无论由 rofi 还是文件管理器生成rofi 会直接加载已有缩略图而不重新调用 thumbnailer手册页明确说明源码中体现为 source/rofi-icon-fetcher.c 的g_file_test(icon_path, G_FILE_TEST_EXISTS)检查。如果某个文件找不到合适的 thumbnailerrofi 会回退到图标主题中对应的 mimetype 图标——源码中表现为将 mimetype 中的/替换为-后作为图标名查询如text/plain→text-plain见 source/rofi-icon-fetcher.c。加载与执行流程源码视角thumbnailer 的加载与调用链路清晰地位于 source/rofi-icon-fetcher.c初始化加载rofi_icon_fetcher_init()L273-L319通过rofi_icon_fetcher_load_thumbnailers()遍历用户数据目录g_get_user_data_dir()与系统数据目录g_get_system_data_dirs()找到所有.thumbnailer后缀文件解析Exec与MimeType建立mimetype → 命令的哈希表L105-L159。图标请求界面线程通过rofi_icon_fetcher_query_advanced()L752 起发起查询将任务推入线程池g_thread_pool_push避免阻塞 UI。工作线程处理rofi_icon_fetcher_worker()L528-L750检测到thumbnail://前缀后L539截取前缀之后的真实路径sentry-entry-name[12]thumbnail://恰好 12 个字符按请求尺寸查找或生成缩略图。命令执行rofi_icon_fetcher_create_thumbnail()L223-L247从哈希表取出命令展开占位符后由exec_thumbnailer_command()L204-L221以g_spawn_sync同步执行值得注意的是命令前会附加nice -n 19将缩略图生成进程的优先级降到最低L173-L178避免影响系统交互性能。图标渲染生成的 PNG 经gdk_pixbuf_new_from_file_at_scale()按请求尺寸加载为 pixbuf再转换为 cairo surface 供界面绘制L702-L750。使用 -preview-cmd 自定义缩略图生成命令对于通用条目名例如一个脚本需要根据 URL 下载图标、或根据输入选择不同图标可以放弃 XDG thumbnailer改用自定义命令。手册页给出的语法rofi ... -preview-cmd path/to/script_or_cmd {input} {output} {size}rofi 调用该脚本/命令时依次替换三个占位符占位符替换内容{input}输入条目图标名即\0icon\x1fthumbnail://之后的部分{output}缩略图输出文件名{size}请求的缩略图尺寸脚本/命令负责生成缩略图尽可能尊重请求的尺寸并保存到{output}指定的文件。也就是说-preview-cmd完全接管了「如何把输入变成一个图片文件」这一步输出结果仍会进入上述 XDG 缩略图缓存体系。源码支撑位于 source/rofi-icon-fetcher.c当条目名带thumbnail://前缀且config.preview_cmd ! NULL时工作线程计算目标缩略图路径若文件不存在则通过helper_parse_setup()将{input}、{output}、{size}替换为真实值构造命令参数并调用exec_thumbnailer_command()执行。配置项默认值为 NULL见 config/config.c通过 source/xrmoptions.c 注册命令行选项对应结构体字段在 include/settings.h。一个典型的自定义脚本示意可以是#!/bin/bash # thumbnail-cmd.sh —— 被 rofi -preview-cmd 调用的自定义缩略图生成器 input$1 # {input}: 图标名 / 条目名 output$2 # {output}: 输出缩略图路径 size$3 # {size}: 请求尺寸 # 例从 URL 下载图片并缩放后写入 $output curl -fsSL $input | convert - -resize ${size}x${size} $output使用时rofi -dmenu -show-icons -preview-cmd /path/to/thumbnail-cmd.sh {input} {output} {size}。处理 AppArmor 限制在启用了 AppArmor 的发行版如 Ubuntu、Debian上默认规则可能导致缩略图生成失败。手册页提供了两种解决路径。方案一直接停用 AppArmorsudo systemctl stop apparmor sudo systemctl disable apparmor该方案简单但会全局关闭 AppArmor 保护仅适合不依赖该安全模块的环境。方案二为 rofi 编写专属 AppArmor 策略推荐将以下配置文件保存为/etc/apparmor.d/usr.bin.rofi手册页原文为 rofi 授予读写主目录、访问缩略图缓存及 NFS 所需的网络能力#vim:syntaxapparmor # AppArmor policy for rofi #include tunables/global /usr/bin/rofi { #include abstractions/base # TCP/UDP network access for NFS network inet stream, network inet6 stream, network inet dgram, network inet6 dgram, /usr/bin/rofi mr, {HOME}/ r, {HOME}/** rw, owner {HOME}/.cache/thumbnails/** rw, }随后重载规则apparmor_parser -r /etc/apparmor.d/usr.bin.rofi要点说明该策略假设 rofi 二进制位于/usr/bin/rofi标准包安装即为此路径若为自定义编译安装需相应调整路径段{HOME}/.cache/thumbnails/** rw权限与上文缩略图缓存目录$HOME/.cache/thumbnails/{normal,large,x-large,xx-large}相对应确保 rofi 能读取已有缓存并写入新生成的缩略图网络访问规则服务于通过 NFS 共享的文件系统场景。配置速查与注意事项将本文涉及的核心配置汇总如下均可在命令行或 XResources 中设置注册位置见 source/xrmoptions.c配置项作用默认值-show-icons加载并在默认主题中显示图标false-icon-theme指定图标主题缺省用 DE 主题回退 Adwaita/gnome系统默认-preview-cmd自定义缩略图生成命令占位符{input}/{output}/{size}未设置实战注意点filebrowser/recursivebrowser 模式图片文件直接以原图路径查询普通文件走thumbnail://协议目录用类型图标——这三类分支的处理见 source/modes/filebrowser.c缓存复用只要$HOME/.cache/thumbnails/下已存在对应 md5 的缩略图rofi 便不会重新调用 thumbnailer因此文件管理器与 rofi 之间可以共享缓存、互相加速低优先级执行thumbnailer 进程会以nice -n 19运行大量文件首次浏览时缩略图会分批异步生成界面不会卡顿回退机制没有合适 thumbnailer 时自动使用 mimetype 图标保证列表仍然可读AppArmor遇到缩略图不生成、日志中出现权限拒绝类错误时优先检查是否命中默认 AppArmor 限制并采用上述专属策略而非全局禁用。通过thumbnail://协议、XDG thumbnailer 标准、-preview-cmd扩展与缓存复用机制rofi 的图标体系既能开箱即用地服务于文件浏览又能被 dmenu 脚本和自定义启动器深度定制形成一套完整、可预测的缩略图工作流。【免费下载链接】rofiRofi: A window switcher, application launcher and dmenu replacement项目地址: https://gitcode.com/gh_mirrors/ro/rofi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考