README

此插件使您能够在Craft中自动为HTML标题添加可链接的锚点。

锚点名称基于标题文本。Anchors使用的将标题文本转换为ID的算法类似于Craft自动生成条目短语的算法。

要求

此插件需要Craft CMS 4.0.0+或5.0.0+。

安装

您可以从插件商店或使用Composer安装此插件。

从插件商店

前往项目控制面板中的插件商店，搜索“Anchors”，然后在模态窗口中点击“安装”按钮。

使用Composer

打开您的终端并运行以下命令

# go to the project directory
cd /path/to/my-project.test

# tell Composer to load the plugin
composer require craftcms/anchors

# tell Craft to install the plugin
./craft install/plugin anchors

模板

要在模板中使用Anchors，只需将一些HTML传递给|anchors过滤器。

{{ entry.body|anchors }}

默认情况下，anchors过滤器只会搜索<h1>、<h2>和<h3>标签。您可以通过传递逗号分隔的标签名称列表来自定义它搜索的标签。

{{ entry.body|anchors('h2,h3') }}

anchors过滤器将任何非ASCII字符转换为ASCII，默认情况下使用当前站点语言的ASCII字符映射。

如果您正在显示与当前站点不同语言的文本，请使用language参数覆盖应使用的ASCII字符映射

{{ entry.body|anchors(language=entry.site.language) }}

默认情况下，anchors过滤器将全部大写的单词转换为小写，并将任何其他情况中的首字母小写。

如果您想始终将锚点转换为小写，可以使用lowercase参数

{{ entry.body|anchors(lowercase=true) }}

配置

要配置Anchors，请在config/文件夹中创建一个新的anchors.php文件，它返回一个数组。

支持以下配置设置

• anchorClass – 应给予命名锚点的类名。（默认为null，表示不给予类。）
• anchorLinkPosition – 锚点链接应在标题中的位置，相对于标题文本（'before'或'after'）。（默认为'after'。）
• anchorLinkClass – 应给予锚点链接的类名。（默认为'anchor'。）
• anchorLinkText – 锚点链接应显示的可见文本。（默认为'#'。）
• anchorLinkTitleText – 锚点链接应有的标题/alt文本。如果包含{heading}，它将被替换为与链接相关联的标题文本。（默认为'Direct link to {heading}'。）
• useAdditionalTagToAnchorTo – 是否在标题上方渲染一个额外的标签并使用它来滚动到当锚点链接被点击时。如果设置为false，则锚点ID将添加到标题中。（默认为true。）

插件API

其他插件可以利用提供的API利用Anchors。

$parsedHtml = \craft\anchors\Plugin::getInstance()->parser->parseHtml($html);

与|anchors模板过滤器一样，parseHtml()还允许您指定哪些HTML标签应获得锚点。

$parsedHtml = \craft\anchors\Plugin::getInstance()->parser->parseHtml($html, 'h2,h3');

您还可以直接传递一些标题文本到Anchors以获取其生成的锚点名称

$anchorName = \craft\anchors\Plugin::getInstance()->parser->generateAnchorName($headingText);