# @coveo/atomic 中文文档

规范地址：https://npmcn.com/package/%40coveo/atomic/

版本：3\.65\.0
npm 元数据更新时间：2026-11-02T20:42:32.127Z
中文译文更新时间：2026-11-10T20:56:24.848Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40coveo/atomic
原文对照：https://npmcn.com/package/%40coveo/atomic/?lang=original
项目主页：https://docs.coveo.com/en/atomic/latest/
源码仓库：https://github.com/coveo/ui-kit

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

- 包体积（解压后）：9.2 MB，2548 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.9\.0 \|\| ^22\.11\.0 \|\| ^24\.11\.0
- 运行依赖：17 个
- peer 依赖：typescript \>=5\.0\.0，@coveo/bueno ^1\.1\.9，@coveo/headless ^3\.58\.1
- 首次发布：2020-07-23T13:10:10.466Z
- 最新版本发布：2026-11-02T20:42:31.777Z
- 近 30 天下载量：41246（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：4981（近 12 个月 65 个）

## 中文简介

用于构建现代 UIs 与 Coveo 平台接口的网络组件库

## 安装

```sh
npm install @coveo/atomic
```

也可以使用：`pnpm add @coveo/atomic`、`yarn add @coveo/atomic`、`bun add @coveo/atomic`

## README

