@gouvfr-lasuite/ui-kit

中文文档
0.28.1发布于 2026/07/31TypeScriptESM + CJS近 30 天下载 7218
[!][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) [
中文使用文档
文档目录59 节
  1. 目录
  2. 导言
  3. 目标
  4. 特征
  5. 技术
  6. 先决条件
  7. 安装
  8. Via Yarn(建议)
  9. 通过 npm
  10. 同伴依赖关系
  11. 快速启动
  12. 1. 导入样式
  13. 2. 配置提供者
  14. 3. 使用组件
  15. 项目结构
  16. 可用组件
  17. 布局导航( N)
  18. 表单
  19. 数据显示( D)
  20. 共享和协作
  21. 一体化
  22. 公用事业
  23. 主题
  24. 可用主题
  25. 使用主题
  26. 创建自定义主题
  27. 钩子
  28. 反应
  29. 用户名
  30. 国际化
  31. 支持的语言
  32. 更改语言
  33. 帮助添加新 PR 语言
  34. 动态添加自定义翻译
  35. 故事书文档
  36. 本地运行故事本
  37. 发展
  38. 安装依赖关系
  39. 可用的脚本
  40. 运行测试
  41. 构成部分结构
  42. 自定义
  43. 设计托肯斯
  44. CSS 变量
  45. 工具类
  46. 用法实例
  47. 以树查看和搜索的布局
  48. 共享模式
  49. 带有验证的表格
  50. 兼容性
  51. 支持的浏览器
  52. 兼容框架
  53. 无障碍
  54. 捐款
  55. 贡献进程
  56. 提交公约
  57. 释放
  58. 许可证
  59. 支助

校对:soup

npm version License: MIT React TypeScript

官方UI Kit为 法语套接字 - 建立在现代化、可访问和可定制的反应组件库上 坎宁安。 。 。 .


目录


导言

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

建于顶上 坎宁安 (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 (韩语)

安装

yarn add @gouvfr-lasuite/ui-kit

通过 npm

npm install @gouvfr-lasuite/ui-kit

同伴依赖关系

确定您安装了对等依赖 :

yarn add react react-dom

快速启动

1. 导入样式

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

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

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

2. 配置提供者

用 CunninghamProvider数字 :

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

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

3. 使用组件

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用户邀请

一体化

构成部分说明
LaGaufreLa Suite numérique 服务菜单
LaGaufreV2La Gaufre 强化版
ProConnectButtonProConnect 登录按钮

公用事业

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

主题

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

可用主题

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

使用主题

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

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

创建自定义主题

见 坎宁安文献 更多信息

钩子

反应

检测到响应性断点 :

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

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

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

用户名

覆盖默认翻译 :

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 -西班牙语

更改语言

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

帮助添加新 PR 语言

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

动态添加自定义翻译

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

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

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

故事书文档

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

本地运行故事本

yarn storybook

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


发展

安装依赖关系

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 令牌文件

运行测试

# 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 并被凌虐

// 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 变量 :

.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);
}

工具类

<!-- 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>

用法实例

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: "[email protected]" }}
            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>
  );
}

共享模式

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: "[email protected]", role: "editor" },
        ]}
        onAddMember={(user, role) => {}}
        onRemoveMember={(userId) => {}}
        onCopyLink={() => navigator.clipboard.writeText(window.location.href)}
      />
    </>
  );
}

带有验证的表格

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)

捐款

欢迎捐款! 见 捐款额 详细文件.

贡献进程

  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

释放

见 捐款额 对释放过程.


许可证

本项目根据以下规定获得许可证: MIT 许可证见 自由主义 详细文件.


支助


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

版本与发布记录

@gouvfr-lasuite/ui-kit 共发布 69 个版本,首次发布于 2025/03/10;过去 12 个月发布了 32 个版本。

版本发布日期距今
0.28.1latest2026/07/313 个月前
0.28.02026/07/283 个月前
0.27.02026/07/084 个月前
0.26.02026/07/034 个月前
0.25.02026/07/014 个月前
0.24.02026/06/294 个月前

关于 @gouvfr-lasuite/ui-kit 的常见问题

@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 和提交记录判断。