# @gouvfr-lasuite/ui-kit 中文文档

规范地址：https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/

版本：0\.28\.1
npm 元数据更新时间：2026-07-31T10:32:38.426Z
中文译文更新时间：2026-11-17T03:46:51.009Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40gouvfr-lasuite/ui-kit
原文对照：https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/?lang=original

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

- 包体积（解压后）：36.6 MB，78 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：17 个
- peer 依赖：@tanstack/react-query ^5，react ^19\.1\.2，react-dom ^19\.1\.2
- 首次发布：2025-03-10T13:35:17.220Z
- 最新版本发布：2026-07-31T10:32:38.223Z
- 近 30 天下载量：7218（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：69（近 12 个月 32 个）

## 中文简介

\[!\]\[npm版本\](https://img.shields.io/npm/v/@gouvfr-lasuite/ui-kit.svg)\](https://www.npmjs.com/package/@gouvfr-lassuite/ui-kit) \[! \[利肯塞:MIT\](https://img.shields.io/badge/License-MIT-blue.svg)\](./LICENSE) \[

## 安装

```sh
npm install @gouvfr-lasuite/ui-kit
```

也可以使用：`pnpm add @gouvfr-lasuite/ui-kit`、`yarn add @gouvfr-lasuite/ui-kit`、`bun add @gouvfr-lasuite/ui-kit`

## README

# 校对:soup

[![npm version](https://img.shields.io/npm/v/@gouvfr-lasuite/ui-kit.svg)](https://www.npmjs.com/package/@gouvfr-lasuite/ui-kit) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/LICENSE) [![React](https://img.shields.io/badge/React-19.x-61DAFB?logo=react)](https://react.dev/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript)](https://www.typescriptlang.org/)

> 官方UI Kit为 **法语套接字** - 建立在现代化、可访问和可定制的反应组件库上 [坎宁安](https://github.com/openfun/cunningham)。 。 。 .

* * *

## 目录

-   [导言](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-introduction)
-   [特征](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-features)
-   [技术](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-technologies)
-   [先决条件](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-prerequisites)
-   [安装](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-installation)
-   [快速启动](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-quick-start)
-   [项目结构](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-project-structure)
-   [可用组件](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-available-components)
-   [主题](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-themes)
-   [钩子](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-hooks)
-   [国际化](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-internationalization)
-   [故事书文档](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-storybook-documentation)
-   [发展](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-development)
-   [自定义](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-customization)
-   [用法实例](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-usage-examples)
-   [兼容性](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-compatibility)
-   [捐款](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-contributing)
-   [许可证](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-license)

* * *

## 导言

`@gouvfr-lasuite/ui-kit` 是用于 **法语套接字**法国政府的合作工具生态系统 该图书馆提供一套符合政府设计标准的一致的可重复使用,可访问的React组件.

建于顶上 [坎宁安](https://github.com/openfun/cunningham) (v4),此套件扩展了设计系统能力,其组件是针对La Suite numérique需要的.

### 目标

-   **视觉一致性**:确保所有La Suite Numérique产品的用户经验一致
-   **无障碍**: 遵守关于最大无障碍度的《世界建筑学咨询小组》和《建筑工程法》标准
-   **业绩**: 优化和可树摇动组件
-   **灵活性**: 支持多个主题(DSFR, ANCT, 白标签)
-   **方便开发者**: 原生类型Script,综合文档,易集成

* * *

## 特征

-   **25+ 组件** 准备使用
-   **多个主题**:DSFR,ANCT,白标签(浅/暗)
-   **无障碍**:键盘导航,屏幕阅读器,ARIA
-   **国际化**: 法语和英语支持
-   **响应**: 有专用钩子的可适应组件
-   **布局**: 带有可调整面板的页面布局系统
-   **拉高夫尔一体化**: 拉苏姆-努梅克服务一体化构成部分
-   **类型脚本**: 为更好的 DX 进行完整的打字
-   **设计符号**:可定制的CSS/SCSS/TS代号系统

* * *

## 技术

| 技术 | 版本 | 使用量 |
| --- | --- | --- |
| 反应 | 19.x (中文(简体) ) | UI 框架 |
| 类型脚本 | 5.6 国家 | 静态打字 |
| 维特 | 6.x (单位:千美元) | Bundler / Dev 服务器 |
| 坎宁安 | 4.1 国家 | 基础设计系统 |
| 故事书 | 第8.5条 | 文档/ 游戏场 |
| 萨斯 | 1.83 (中文(简体) ) | CSS 预处理器 |
| 维特 | 2.1 国家 | 单位测试 |
| 反应-辅助成分 | 1.8 (中文(简体) ) | 可访问原始 |
| 反应-可逆小板 | 2.1 国家 | 可调整面板 |
| 日记 | 第6.3条 | 拖放 |

* * *

## 先决条件

-   **节点.js**页:1
-   **软件包管理器**: 纱线( 建议) 或 npm
-   **反应**: 19.x (韩语)

* * *

## 安装

### Via Yarn(建议)

```bash
yarn add @gouvfr-lasuite/ui-kit
```

### 通过 npm

```bash
npm install @gouvfr-lasuite/ui-kit
```

### 同伴依赖关系

确定您安装了对等依赖 :

```bash
yarn add react react-dom
```

* * *

## 快速启动

### 1\. 导入样式

在你的条目文件中(例如, `main.tsx` 或者说 `App.tsx`:

```tsx
// UI Kit styles (includes Cunningham)
import "@gouvfr-lasuite/ui-kit/style";

// Optional: Marianne font
import "@gouvfr-lasuite/ui-kit/fonts/Marianne";
```

### 2\. 配置提供者

用 `CunninghamProvider`数字 :

```tsx
import { CunninghamProvider } from "@gouvfr-lasuite/ui-kit";

function App() {
  return (
    <CunninghamProvider>
      <YourApp />
    </CunninghamProvider>
  );
}
```

### 3\. 使用组件

```tsx
import { MainLayout, QuickSearch, TreeView } from "@gouvfr-lasuite/ui-kit";

function MyPage() {
  return (
    <MainLayout
      leftPanelContent={<TreeView data={treeData} />}
    >
      <QuickSearch placeholder="Search..." />
      {/* Your content */}
    </MainLayout>
  );
}
```

* * *

## 项目结构

```
ui-kit/
├── src/
│   ├── components/           # React components
│   │   ├── badge/           # Badge
│   │   ├── button/          # Buttons (ProConnect)
│   │   ├── datagrid/        # Data grid
│   │   ├── dnd/             # Drag and Drop
│   │   ├── dropdown-menu/   # Dropdown menu
│   │   ├── filter/          # Filters
│   │   ├── footer/          # Footer
│   │   ├── form/            # Form fields
│   │   ├── hero/            # Hero section
│   │   ├── icon/            # Icons
│   │   ├── la-gaufre/       # La Suite integration
│   │   ├── language/        # Language selector
│   │   ├── layout/          # Layouts and panels
│   │   ├── loader/          # Loading indicators
│   │   ├── modal/           # Modals
│   │   ├── Provider/        # Cunningham Provider
│   │   ├── quick-search/    # Quick search
│   │   ├── separator/       # Separators
│   │   ├── share/           # Sharing and permissions
│   │   ├── tabs/            # Tabs
│   │   ├── tooltip/         # Tooltips
│   │   ├── tree-view/       # Tree view
│   │   └── users/           # User avatars and menus
│   ├── hooks/               # Custom React hooks
│   ├── locales/             # Translation files
│   ├── styles/              # Global styles and variables
│   ├── assets/              # Resources (fonts, images)
│   └── utils/               # Utilities
├── .storybook/              # Storybook configuration
├── cunningham.ts            # Design tokens configuration
└── dist/                    # Production build
```

* * *

## 可用组件

### 布局导航( N)

| 构成部分 | 说明 |
| --- | --- |
| `MainLayout` | 主布局,有页眉和可调整面板 |
| `Header` | 应用程序页眉 |
| `LeftPanel` | 左侧面板(导航) |
| `RightPanel` | 右侧面板(细节) |
| `Footer` | 官方页脚 |
| `Tabs` | 标签导航 |
| `DropdownMenu` | 背景下拉菜单 |

### 表单

| 构成部分 | 说明 |
| --- | --- |
| `Input` | 文本输入字段 |
| `Textarea` | 多行文本区域 |
| `Select` | 选择列表 |
| `Checkbox` | 复选框 |
| `Radio` | 无线电按钮 |
| `Switch` | 切换切换 |
| `Label` | 字段标签 |

### 数据显示( D)

| 构成部分 | 说明 |
| --- | --- |
| `TreeView` | 与 pagination 交互树视图 |
| `Datagrid` | 数据网格 |
| `QuickSearch` | 快速搜索栏 (cmd+k) |
| `Badge` | 状态徽章 |
| `Icon` | 材料图标 |
| `Loader` | 装入指标 |
| `Tooltip` | 工具提示 |

### 共享和协作

| 构成部分 | 说明 |
| --- | --- |
| `ShareModal` | 与访问管理共享模式 |
| `UserAvatar` | 用户外观 |
| `UserMenu` | 登录的用户菜单 |
| `UsersInvitation` | 用户邀请 |

### 一体化

| 构成部分 | 说明 |
| --- | --- |
| `LaGaufre` | La Suite numérique 服务菜单 |
| `LaGaufreV2` | La Gaufre 强化版 |
| `ProConnectButton` | ProConnect 登录按钮 |

### 公用事业

| 构成部分 | 说明 |
| --- | --- |
| `Modal` | 通用模式 |
| `Separator` | 视觉分隔符 |
| `Hero` | 英雄区 |
| `Filter` | 过滤组件 |
| `LanguageSelector` | 语言选择器 |

* * *

## 主题

UI Kit 支持多个预定义的主题 :

### 可用主题

| 主题 | 说明 |
| --- | --- |
| `default` | 白色标签 - 轻型模式 |
| `dark` | 白色标签 - 黑暗模式 |
| `dsfr-light` | 法国国家设计系统 - 轻型模式 |
| `dsfr-dark` | 法国国家设计系统 - 黑暗模式 |
| `anct-light` | ANCT - 灯光模式 |
| `anct-dark` | ANCT - 黑暗模式 |

### 使用主题

```tsx
import { CunninghamProvider, cunninghamConfig } from "@gouvfr-lasuite/ui-kit";

// Use a predefined theme
<CunninghamProvider theme="dsfr-light">
  <App />
</CunninghamProvider>
```

### 创建自定义主题

见 [坎宁安文献](https://suitenumerique.github.io/cunningham/storybook/?path=/docs/getting-started-customization--docs) 更多信息

## 钩子

### 反应

检测到响应性断点 :

```tsx
import { useResponsive } from "@gouvfr-lasuite/ui-kit";

function MyComponent() {
  const { isMobile, isTablet, isDesktop } = useResponsive();

  return isDesktop ? <DesktopView /> : <MobileView />;
}
```

### 用户名

覆盖默认翻译 :

```tsx
import { useCustomTranslations } from "@gouvfr-lasuite/ui-kit";

// In your Provider
const customTranslations = {
  "en-US": {
    components: {
      share: {
        modalTitle: "Share this document",
      },
    },
  },
};
```

* * *

## 国际化

UI Kit本土支持法语,英语,荷兰语,德语和西班牙语.

### 支持的语言

-   `fr-FR` - 法语( 默认)
-   `en-US` - 英语
-   `nl-NL` - 荷兰语
-   `de-DE` - 德语
-   `es-ES` -西班牙语

### 更改语言

```tsx
<CunninghamProvider currentLanguage="en-US">
  <App />
</CunninghamProvider>
```

### 帮助添加新 PR 语言

-   在 `src/locales`
-   添加全部翻译
-   创建 PR

### 动态添加自定义翻译

```tsx
import { locales } from "@gouvfr-lasuite/ui-kit";

const customLocales = {
  ...locales,
  "de-DE": {
    components: {
      share: {
        modalTitle: "Teilen",
        // ...
      },
    },
  },
};

<CunninghamProvider customLocales={customLocales}>
  <App />
</CunninghamProvider>
```

* * *

## 故事书文档

交互式文件可通过故事书查阅.

### 本地运行故事本

```bash
yarn storybook
```

然后进入 [http://localhost:6006 (英语)](http://localhost:6006/)

* * *

## 发展

### 安装依赖关系

```bash
yarn install
```

### 可用的脚本

| 脚本 | 说明 |
| --- | --- |
| `yarn dev` | 启动 Vite 开发服务器 |
| `yarn build` | 建立用于制作的图书馆 |
| `yarn lint` | 使用 ESLint 检查代码 |
| `yarn test` | 用 Vitest 进行测试 |
| `yarn storybook` | 开始故事手册(6006港) |
| `yarn build-storybook` | 构建用于部署的故事本 |
| `yarn build-theme` | 生成 CSS/SCSS/TS 令牌文件 |

### 运行测试

```bash
# Tests in watch mode
yarn test

# Tests with coverage
yarn test --coverage
```

### 构成部分结构

```
src/components/my-component/
├── index.tsx           # Main export
├── index.scss          # Component styles
├── MyComponent.tsx     # React component
├── types.ts            # TypeScript types
└── my-component.stories.tsx  # Storybook stories
```

* * *

## 自定义

### 设计托肯斯

设计符号定义于 `cunningham.ts` 并被凌虐

```tsx
// Available tokens
{
  globals: {
    font: { sizes, weights, families },
    spacings: { xs, sm, md, lg, xl, ... },
    colors: { brand-*, gray-*, info-*, success-*, warning-*, error-* },
    breakpoints: { xxs, xs, mobile, tablet },
  },
  contextuals: {
    background: {
        semantic: {
            brand: {
                primary: '..'
            }
        }
    }
  }
 
}
```

### CSS 变量

托肯被曝光为 CSS 变量 :

```css
.my-custom-element {
  color: var(--c--globals--colors--brand-500);
  padding: var(--c--globals--spacings--md);
  font-size: var(--c--globals--font--sizes--lg);
  background: var(--c--contextuals--background--semantic--brand--primary);
}
```

### 工具类

```html
<!-- Colors -->
<div class="clr-green-500">Primary text</div>
<div class="bg-success-500">Secondary background</div>

<!-- Spacing -->
<div class="p-md">Medium padding</div>
<div class="m-lg">Large margin</div>
```

* * *

## 用法实例

### 以树查看和搜索的布局

```tsx
import {
  CunninghamProvider,
  MainLayout,
  TreeView,
  QuickSearch,
  UserMenu,
} from "@gouvfr-lasuite/ui-kit";
import "@gouvfr-lasuite/ui-kit/style";

const treeData = [
  {
    id: "1",
    name: "Documents",
    children: [
      { id: "1-1", name: "Report.pdf" },
      { id: "1-2", name: "Notes.md" },
    ],
  },
];

function App() {
  return (
    <CunninghamProvider>
      <MainLayout
        icon={<Logo />}
        leftPanelContent={
          <TreeView
            data={treeData}
            onSelect={(node) => console.log(node)}
          />
        }
        rightHeaderContent={
          <UserMenu
            user={{ name: "John Doe", email: "john@example.com" }}
            onLogout={() => {}}
          />
        }
      >
        <QuickSearch
          onSearch={(query) => console.log(query)}
          groups={[
            {
              title: "Recent documents",
              items: [
                { id: "1", label: "Q4 Report" },
                { id: "2", label: "Budget 2024" },
              ],
            },
          ]}
        />
        <main>Main content</main>
      </MainLayout>
    </CunninghamProvider>
  );
}
```

### 共享模式

```tsx
import { ShareModal } from "@gouvfr-lasuite/ui-kit";

function ShareButton() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Share</button>
      <ShareModal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        members={[
          { id: "1", name: "Marie", email: "marie@example.com", role: "editor" },
        ]}
        onAddMember={(user, role) => {}}
        onRemoveMember={(userId) => {}}
        onCopyLink={() => navigator.clipboard.writeText(window.location.href)}
      />
    </>
  );
}
```

### 带有验证的表格

```tsx
import { Input, Select, Switch, Label } from "@gouvfr-lasuite/ui-kit";

function ContactForm() {
  return (
    <form>
      <div>
        <Label htmlFor="name">Name</Label>
        <Input id="name" placeholder="Your name" required />
      </div>

      <div>
        <Label htmlFor="department">Department</Label>
        <Select
          id="department"
          options={[
            { value: "hr", label: "Human Resources" },
            { value: "tech", label: "Technology" },
            { value: "admin", label: "Administration" },
          ]}
        />
      </div>

      <div>
        <Switch id="newsletter" />
        <Label htmlFor="newsletter">Subscribe to newsletter</Label>
      </div>
    </form>
  );
}
```

* * *

## 兼容性

### 支持的浏览器

| 浏览器 | 版本 |
| --- | --- |
| 颜色 | 最后两个版本 |
| 火花 | 最后两个版本 |
| 萨法里 | 最后两个版本 |
| 边缘 | 最后两个版本 |

### 兼容框架

-   **反应**: 19.x(同类依赖)
-   **下一个.js**: 14+(有适当的配置)
-   **重混合**: 兼容性
-   **维特**: 优化

### 无障碍

-   WCAG 2.1 符合AA级要求
-   RGAA 4.1 达标
-   全键盘导航
-   屏幕阅读器支持(NVDA、Voice Over、JAWS)

* * *

## 捐款

欢迎捐款! 见 [捐款额](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/CONTRIBUTING.md) 详细文件.

### 贡献进程

1.  叉子存储器
2.  创建特性分支( E)`git checkout -b feature/my-feature`(中文(简体) )
3.  提交更改( 遵循承诺公约)
4.  推出分支( R)`git push origin feature/my-feature`(中文(简体) )
5.  打开拉请求

### 提交公约

这个项目遵循了公约承诺:

```
type(scope): description

# Examples
feat(tree-view): add pagination support
fix(modal): resolve focus trap issue
docs(readme): update installation section
```

### 释放

见 [捐款额](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/CONTRIBUTING.md) 对释放过程.

* * *

## 许可证

本项目根据以下规定获得许可证: **MIT 许可证**见 [自由主义](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/LICENSE) 详细文件.

* * *

## 支助

-   **问题**数字 : [GitHub 问题](https://github.com/suitenumerique/ui-kit/issues)
-   **文档**数字 : [故事书](https://npmcn.com/package/%40gouvfr-lasuite/ui-kit/#readme-storybook-documentation)
-   **坎宁安**数字 : [坎宁安文档](https://github.com/openfun/cunningham)

* * *

**照顾La Suite numérique公司**  
法国政府的一项倡议

## 常见问题

### @gouvfr-lasuite/ui-kit 是什么？

\[\!\]\[npm版本\]\(https://img\.shields\.io/npm/v/@gouvfr-lasuite/ui-kit\.svg\)\]\(https://www\.npmjs\.com/package/@gouvfr-lassuite/ui-kit\) \[\! \[利肯塞:MIT\]\(https://img\.shields\.io/badge/License-MIT-blue\.svg\)\]\(\./LICENSE\) \[

### 如何安装 @gouvfr-lasuite/ui-kit？

在项目目录运行 npm install @gouvfr-lasuite/ui-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@tanstack/react-query（^5）、react（^19\.1\.2）、react-dom（^19\.1\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gouvfr-lasuite/ui-kit 支持 TypeScript 吗？

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

### @gouvfr-lasuite/ui-kit 支持 ESM 还是 CommonJS？

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

### @gouvfr-lasuite/ui-kit 可以商用吗？

@gouvfr-lasuite/ui-kit 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @gouvfr-lasuite/ui-kit 的下载量有多少？

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

### @gouvfr-lasuite/ui-kit 还在维护吗？

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

