# @canonical/cookie-policy 中文文档

规范地址：https://npmcn.com/package/%40canonical/cookie-policy/

版本：4\.0\.0
npm 元数据更新时间：2026-11-03T16:22:35.643Z
中文译文更新时间：2026-11-09T01:10:06.231Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40canonical/cookie-policy
原文对照：https://npmcn.com/package/%40canonical/cookie-policy/?lang=original
项目主页：https://github.com/canonical/cookie-policy#readme
源码仓库：https://github.com/canonical/cookie-policy

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：396 kB，27 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2019-05-07T14:15:24.639Z
- 最新版本发布：2026-11-03T16:22:35.339Z
- 近 30 天下载量：21126（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 14 个）

## 中文简介

显示 cookie 策略通知的脚本和样式表

## 安装

```sh
npm install @canonical/cookie-policy
```

也可以使用：`pnpm add @canonical/cookie-policy`、`yarn add @canonical/cookie-policy`、`bun add @canonical/cookie-policy`

## README

# Canonical cookie政策组成部分

这个项目包含在网页上显示 cookie 策略通知的脚本和样式.

您可以在自己的网页上显示您选择的自定义 cookie 消息 .

## 使用量

这个工程可以通过一个 [国家防范机制一揽子计划](https://www.npmjs.com/package/cookie-policy)。 。 。 .

```bash
yarn add @canonical/cookie-policy
```

或者说...

```bash
npm install @canonical/cookie-policy
```

然后可以通过直接链接或通过ES6导入来安装库.

1.  通过直接链接

要直接使用该图书馆,请在JS文件中添加一个链接,其中包含 [IIFE (英语)](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) 并呼唤自由:

```javascript
<script src="[ INSERT YOUR LOCAL PATH ]/js/cookie-policy.js"></script>
<script>
  cpNs.cookiePolicy();
</script>
```

2.  通过ES6导入

```javascript
import { cookiePolicy } from '@canonical/cookie-policy';
```

### 字体

从4.0.0版本开始,饼干政策风格不再包括Ubuntu字体. 横幅用 `"Ubuntu variable"` 但期望页面能加载它.

-   **如果你的网站使用香草**,你已经有了: 香草的基底样式包括字体.
-   **如果您的网站主机字体本身**,没有改变: `@font-face` 规则.
-   **否则**在您网站的CSS中添加这些规则:

```css
@font-face {
  font-family: "Ubuntu variable";
  font-stretch: 100%;
  font-style: normal;
  font-weight: 100 800;
  font-display: swap;
  src: url("https://assets.ubuntu.com/v1/f1ea362b-Ubuntu%5Bwdth,wght%5D-latin-v0.896a.woff2") format("woff2");
}

@font-face {
  font-family: "Ubuntu variable";
  font-stretch: 100%;
  font-style: italic;
  font-weight: 100 800;
  font-display: swap;
  src: url("https://assets.ubuntu.com/v1/90b59210-Ubuntu-Italic%5Bwdth,wght%5D-latin-v0.896a.woff2") format("woff2");
}
```

这些都是相同的文件 香草装载。 没有他们,横幅就回到系统字体上.

### cookie 政策参数

制定饼干政策的饼干政策功能需要两个可能的参数:

1.  `callback` (default = null) - 一个回调功能,在用户选择 cookie 偏好后调用
2.  `initWithCookieService` (default = false) - 一个bool,它决定了是否尝试和我们的共享cookie服务互通

### 取消饼干政策

如果您希望用户更改他们的偏好, 您可以添加 `js-revoke-cookie-manager` 分类到文件中包含的任何内容,以召回政策主管.

```html
<button class="js-revoke-cookie-manager">Revoke cookie manager</button>
```

或者说

```html
<a href="" class="js-revoke-cookie-manager">Revoke cookie manager</a>
```

### 访问已禁用跟踪器的页面

如果您添加查询 `?cp=hide` 切换到任何 URL 的 cookie 策略将不会被执行 。 主要的用法是访问政策页面而不以模式来封锁内容.

### 回呼钩

在选择首选时,您可以使用回调设置 cookie 策略 .

```javascript
function callbackFunction() {
  alert('Calling back');
}
cpNs.cookiePolicy(callbackFunction);
```

### 共享饼干服务

若为 `initWithCookieService = true`,这触发函数的调用 `initSharedCookieService()`,并意味着饼干政策将试图从我们的饼干数据库中取回用户饼干偏好. 这需要弗拉斯克扩展 [cookie service (英语)](https://github.com/canonical/canonicalwebteam.cookie_service) 将插入项目.

若为 `initWithCookieService = false` 或没有通过,饼干政策 将只使用饼干设置在该特定网站.

共享 cookie 服务逻辑设置了以下附加 cookie :

-   `_cookies_accepted: all|performance|functional|essential|unset`:用户选择的首选.
-   `_cookies_freshness_ts: <timestamp>`:这是用来保证已经设定的饼干在1天前是新鲜的. 如果不是,它将为最新的饼干查询中央服务.
-   `_cookies_set_offline: true | null`: 如果在没有饼干时设置了饼干偏好, 则设置了此旗帜 。 下次服务上线时, cookie 首选项会被同步并去掉旗帜.

Flask 扩展设置了额外的饼干 [cookie service (英语)](https://github.com/canonical/canonicalwebteam.cookie_service)数字 :

-   `_cookies_auth_token: <encrypted_token>`:用来识别不同站点之间的用户. 中央存储为 [https://cookies.canonical.com (中文(简体) )](https://cookies.canonical.com/),作为一个会话饼干.
-   `_cookies_redirect_attempted: 1 | null`: 这是一面旗子, 用来表示重新定向到中央服务, 用于认证和初始设置 `_cookies_auth_token`,已尝试(无论是否成功)。 会议于届会结束时结束.

#### 通过 ES6 导入的完整示例

```javascript
import { cookiePolicy } from '@canonical/cookie-policy';

cookiePolicy();
```

### 饼干组

基本饼干总是允许的,除非用户在浏览器中关闭. 否则,将会有一系列价值 `_cookies_accepted` 饼干可以包含:

| Cookie 值 | 说明 | 说明 |
| --- | --- | --- |
| 全部 | 所有饼干都被用户接受. 现有部件目前使用 | 上一个数值是 `true`使用同样的饼干. |
| 关键 | 基本的饼干接受. | 用于隐藏通知而不是设置 cookie |
| 业绩 | 性能饼干接受. | \- 说吧 |
| 函数 | 功能饼干被接受. | \- 说吧 |

### API - / cookies/ set- 首选项

这个软件包将尝试 POST 用户 cookie 偏好到我们的共享 cookie 服务( cookies.canonical.com). 这是由一个 [Python 软件包](https://github.com/canonical/canonicalwebteam.cookie_service), cononical webteam.cookies service, 揭示一个内部端点"/ cookies/ set-preference", 尝试POST只能提供饼干 `_cookies_service_up=1` 已存在。 不使用上述 Python 软件包的应用程序不会试图 POST 用户偏好 .

## 捐款

如果您想帮助改进此工程, 这里列出一系列命令 帮你开始吧.

### 制定饼干政策

安装必要的依赖关系;

```
npm install
```

要将JS和CSS构建到构建文件夹中,运行:

```
npm run build
```

您可以通过运行查看动作中的构建文件 :

```
npm run serve
```

还有,访问http://0.0.0.0:8301/

### 抢劫

当开发此工程时, 您可以运行以下命令以监听 变动 `src/js/*js` 财务报告和审定财务报表 `src/sass/*scss` 文件夹并建入 `/build` 文件夹.

```
npm run watch
```

在提交拉拉请求之前,先检查一下电线 检查JS 和Sass 对于错误.

```
npm run test
```

代码许可LGPLv3 由Canonical Ltd.

和来自Canonical的..

## 常见问题

### @canonical/cookie-policy 是什么？

显示 cookie 策略通知的脚本和样式表

### 如何安装 @canonical/cookie-policy？

在项目目录运行 npm install @canonical/cookie-policy，或使用 pnpm add / yarn add / bun add。

### @canonical/cookie-policy 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/canonical\_\_cookie-policy 是否存在。

### @canonical/cookie-policy 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @canonical/cookie-policy 可以商用吗？

@canonical/cookie-policy 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @canonical/cookie-policy 的下载量有多少？

根据 npm 官方下载统计，@canonical/cookie-policy 在 2026/10/09 – 2026/11/07 这 30 天内被下载 21,126 次，日均约 704 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @canonical/cookie-policy 还在维护吗？

最新版本 4\.0\.0 发布于 2026/11/04（5 天前）；至今共发布 38 个版本，其中过去 12 个月发布了 14 个；首次发布于 2019/05/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。