README

管理栏由两部分组成

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

如果您正在创建一个具有 Twig 前端的 Craft 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 模板

要将管理栏添加到您的网站，请将 {{ adminBar() }} 标签添加到您的 Twig 模板中。当有人（拥有查看 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代码。

注意

您嵌入静态资产的方式由您决定。通常来说，减少服务器请求会更好，但将一些额外的KB添加到HTML标记中的每一页可能不如缓存和加载静态的 .css 和 .js 文件那样高效。

动态加载管理栏

使用Blitz静态缓存与Admin Bar结合使用

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

支持的版本

以下是关于未来添加和支撑Admin Bar功能的一般目标

新功能将添加到当前主要插件版本中，该版本针对Craft CMS的当前发布版本。
针对Craft CMS先前发布的主要版本的最新主要插件版本，将通过Craft CMS该版本更新中引入的bug修复来得到支持。
先前的主要插件版本将仅获得安全相关的更新——当需要时。

由Will Browar提供

wbrowar / adminbar

维护者

详情