README

管理栏由两部分组成

管理栏组件是一个独立的网络组件，可以添加到任何项目的前端。
管理栏（此插件）提供插件设置、Twig 标签，并检查用户是否已登录，以确定管理栏组件是否应在页面上显示。

如果您正在创建一个具有 Twig 前端的重工 CMS 网站，您可以使用此插件及其 Twig 标签将管理栏添加到您的网站前端。

如果您正在创建一个无头网站或静态缓存的网站，您可能不需要此插件，在这种情况下，您可以直接将管理栏组件添加到您网站的 JavaScript 中（通过打包器或 <script> 标签）。

⚠️ 管理栏的 composer 包名已从 wbrowar/adminbar 更改为 wbrowar/craft-admin-bar。更新您的 composer.json 以指向 Packagist 上的新包。

要求

Craft 4.0.0

安装

要安装插件，您可以在 Craft 插件商店中找到它，或按照以下说明操作

打开您的终端并转到您的 Craft 项目
```
cd /path/to/project
```

然后告诉 Composer 需要该插件

composer require wbrowar/craft-admin-bar

在控制面板中，转到设置 → 插件，然后单击“安装”按钮安装管理栏。

将管理栏添加到您的 Twig 模板

要将管理栏添加到您的网站，请在您的 Twig 模板中添加 {{ adminBar() }} 标签。当权限可以查看 CP 的用户登录到您的网站时，管理栏将在包含此标签的任何页面上显示。

在您的插件设置中，您可以使用 CSS 自定义属性来覆盖管理栏的外观以匹配您网站的外观和感觉。

您可以通过传递参数数组来更改管理栏的外观和功能。在此示例中，您可以通过传递“编辑”链接时希望编辑的条目来传递条目。

{{ adminBar({ entry: entry }) }}

以下是可用参数的列表

向管理栏添加文本元素

可以通过将对象添加到 textElements 参数中来将纯文本和标签添加到管理栏。对象属性可以包括任何属性，如 <admin-bar-text> 元素所接受，如文档中所述。每个对象将添加一个新的文本元素，每个对象中的属性将使用 Craft 的 attr() 方法添加。

例如，这将添加一行文本，显示当前条目部分的条目数量

{{ adminBar({
    entry: entry ?? null,
    textElements: [
        { 'label-content': craft.entries.section(entry.section.handle).count(), 'text-content': 'Entries in this section' },
    ],
}) }}

配置设置

配置文件使您能够调整管理栏在多个环境中的外观和功能。它还允许您为管理栏创建附加链接，并允许通过这些附加链接调用插件操作。

要将配置文件添加到您的网站，请在 /config/admin-bar.php 创建一个返回设置数组的文件

<?php

return array(
    // Settings go here
);

以下是可以通过配置文件更改的设置

管理员栏

附加链接

您可以使用配置文件通过传递到名为 additionalLinks 的数组中的属性来向管理员栏添加链接。在 config.php 文件中有注释的示例，以下是您可以使用来创建链接的属性。

优化CSS和JS交付以提升性能

默认情况下，使用 {{ adminBar() }} 将渲染HTML，并将链接到使管理员栏工作的静态CSS和JS资源。CSS加载在 <head> 中的文件中，JavaScript加载在 <body> 标签底部的文件中——延迟加载，以避免阻塞渲染。

因为这些会增加对服务器的额外请求，您可能更愿意将CSS和JS代码移动到您的Twig模板中。首先，为了关闭默认的加载行为，向您的嵌入代码中添加 useCss 和 useJs 参数，并将它们都设置为 false

{{ adminBar({
    entry: entry ?? null,
    useCss: false,
    useJs: false,
}) }}

这会关闭向页面加载任何JavaScript或CSS。要重新加载这些资源，您可以在您的Twig模板的任何位置添加以下内容

{% css adminBarCssFile({ contents: true }) %}
{% css adminBarOnPageCss() %}
{% js adminBarJsFile({ contents: true }) %}

adminBarCssFile() 获取与 Admin Bar Component 一起提供的CSS并将其添加到页面中。
- 将 contents 参数设置为 true 将使用PHP的 file_get_contents() 方法将CSS代码作为字符串从文件中提取出来。
adminBarOnPageCss() 方法添加一些特定于管理员栏插件的CSS，以及任何在自定义CSS管理员栏插件设置中添加的CSS。
adminBarJsFile() 获取与 Admin Bar Component 一起提供的JavaScript并将其添加到页面中。
- contents 参数也使用 file_get_contents() 来获取放置在 <script> 标签内的JavaScript代码。

注意

如何嵌入静态资源由您决定。通常，减少服务器请求会更好，但在HTML标记的每个页面上添加几个额外的KB可能不如缓存和加载静态 .css 和 .js 文件那样高效。

动态加载管理员栏

使用Blitz静态缓存与管理员栏结合使用

Blitz Craft CMS插件提供一个名为 includeDynamic() 的Twig函数，允许您在静态缓存的页面上渲染Twig模板。使用此函数，管理员栏可以动态地包含到您的模板中，以便在缓存和未缓存的页面上工作。

安装Blitz后，您可以将 {{ adminBar() }} 方法从您的Twig模板中移到您的 templates 目录中的单独Twig文件。对于此示例，我们将以下代码添加到位于 /templates/includes/admin-bar.twig 的文件中。

{% set entry = entryUri ?? false ? craft.entries.uri(entryUri).one() : null %}

{{ adminBar({
  entry: entry ?? null,
  useCss: false,
  useJs: false,
}) }}

请注意，useCss 和 useJs 都设置为 false。这是因为从动态包含注册CSS和JS文件在静态缓存的页面上不会工作。您可以在这里设置任何其他您想要的 adminBar() 参数。

接下来，在您希望嵌入管理员栏的地方调用 dynamicInclude() 函数

{{ craft.blitz.includeDynamic('includes/admin-bar.twig', { entryUri: entry.uri ?? '' }) }}

{% css adminBarCssFile() %}
{% css adminBarOnPageCss() %}
{% js adminBarJsFile() with { defer: true, type: 'module' } %}

您可以将参数传递给 includeDynamic()，因此我们可以传递当前页面条目的URI——这将用于确定管理员栏将使用什么页面作为“编辑”按钮。

为了将管理员栏的CSS和JS加载到前端，我们可以在模板的任何位置使用管理员栏内置的Twig函数。

版本发布

发布说明可以在 CHANGELOG.md 中找到

支持版本

以下是关于添加和支持管理员栏未来功能的总体目标

插件的新功能将被添加到当前主插件版本，该版本针对Craft CMS的当前发布版本。
针对Craft CMS之前发布的较新主要版本的最新主要插件版本将得到支持，并包含对该版本Craft CMS更新中引入的bug修复。
之前的主要插件版本将仅获得安全相关的更新——如有必要。

由Will Browar提供

wbrowar / craft-admin-bar

维护者

详细信息