15.1 通用项关键字

接下来几节将要介绍的自定义声明 — defcustomdefgroup 等 — 都接受关键字参数(see 永不改变的变量),用于指定各类信息。本节描述适用于所有类型自定义声明的关键字。

:tag 外,所有这些关键字在同一个项中都可以多次使用,每次使用效果相互独立。:tag 是个例外,因为同一个项只能显示一个名称。

:tag label

在自定义菜单和缓冲区中,使用字符串 label(而非项本身的名称)作为该项的标签。不要使用与项的真实名称差异过大的标签,否则会造成混淆。

:group group

将该自定义项加入到组 group 中。如果自定义项缺少此关键字,则会被放入当前文件中最后定义的组。

defgroup 中使用 :group 时,会将新组设为 group 的子组。

如果多次使用该关键字,可以将同一个项放入多个组。显示其中任意一个组时都会出现该项。请不要过度使用此功能,否则会造成使用上的困扰。

:link link-data

在该项的文档字符串后添加一个外部链接。这是一段带有按钮的文字,可跳转至其他相关文档。

link-data 支持以下几种写法:

(custom-manual info-node)

链接到某个 Info 节点;info-node 是一个字符串,用于指定节点名称,例如 "(emacs)Top"。该链接在自定义缓冲区中显示为 ‘[Manual]’,点击后会打开内置的 Info 阅读器并跳转到对应节点。

(info-link info-node)

作用与 custom-manual 相同,区别是该链接在自定义缓冲区中直接显示 Info 节点名称。

(url-link url)

链接到某个网页;url 是表示网址的字符串 URL。该链接在自定义缓冲区中显示为 url,点击后会调用由 browse-url-browser-function 指定的网页浏览器打开。

(emacs-commentary-link library)

链接到某个库的注释说明部分;library 是表示库名的字符串。See Conventional Headers for Emacs Libraries

(emacs-library-link library)

链接到某个 Emacs Lisp 库文件;library 是表示库名的字符串。

(file-link file)

链接到某个文件;file 是表示文件名的字符串。用户激活该链接时,会通过 find-file 打开对应文件。

(function-link function)

链接到函数的文档;function 是一个字符串,指定函数名。用户点击该链接时,会通过 describe-function 显示该函数的说明。

(variable-link variable)

链接到变量的文档;variable 是一个字符串,指定变量名。用户点击该链接时,会通过 describe-variable 显示该变量的说明。

(face-link face)

链接到外观(face)的文档;face 是一个字符串,指定外观名称。用户点击该链接时,会通过 describe-face 显示该外观的说明。

(custom-group-link group)

链接到另一个自定义组。激活该链接会为 group 创建一个新的自定义缓冲区。

你可以在 link-data 的第一个元素后面添加 :tag name,来指定在自定义缓冲区中显示的文字。例如:(info-link :tag "foo" "(emacs)Top") 会生成一个指向 Emacs 手册的链接,在缓冲区中显示为 ‘foo’。

你可以多次使用该关键字,以添加多个链接。

:load file

在显示该自定义项之前,加载文件 file(字符串)(see 加载)。加载通过 load 完成,且仅在文件尚未加载时执行。

:require feature

当你保存的自定义设置设置该项的值时,执行 (require 'feature)feature 应为一个符号。

使用 :require 最常见的场景是:某个变量用于启用某个功能(如次要模式),而如果未加载实现该模式的代码,仅仅设置变量不会产生任何效果。

:version version

该关键字用于指定:该项是在 Emacs 版本 version 中首次引入的,或其默认值在该版本中被修改。version 必须为字符串。

:package-version '(package . version)

该关键字用于指定:该项是在 packageversion 版本中首次引入的,或其含义、默认值在该版本中被修改。该关键字的优先级高于 :version

package 应为软件包的官方名称(符号形式,例如 MH-E)。version 应为字符串。如果软件包 package 是作为 Emacs 的一部分发布的,那么 packageversion必须出现在 customize-package-emacs-version-alist 的值中。

作为 Emacs 一部分分发、且使用了 :package-version 关键字的软件包,必须同时更新 customize-package-emacs-version-alist 变量。

Variable: customize-package-emacs-version-alist

这个关联列表(alist)提供了 Emacs 版本 与 :package-version 关键字中记录的软件包版本之间的映射关系。其元素格式如下:

(package (pversion . eversion)...)

每个作为符号的 package,都对应一个或多个子元素,每个子元素包含一个软件包版本 pversion 以及与之关联的 Emacs 版本 eversion。这些版本均为字符串。例如,MH-E 软件包通过以下形式更新该关联列表:

(add-to-list 'customize-package-emacs-version-alist
             '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
                    ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
                    ("7.4" . "22.1") ("8.0" . "22.1")))

package 的值必须唯一,并且需要与 :package-version 关键字中的 package 值保持一致。由于用户可能在错误信息中看到该值,因此建议使用软件包的官方名称,例如 MH-E 或 Gnus。


emacs

Emacs

org-mode

Orgmode

Donations

打赏

Copyright

© 2025 Jasper Hsu

Creative Commons

Creative Commons

Attribute

Attribute

Noncommercial

Noncommercial

Share Alike

Share Alike