README

轻松管理Statamic项目中的Cookie偏好设置。

功能

此插件提供可定制的Cookie对话框，允许用户根据您定义的Cookie组和单个Cookie接受或拒绝Cookie。另一方面，您可以根据用户的Cookie偏好动态显示或阻止内容。

✅ 可定制的Cookie对话框内容
✅ 可定制的Cookie组和Cookie
✅ 标签用于根据Cookie偏好动态渲染内容
✅ 标签用于在拒绝给定Cookie时渲染备用内容
✅ Cookie版本管理
✅ JavaScript API
✅ 多站点支持

注意

此插件不保证符合GDPR法规。请咨询法律专家以确保您的网站符合适用的数据保护法。

🛠️ 安装方法

您可以在Statamic控制面板的“工具 > 插件”部分搜索此插件并点击“安装”，或者从项目根目录运行以下命令

composer require emplify-software/statamic-cookie-dialog

插件安装后，通过运行以下命令发布Cookie资产

php artisan vendor:publish --tag=statamic-cookie-dialog

⭐️ 专业版

您可以在Statamic市场购买此插件的专用版。

购买专业版后，通过将项目config/statamic/editions.php文件中插件的版本设置为'pro'来启用它

    'addons' => [
        'emplify-software/statamic-cookie-dialog' => 'pro'
    ],

启用专业版后，将移除Attribution链接到emplify software GmbH。

💡 使用方法

要为所有页面启用Cookie对话框，请将以下标记放置在您的layout.antlers.html文件中的任何位置

{{ cookie_dialog }}

注意

如果您已启用静态缓存，请确保将{{ cookie_dialog }}、{{ cookie:allowed }}和{{ cookie:denied }}标签包裹在{{ nocache }}标签中，以防止Cookie对话框被缓存

{{ nocache }}
   {{ cookie_dialog }}
{{ /nocache }}

这将在用户接受或拒绝Cookie时显示弹出对话框。默认提供描述文本和示例Cookie组。

您可以在控制面板工具 > Cookie对话框下完全控制对话框内容和所有Cookie设置。

在“Cookie”选项卡中，您可以选择启用或禁用Cookie对话框，设置Cookie版本，创建或编辑Cookie组。Cookie组具有唯一的标识符、名称和描述，并可以标记为必需，默认情况下可以勾选。每个Cookie组可以包含多个具有名称、描述和生命周期的Cookie。

在“内容”选项卡中，您可以自定义Cookie对话框的内容，包括标题、描述、按钮和切换按钮的高亮颜色。

根据Cookie偏好启用内容

您可以将内容包裹在{{ cookie:allowed }}标签中，以便仅在用户接受特定Cookie或Cookie组时显示。

{{ cookie:allowed cookies="marketingCookieA|marketingCookieB" }}
    <p>
        This content will only be shown if the user has accepted
        the cookies marketingCookieA and marketingCookieB
    </p>
{{ /cookie:allowed }}

您还可以根据一个或多个Cookie组允许内容

{{ cookie:allowed group="marketing" }}
    <p>
        This content will only be shown if the user has accepted 
        the cookie group "marketing"
    </p>
{{ /cookie:allowed }}

{{ cookie:allowed group="marketing|statistics" }}
    <p>
        This content will only be shown if the user has accepted
        the cookie groups "marketing" and "statistics"
    </p>
{{ /cookie:allowed }}

一旦用户接受Cookie，内容将动态加载，无需重新加载页面。

这适用于所有类型的内容，包括图像、样式表和脚本

{{ cookie:allowed cookies="marketingCookieA|marketingCookieB" }}
    <script src="https://example.com/marketing-script.js"></script>
{{ /cookie:allowed }}

如果尚未接受Cookie，则启用备用内容

您可以使用{{ cookie:denied }}标签包裹内容，仅当用户未接受特定的cookie组或单个cookie时显示。默认情况下，这些内容将显示，直到用户接受必要的cookie。

您可以通过与{{ cookie:allowed }}标签相同的方式，根据cookie或组进行筛选。

{{ cookie:denied cookies="marketingCookieA|marketingCookieB" }}
    <p>
        Please enable the cookies marketingCookieA
        and marketingCookieB to see this content
    </p>
{{ /cookie:denied }}

{{ cookie:allowed cookies="marketingCookieA|marketingCookieB" }}
    <p>
        This content will only be shown if the user has accepted
        the cookies marketingCookieA and marketingCookieB
    </p>
{{ /cookie:allowed }}

当用户接受cookie后，{{ cookie:denied }}标签内的内容将动态删除。

重要

当使用{{ cookie:allowed }}和{{ cookie:denied }}标签或JavaScript API时，只有当用户接受组中所有cookie时，才认为cookie组是允许的。

这不同于cookie对话框中的切换开关：当组中任何一个cookie切换被选中时，组切换会自动激活，向用户表明他们已接受该组的cookie，但只有在组中所有cookie都被接受后，组才被视为允许。

在特定页面上隐藏cookie对话框

当您在layout.antlers.html文件中放入{{ cookie_dialog }}标签时，对话框将默认显示在所有页面上。要隐藏特定页面上的cookie对话框（例如隐私政策页面），您可以设置hidden参数，根据页面的URL或其他条件。

{{ cookie_dialog :hidden="current_uri == '/privacy-policy'" }}

通过使用hidden参数，您仍然可以使用JavaScript API在页面上稍后显示cookie对话框。如果要在某些页面上完全禁用cookie对话框，您可以将{{ cookie_dialog }}标签包裹在条件语句中。

