# @datagouv/components-next 中文文档

规范地址：https://npmcn.com/package/%40datagouv/components-next/

版本：1\.5\.0
npm 元数据更新时间：2026-11-17T14:31:52.563Z
中文译文更新时间：2026-11-17T14:34:46.820Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：22.3 MB，431 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>= 20\.0\.0
- 运行依赖：41 个
- peer 依赖：vue ^3\.5\.13，echarts ^6\.0\.0，vue-router ^4\.5\.0 \|\| ^5\.0\.0
- 首次发布：2025-04-30T14:54:57.653Z
- 最新版本发布：2026-11-17T14:31:52.248Z
- 近 30 天下载量：5717（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：340（近 12 个月 302 个）

## 中文简介

在本文档中,“用户”是使用 `@datagouv/components` (例如: `cdata` 或者说 `udata-front-kit`) (中文(简体) ). 关于一般项目的设置和开发,见 [主要项目](https://npmcn.com/package/%40datagouv/README.md)。 。 。 .

## 安装

```sh
npm install @datagouv/components-next
```

也可以使用：`pnpm add @datagouv/components-next`、`yarn add @datagouv/components-next`、`bun add @datagouv/components-next`

## README

# @ datagouv/ 组件

在本文档中,“用户”是使用 `@datagouv/components` (例如: `cdata` 或者说 `udata-front-kit`) (中文(简体) ). 关于一般项目的设置和开发,见 [主要项目](https://npmcn.com/package/%40datagouv/README.md)。 。 。 .

## 使用量

### 配置

`@datagouv/components` 页:1 [阴道](https://vuejs.org/) 装入配置的插件 .

```ts
import { datagouv } from '@datagouv/components-next'

app.use(datagouv, {
    name: 'data.gouv.fr', // Name of the site in some texts
    baseUrl: 'https://www.data.gouv.fr', // Used for redirects
    apiBase: 'https://www.data.gouv.fr', // Used for API calls (could default to `baseUrl`?)
})
```

### 版式

用来使用 `Toggletip` 组件 `<div id="tooltips" />` 在您的布局中.

### 特殊功能和组件( 只用于 Nuxt)

Nuxt是一个特殊的环境(包括服务器和浏览器),需要一些特殊的功能和组件才能工作.

```ts
import { TextClamp } from '#components'
import CdataLink from './components/CdataLink.vue'
import { datagouv, type UseFetchFunction } from '@datagouv/components-next'

const runtimeConfig = useRuntimeConfig()

app.vueApp.use(datagouv, {
    // These are the same as above…
    name: runtimeConfig.public.title,
    baseUrl: runtimeConfig.public.baseUrl,
    apiBase: runtimeConfig.public.apiBase,
    devApiKey: runtimeConfig.public.devApiKey,

    // ----------------------------------------
    // --- Special functions and components ---

    // Tell `@datagouv/components` to use `useFetch` from Nuxt instead of custom built-in.
    customUseFetch: useFetch as UseFetchFunction, 

    // Nuxt doesn't like `TextClamp` in the server, provides the client only `TextClamp`
    textClamp: TextClamp,

    // The following properties allow to provide components specific to Nuxt.

    // This `appLink` component will receive the raw link (without i18n prefix)
    // and needs to add it.
    appLink: CdataLink,
    
    // The ClientOnly allow to disable SSR for some components.
    clientOnly: ClientOnly,
})
```

### 支助科

`@datagouv/components` 正在使用 [尾风CSS](https://tailwindcss.com/docs) 还有一些 [联邦](https://www.systeme-de-design.gouv.fr/) 现在 用户需要提供DSFR的正确版本. 关于TailwindCSS,有两种模式:

1.  如果用户正在使用 TailwindCSS, 它可以导入一个完整的 TailwindCSS 配置 `@import "@datagouv/components-next/assets/main.css";`,然后通过 TailwindCSS CLI 或 Vite 插件构建 CSS .
2.  如果用户没有使用TailwindCSS,它可以导入一个已经建好的CSS文件 `@import '@datagouv/components-next/dist/components.css';`。注意@dev,此文件应在将软件包发布到 PNPM 之前构建 `pnpm run css`。详细情况请参见: [技术堆栈](https://npmcn.com/package/%40datagouv/README.md#-technology-stack),参见主读取.

### I18n 时

`@datagouv/components` 正在使用一些自定义功能提供国际化:

-   `$t()` 模板内
-   `const { t } = useTranslation()` 联合来文
-   `<TranslationT keypath="xxx"></TranslationT>` 用于在文本中放置 HTML

### `Suspense`

与 [坚果](https://nuxt.com/),一些组件正在执行 HTTP 请求 `setup` 函数(Nuxt然后可以对这些请求进行SSSR:执行这些请求的服务器侧)。 这些组件需要用下列方式包裹: [`<Suspense>`](https://vuejs.org/guide/built-ins/suspense) 包装( 你可以提供 `#fallback`) (中文(简体) ). 您可以将单个组件包入内部 `<Suspense>` 或将您的整个应用程序/推出包入 `<Suspense>`

```html
<Suspense>
    <ActivityList />
</Suspense>
```

## 发展

关于一般发展准则和贡献,见本报告附件 [贡献部分](https://npmcn.com/package/%40datagouv/README.md#-contributing) 在主读取.

### 代码 Linting 和格式

此组件库同时使用ESLint和Pretier进行代码质量和格式化:

```bash
pnpm run lint    # Lint and auto-fix ESLint issues
pnpm run format  # Format code with Prettier
```

**说明:** 在提交贡献前确保运行这两个命令,以确保代码样式一致.

### 配置

您可以使用可混凝土配置 `useComponentsConfig()`。 。 。 .

```ts
import { useComponentsConfig } from '../main'

const config = useComponentsConfig()
```

### 特殊功能和组件( 只用于 Nuxt)

> \[尖叫声\]  
> 单位 `@datagouv/components` 我们无法直接使用一些功能和组件:
> 
> -   `TextClamp` 组件
> -   `useFetch` Nuxt 函数

要使用这些,需要从配置或者通过特殊的包装得到.

#### `useFetch`

```ts
import { useFetch } from '../functions/api'

const { data: allLicenses } = await useFetch<Array<License>>('/api/1/datasets/licenses/')
```

此包装将使用提供的 `useFetch` 函数来自 Nuxt 或自定义内置替换(在大多数情况下应该工作,但是一个真正简化的 Nuxt 的版本).

#### `TextClamp`

使用配置中的组件( 将来可以添加一个包装来简化) .

```ts
import { useComponentsConfig } from '../main'

const config = useComponentsConfig()
```

```html
<component
    :is="config.textClamp"
    v-if="config && config.textClamp"
    class="fr-mx-1v"
    :auto-resize="true"
    :text="organization.name"
    :max-lines="1"
/>
```

> \[注\]  
> 坚果甚至不允许装入 `vue3-text-clamp` 服务器中的库,所以我们需要在插件配置中使用动态导入,以确保它只被加载到非纳克特环境中.

#### 链接

要在应用程序中进行链接, 您可以使用 `<AppLink>` 组件。 不知道为什么需要它。 也许我们总是需要 `<RouterLink>` 从 [`vue-router`](https://router.vuejs.org/) 因为每个用户都在使用 `vue-router`\* I think it's used 在链接中添加lang前缀但还没有完成 需要测试.

也许这个组件不应该被曝光,因为我不知道为什么一个用户应该使用这个而不是他们自己的组件(英语:`<RouterLink>` 或者说 `<CdataLink>`. ) (中文(简体) )

## 释放

此软件包作为 `@datagouv/components-next` 打开 [无](https://www.npmjs.com/package/@datagouv/components-next)。 。 。 .

它跟随 [语义版本规范](https://semver.org/)。 。 。 .

为了重新发行,你必须:

1.  更新版本
2.  发布到 npm
3.  提交并按下版本更改

### 更新版本

使用专用 pnpm 命令, 并带有正确的参数 :

```
pnpm version VERSION
```

VERSION是:

-   `major` 当您进行不兼容的 API 更改时
-   `minor` 当您以向后兼容的方式添加函数时
-   `patch` 当您使反向兼容错误修正时版本 发布前和构建元数据的其他标签可作为MAJOR.MINOR.PATCH格式的扩展.

### 向国家预防机制公布

```
pnpm login
pnpm run publish-stable
```

## 许可证

此组件库根据 **MIT 许可证**,这与主要项目相同。 这允许在其他项目中随意使用部件.

详情见 [自由主义](https://npmcn.com/package/%40datagouv/LICENSE) 文件在主工程目录中.

## 常见问题

### @datagouv/components-next 是什么？

在本文档中,“用户”是使用 @datagouv/components \(例如: cdata 或者说 udata-front-kit\) \(中文\(简体\) \)\. 关于一般项目的设置和开发,见 主要项目。 。 。 \.

### 如何安装 @datagouv/components-next？

在项目目录运行 npm install @datagouv/components-next，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.5\.13）、echarts（^6\.0\.0）、vue-router（^4\.5\.0 \|\| ^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @datagouv/components-next 支持 TypeScript 吗？

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

### @datagouv/components-next 支持 ESM 还是 CommonJS？

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

### @datagouv/components-next 需要什么版本的 Node\.js？

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

### @datagouv/components-next 可以商用吗？

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

### @datagouv/components-next 的下载量有多少？

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

### @datagouv/components-next 还在维护吗？

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

