15.6 自定义主题

自定义主题(Custom themes)是可以**整体启用或禁用**的一组设置集合。 See Custom Themes in The GNU Emacs Manual。 每个自定义主题都由一个 Emacs Lisp 源文件定义,该文件应遵循本节描述的规范。 (你不必手动编写自定义主题,也可以使用类似自定义界面的工具创建; See Creating Custom Themes in The GNU Emacs Manual。)

自定义主题文件应命名为 foo-theme.el, 其中 foo 是主题名称。 文件中的第一个 Lisp 表达式应为调用 deftheme, 最后一个表达式应为调用 provide-theme

Macro: deftheme theme &optional doc &rest properties

该宏将 theme(一个符号)声明为自定义主题的名称。 可选参数 doc 应为描述该主题的字符串; 当用户调用 describe-theme 命令, 或在 ‘*Custom Themes*’ 缓冲区中按下 ? 时,会显示这段描述。 剩余参数 properties 用于传递包含主题属性的属性列表。

支持以下属性:

:family

一个符号,用于标识主题所属的 “family(系列)”。 主题的 系列(family) 是一组在细节上有所不同的相似主题, 例如分别适用于框架浅色、深色背景的 face 颜色。

:kind

一个符号。如果某个主题已启用,且该属性值为 color-scheme, 则 theme-choose-variant 命令会查找同一系列下的其他可用主题, 以便进行主题切换。其他值目前未定义,不应使用。

:background-mode

一个符号,为 light(浅色)或 dark(深色)。 该属性目前暂未使用,但仍建议写明。

有两个特殊主题名称禁止使用(使用会报错): user 是存储用户直接自定义设置的虚拟主题, changed 是存储在自定义系统之外所做修改的虚拟主题。

Macro: provide-theme theme

该宏声明名为 theme 的主题已完整定义。

defthemeprovide-theme 之间是用于指定主题设置的 Lisp 表达式: 通常是调用 custom-theme-set-variables 和/或 调用 custom-theme-set-faces

Function: custom-theme-set-variables theme &rest args

该函数指定自定义主题 theme 的变量设置。 theme 应为符号。args 中的每个参数格式为:

(var expression [now [request [comment]]])

列表中各项含义与 custom-set-variables 一致。See 应用自定义设置

Function: custom-theme-set-faces theme &rest args

该函数指定自定义主题 theme 的 face 设置。 theme 应为符号。args 中的每个参数格式为:

(face spec [now [comment]])

列表中各项含义与 custom-set-faces 一致。See 应用自定义设置

理论上,主题文件也可以包含其他 Lisp 表达式,这些表达式会在加载主题时执行, 但这属于不良写法。 为防止加载包含恶意代码的主题,Emacs 在首次加载任何非内置主题前, 都会显示源文件并请求用户确认。 因此,主题通常不会被字节编译, 且 Emacs 在加载主题时,通常优先读取源文件。

以下函数可用于以编程方式启用和禁用主题:

Function: custom-theme-p theme

如果 theme(符号)是一个已加载到 Emacs 中的自定义主题名称 (无论是否启用),该函数返回非 nil;否则返回 nil

Variable: custom-known-themes

该变量的值是已加载到 Emacs 中的主题列表。 每个主题由一个 Lisp 符号(主题名)表示。 该变量的默认值包含两个虚拟主题:(user changed)changed 主题存储应用任何自定义主题之前的设置 (例如在自定义系统外设置的变量)。 user 主题存储用户自定义并保存的设置。 通过 deftheme 宏声明的其他主题会被添加到该列表头部。

Command: load-theme theme &optional no-confirm no-enable

该函数从源文件中加载名为 theme 的自定义主题, 在变量 custom-theme-load-path 指定的目录中查找源文件。 See Custom Themes in The GNU Emacs Manual。 它还会启用该主题(除非可选参数 no-enablenil), 使其变量与 face 设置生效。 除非可选参数 no-confirmnil, 否则加载主题前会提示用户确认。

Function: require-theme feature &optional noerror

该函数在 custom-theme-load-path 中搜索并加载提供 feature 的文件。 它类似于函数 require(see 功能), 区别在于它搜索 custom-theme-load-path 而非 load-path (see 库搜索)。 在某些自定义主题需要加载辅助 Lisp 文件,而 require 不适用时,该函数很有用。

如果根据 featurep 判断,符号 feature 尚未存在于当前 Emacs 会话中, 则 require-theme 会在 custom-theme-load-path 指定的目录中, 依次查找后缀为 ‘.elc’ 或 ‘.el’ 的 feature 文件。

若成功找到并加载了提供 feature 的文件, require-theme 返回 feature。 可选参数 noerror 决定搜索或加载失败时的行为: 若为 nil,函数会报错;否则返回 nil。 如果文件加载成功但未提供 featurerequire-theme 仍然会报错,且无法抑制。

Command: enable-theme theme

启用名为 theme 的自定义主题。 如果该主题未加载,则报错。

Command: disable-theme theme

禁用名为 theme 的自定义主题。 主题仍保持加载状态,后续调用 enable-theme 可重新启用。


emacs

Emacs

org-mode

Orgmode

Donations

打赏

Copyright

© 2025 Jasper Hsu

Creative Commons

Creative Commons

Attribute

Attribute

Noncommercial

Noncommercial

Share Alike

Share Alike