{{ if current_uri != '/privacy-policy' }}
    {{ cookie_dialog }}
{{ /if }}

遍历cookie组和cookie

您可以使用{{ cookie_groups }}标签遍历cookie配置中的所有cookie组和cookie。如果您想显示包含网站上使用的所有cookie信息（例如在专门的隐私政策页面上）的表格，这将非常有用。

<table>

  <thead>
    <tr>
      <th>Name</th>
      <th>Description</th>
      <th>Lifetime</th>
    </tr>
  </thead>

  <tbody>
    {{ cookie_groups }}
      {{ cookies }}
        <tr>
          <td>{{ cookie_identifier }}</td>
          <td>{{ cookie_description }}</td>
          <td>{{ cookie_lifetime }}</td>
        </tr>
      {{ /cookies }}
    {{ /cookie_groups }}
  </tbody>

</table>

暗色/亮色模式

默认情况下，cookie对话框将根据用户的操作系统设置自动显示为暗色或亮色模式。如果您不想使用自动模式，您可以在工具 > cookie对话框 > 内容 > 暗色/亮色模式控制面板中选择特定的颜色模式。

要动态地在暗色和亮色模式之间切换，您还可以使用JavaScript在网站的<html>标签中添加或删除es-dark类。

document.documentElement.classList.add('es-dark'); // Enable dark mode
document.documentElement.classList.remove('es-dark'); // Enable light mode

🧩 JavaScript API

此插件还提供了一个JavaScript API，允许您与cookie对话框和cookie首选项进行交互。

当页面上存在{{ cookie_dialog }}标签时，JavaScript API通过全局CookieDialog对象可访问。

手动触发cookie对话框

您可以使用JavaScript通过调用以下全局函数手动触发cookie对话框：

CookieDialog.showDialog()

这将打开一个非阻塞对话框，用户可以选择更改他们的cookie首选项。默认情况下，在用户保存他们的新cookie首选项后，页面将重新加载以应用更改到{{ cookie:allowed }}或{{ cookie:denied }}标签中的内容。如果用户在没有保存的情况下关闭对话框，如果没有更改cookie首选项，或者内容可以动态注入而不需要页面重新加载，则页面不会重新加载。

您可以显式覆盖此默认重新加载行为。

要防止页面重新加载，请将false作为参数传递。
当cookie偏好设置更改时强制重新加载页面，请将参数传递为true

CookieDialog.showDialog(false) // Prevent page reload after saving cookie preferences

我们建议在您的网站上放置一个按钮或链接，允许用户随时更改他们的cookie偏好设置。这可以通过按钮点击时调用CookieDialog.showDialog()来实现

<button onclick="CookieDialog.showDialog()">Change Cookie Preferences</button>

访问cookie偏好设置

您可以通过CookieDialog.cookiePreferences访问用户存储在浏览器cookie中的cookie偏好设置。此对象包含版本、时间戳以及按cookie组分组的所有接受到的cookie，例如：

{
    "version": "1",
    "timestamp": 1724072915147,
    "cookies": {
        "marketing": {
            "marketingCookieA": true,
            "marketingCookieB": true
        },
        "statistics": {
            "statisticsCookieA": true,
            "statisticsCookieB": false
        }
    }
}

cookie偏好设置对象符合以下TypeScript接口

interface CookiePreferences {
    version: string;
    timestamp: number;
    cookies: {
        [cookieGroup: string]: {
            [cookieName: string]: boolean;
        };
    };
}

您还可以通过CookieDialog.allowedCookies（string[]）获取所有当前接受到的cookie列表，以及通过CookieDialog.allowedGroups（string[]）获取所有当前接受到的cookie组列表。

🔢 Cookie版本

您可以在cookie设置中设置cookie版本（在工具 > Cookie对话框下）。此版本将存储在访客的浏览器cookie中，并将与cookie设置中的当前版本进行比较。当版本更新时，即使用户已经接受cookie，cookie对话框也将再次显示给所有用户。

🔐 访问控制（权限）

如果您只想允许某些用户访问控制面板中的cookie对话框设置，请确保为用户的角色设置了管理cookie对话框权限。您也可以在控制面板的“权限”部分管理此权限。

🌐 翻译

您可以通过在Statamic项目的resources/lang目录中创建一个新的语言文件来自定义cookie对话框的翻译。语言文件的命名应为[lang].json，其中[lang]是翻译的语言代码（例如，英语的en或德语的de）。

在翻译文件中，您可以定义默认英语文本到您希望的语言的映射（有关更多信息，请参阅https://laravel.net.cn/docs/11.x/localization#using-translation-strings-as-keys）。

📄 许可证

您可以在许可协议的条款和条件下免费使用此插件。为了给您一个简短的概述，以下是主要点：

✅ 您可以

在您的网站或为客户的网站（无论是非商业用途还是商业用途）上使用软件
修改软件供您自己使用或用于为客户的网站

❌ 您不能

在没有明确许可的情况下删除或模糊所需的对emplify software GmbH的归属链接
以任何形式重新分发软件，无论是修改过的还是未修改过的，给任何第三方

当您购买此插件的专业版时，cookie对话框中自动移除对emplify software GmbH的归属链接。

🛟 支持

此插件由emplify software积极维护和支持。如果您遇到任何问题，请随时在GitHub仓库上打开一个问题。

emplify-software / statamic-cookie-dialog

维护者

详细信息