[![npm version](https://badge.fury.io/js/@coveo%2Fatomic.svg)](https://badge.fury.io/js/@coveo%2Fatomic) ![Built With Stencil](https://img.shields.io/badge/-Built%20With%20Stencil-16161d.svg?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDE5LjIuMSwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCA1MTIgNTEyOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI%2BCjxzdHlsZSB0eXBlPSJ0ZXh0L2NzcyI%2BCgkuc3Qwe2ZpbGw6I0ZGRkZGRjt9Cjwvc3R5bGU%2BCjxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik00MjQuNywzNzMuOWMwLDM3LjYtNTUuMSw2OC42LTkyLjcsNjguNkgxODAuNGMtMzcuOSwwLTkyLjctMzAuNy05Mi43LTY4LjZ2LTMuNmgzMzYuOVYzNzMuOXoiLz4KPHBhdGggY2xhc3M9InN0MCIgZD0iTTQyNC43LDI5Mi4xSDE4MC40Yy0zNy42LDAtOTIuNy0zMS05Mi43LTY4LjZ2LTMuNkgzMzJjMzcuNiwwLDkyLjcsMzEsOTIuNyw2OC42VjI5Mi4xeiIvPgo8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNDI0LjcsMTQxLjdIODcuN3YtMy42YzAtMzcuNiw1NC44LTY4LjYsOTIuNy02OC42SDMzMmMzNy45LDAsOTIuNywzMC43LDkyLjcsNjguNlYxNDEuN3oiLz4KPC9zdmc%2BCg%3D%3D&colorA=16161d&style=flat-square)

# 原子

一个用于构建现代UIs与Coveo平台的网络组件库. 原子网络组件是用 [斯坦西尔](https://stenciljs.com/docs/introduction)它们是自我封装、可堆肥和轻量级的.

使用图书馆: [科沃原子图书馆正式文件](https://docs.coveo.com/en/atomic/latest/)。 。 。 .

**捐款**: 见 [捐款额](https://npmcn.com/package/%40coveo/atomic/CONTRIBUTING.md) 关于开发原子部件、进行试验和使用开发工具的准则.

## 入境点

这个 `@coveo/atomic` 软件包显示下列切入点:

-   `@coveo/atomic`:出口Coveo Atomic所使用的各种类型和公用事业.
-   `@coveo/atomic/loader`:出口科沃原子部件类型以及 `defineCustomElements` 财务报告和审定财务报表 `setNonce` 公用事业.
-   `@coveo/atomic/themes`:导出 Coveo 原子主题样本.
-   `@coveo/atomic/assets`:导出Coveo Atomic使用的SVG图标.
-   `@coveo/atomic/lang`:导出Coveo Atomic所使用的本地化文件.

## 开始

复制后,请遵守顶级指令 [读取](https://npmcn.com/package/README.md) 以安装依赖和链接软件包.

### 运行软件包脚本

虽然此软件包有软件包特定脚本,但它最好依靠运行命令 `turbo` 从一相相根起.

例如,在开发中运行软件包

```sh
# ✅ Preferred method
pnpm turbo run dev --filter=@coveo/atomic
```

从单列波根,相对于

```sh
# ❌ Deprecated method
cd package/atomic
pnpm run dev
```

在从软件包文件夹运行脚本时, 使用 `turbo` 脚本一般是一种更平滑的经验.

随后的所有例子都假设您是从单列波根操作的.

### 可用的脚本

原子使用故事书进行组件开发,文档和测试. 要在开发模式中启动故事本 :

```sh
pnpm turbo run dev --filter=@coveo/atomic
```

故事书将在 `http://localhost:4400`。 。 。 .

> \[注\] 这很重要,你建造 `@coveo/atomic` 在运行"故事本"服务器之前至少要运行一次. 这将确保所有组件都能通过Storybook正确渲染, 否则您不会看到组件被渲染 .

为了建设用于制作的图书馆,运行:

```sh
pnpm turbo run build --filter=@coveo/atomic
```

要对组件进行单元测试,请运行:

```sh
pnpm turbo run test --filter=@coveo/atomic
```

### 故事本 MCP( 模式背景协议)

这个"故事本"实例被配置为MCP addon,这使得AI代理能够与组件故事进行程序互动. 当故事本运行时, MCP 服务器可以在 `http://localhost:4400/mcp`。 。 。 .

## 公用事业

### 立体装饰器

在建造原子组件时,会使用一系列的装饰来使开发更快.

## 初始化 Bindings & BindState to Controller 装饰器

`InitializeBindings` 是一个自动获取 `bindings` 从父母那里 `atomic-search-interface` 或者说 `atomic-external` 组件。 此装饰必须应用到命名为 `bindings`。 。 。 .

_重要_ 为使使用此装饰器的组件能正确渲染,它应当有一个内部状态,约束在其中的一个属性上: `bindings`。这可以通过使用 `BindStateToController` 装饰器与一个 `State` 装饰师.

下面是一个完整的例子:

```typescript
import {
  InitializeBindings,
  InitializableComponent,
  BindStateToController,
  Bindings,
} from '@coveo/atomic';
import {ControllerState, Controller, buildController} from '@coveo/headless';
import {Component, State} from '@stencil/core';

@Component({
  tag: 'atomic-component',
})
export class AtomicComponent implements InitializableComponent {
  @InitializeBindings() public bindings!: Bindings;
  private controller!: Controller;

  // Automatically subscribes the `controllerState` to the state of the `controller`
  @BindStateToController('controller')
  @State()
  private controllerState!: ControllerState;

  // Method called after bindings are defined, where controllers should be initialized
  public initialize() {
    this.controller = buildController(this.bindings.engine);
  }

  render() {
    return [this.strings.value(), this.controllerState.value];
  }
}
```

## 结果 Context 装饰器

`ResultContext` 是一个自动获取 `result` 由母组件提供 `atomic-result`。此工具用于自定义结果模板组件内部.

```typescript
import {ResultContext} from '@coveo/atomic';
import {Component, State} from '@stencil/core';

@Component({
  tag: 'atomic-result-component',
})
export class AtomicResultComponent {
  @ResultContext() private result!: Result;

  @State() public error!: Error;

  public render() {
    return this.result.title;
  }
}
```

## 生成组件命令

要生成新的组件,请使用以下命令:

```sh
pnpm turbo generate-component --filter=@coveo/atomic -- --name=<component-name> --output=<path-to-output-directory>
```

这个 `output` 参数是可选的。 如果不提供,则默认为 `src/components/commerce`。 。 。 .

例如,生成一个命名的组件 `atomic-ball`,运行 :

```sh
pnpm turbo generate-component --filter=@coveo/atomic -- --name=ball
```

这将在默认路径下创建必要的组件文件 `src/components/commerce/atomic-ball`。 。 。 .

如果你想指定不同的路径,你可以使用 `--output` 旗帜。 例如,生成以下构成部分: `src/components/search`,运行 :

```sh
pnpm turbo generate-component --filter=@coveo/atomic -- --name=ball --output=src/components/search
```

您还可以使用 `--name=atomic-ball` 如果你愿意,但如果有必要,剧本会自动添加"原子"前缀.

这将在指定的目录中创建组件( N)`src/components/search/atomic-ball` )或使用默认值 `src/components/commerce/atomic-ball` 若无 `output` 提供.

## 常见问题

### @coveo/atomic 是什么？

用于构建现代 UIs 与 Coveo 平台接口的网络组件库

### 如何安装 @coveo/atomic？

在项目目录运行 npm install @coveo/atomic，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@coveo/bueno（^1\.1\.9）、@coveo/headless（^3\.58\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @coveo/atomic 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @coveo/atomic 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @coveo/atomic 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.9\.0 \|\| ^22\.11\.0 \|\| ^24\.11\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @coveo/atomic 可以商用吗？

@coveo/atomic 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @coveo/atomic 的下载量有多少？

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

### @coveo/atomic 还在维护吗？

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