校对:soup
官方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 (韩语)
安装
Via Yarn(建议)
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 | 用户邀请 |
一体化
| 构成部分 | 说明 |
|---|---|
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 - 黑暗模式 |
使用主题
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)
捐款
欢迎捐款! 见 捐款额 详细文件.
贡献进程
- 叉子存储器
- 创建特性分支( E)
git checkout -b feature/my-feature(中文(简体) ) - 提交更改( 遵循承诺公约)
- 推出分支( R)
git push origin feature/my-feature(中文(简体) ) - 打开拉请求
提交公约
这个项目遵循了公约承诺:
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公司
法国政府的一项倡议