# @dscout/particle 中文文档

规范地址：https://npmcn.com/package/%40dscout/particle/

版本：1\.0\.0-alpha\.59
npm 元数据更新时间：2026-09-28T20:41:54.182Z
中文译文更新时间：2026-11-12T21:15:20.272Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：5.6 MB，3350 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，react-router-dom ^6\.0\.0 \|\| ^7\.0\.0
- 首次发布：2017-01-26T21:49:28.673Z
- 最新版本发布：2026-09-28T20:41:54.024Z
- 近 30 天下载量：7393（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：145（近 12 个月 14 个）

## 中文简介

用于构建 dscout 用户界面的图案库

## 安装

```sh
npm install @dscout/particle
```

也可以使用：`pnpm add @dscout/particle`、`yarn add @dscout/particle`、`bun add @dscout/particle`

## README

# 颗粒

一个用于构建dscout用户界面的CSS框架和React组件库. 访问 [文档网站](https://dscout.github.io/particle/) 学习更多.

## 使用量

使用 [线条](https://yarnpkg.com/en/docs/install) 或者说 [无](https://www.npmjs.com/)数字 :

```bash
$ yarn add @dscout/particle
$ npm install --save @dscout/particle
```

### 反应版本支持

粒子支持反应18.x和反应19.x两种应用. 在React版本之间升级时不需要更改代码. 注意颗粒是使用Resact 18.x构建的,因此使用Resact 19.x时应当铭记这一点,开发者应当如预期的那样验证组件.

```bash
# React 18 applications
yarn add @dscout/particle react@^18.0.0 react-dom@^18.0.0

# React 19 applications
yarn add @dscout/particle react@^19.0.0 react-dom@^19.0.0
```

### 同伴依赖关系

粒子要求执行应用程序安装 React(`react`, (中文(简体) ), `react-dom`)和反应路由器(`react-router-dom`) (中文(简体) ). `@floating-ui/dom` ——赋予工具提示和下放组件以权力——是粒子和自动安装的常规依赖;执行应用程序不需要添加.

### 导入

Everything is a named导出在命名空间"@dscout/project"上,例如:

```javascript
import React from 'react';
import { Container, Heading } from '@dscout/particle';

export default function Announcement() {
  return (
    <Container>
      <Heading level="2">Important!</Heading>
      <p>Make sure to eat your vegetables.</p>
    </Container>
  );
}
```

## 样式表

样式表包含两种格式: `css` 财务报告和审定财务报表 `scss`。 。 。 .

预编译样式表位于 `lib` 构建输出的目录. 要导入纯 CSS 文件 :

```css
@import 'node_modules/@dscout/particle/lib/stylesheets/particle.css';
@import 'node_modules/@dscout/particle/lib/stylesheets/particle.min.css';
```

来源 `scss` 文件位于 `styles` 目录. 你可以把它导入你自己 `scss` 类似文件 :

```scss
@import '@dscout/particle/styles/particle.scss';
```

## 与故事书一起发展

故事书为粒子组件提供了孤立的开发环境,以及作为游乐场和文献的已出版的静态站点.

### 安装依赖关系

粒子使用灰尘来管理节点依赖. 先在当地开发 安装 asdf 时:

```bash
brew install asdf
```

然后安装节点。 如果您还没有在您的机器上设置节点, 您可能首先需要安装它的依赖和 OpenPGP 密钥 :

```bash
brew install coreutils
brew install gpg
bash ~/.asdf/plugins/nodejs/bin/import-release-team-keyring
```

安装asdf 依赖性

```bash
asdf install
```

安装国家预防机制的依赖性 [线条](https://yarnpkg.com/en/docs/install)数字 :

```bash
yarn install
```

### 开始故事本

本地运行故事书 :

```bash
yarn start
```

## 脚本

为运行共同任务提供各种脚本.

使用 ESLint 并运行打字器的 Lint :

```bash
yarn lint
```

以监视模式启动 Vitest 测试跑取器 :

注:在测试前,您需要运行 `yarn playwright install` 确保本地测试跑道能够正确旋转必要的浏览器环境.

```bash
yarn test
```

## 捐款

[见维基文库](https://github.com/dscout/particle/wiki/Development-and-QA-workflow) 详细介绍如何为粒子作出贡献.

## 发布新版本

可以找到关于编写新版本并将其提交 npm 的说明 [这里](https://github.com/dscout/particle/wiki/Versioning-&-Releases)。 。 。 .

## 常见问题

### @dscout/particle 是什么？

用于构建 dscout 用户界面的图案库

### 如何安装 @dscout/particle？

在项目目录运行 npm install @dscout/particle，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、react-router-dom（^6\.0\.0 \|\| ^7\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dscout/particle 支持 TypeScript 吗？

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

### @dscout/particle 支持 ESM 还是 CommonJS？

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

### @dscout/particle 可以商用吗？

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

### @dscout/particle 的下载量有多少？

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

### @dscout/particle 还在维护吗？

最新版本 1\.0\.0-alpha\.59 发布于 2026/09/29（1 个月前）；至今共发布 145 个版本，其中过去 12 个月发布了 14 个；首次发布于 2017/01/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。