# @dbcdk/react-components 中文文档

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

版本：0\.0\.240
npm 元数据更新时间：2026-11-11T16:59:21.670Z
中文译文更新时间：2026-11-11T16:54:26.331Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40dbcdk/react-components
原文对照：https://npmcn.com/package/%40dbcdk/react-components/?lang=original

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

- 包体积（解压后）：2.3 MB，728 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.17
- 运行依赖：0 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，markdown-it ^15\.0\.3，lucide-react \>=0\.543\.0 \<2，@tanstack/react-table ^8\.21\.3，@tanstack/react-virtual ^3\.14\.13
- 首次发布：2025-09-04T04:49:03.203Z
- 最新版本发布：2026-11-11T16:59:21.486Z
- 近 30 天下载量：7748（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：237（近 12 个月 233 个）

## 中文简介

DBC 项目的再使用组件

## 安装

```sh
npm install @dbcdk/react-components
```

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

## README

# DBC 反应组件

DBC项目中可再使用的再使用组件.

这个库提供了一个共享的,可主题的组件系统,用于整个DBC的内部(和选定的外部)应用程序. 其目的是促进一致性,加快发展,提高整体质量和无障碍性.

* * *

## 图书馆的目的

本组成部分图书馆的目标是:

-   **一致性**  
    对DBC的数字产品,特别是内部工具,提供统一的外观和感觉.
    
-   **开发速度**  
    通过重新使用经过良好检验的部件来减少开发和维护时间,而不是从零开始重建UI.
    
-   **质量和可获取性**  
    组成部分根据最佳做法进行审查和建设,同时考虑到无障碍性和稳健性,确保良好的基线质量.
    
-   **减少第三方依赖性**  
    通过在整个组织建立和共享我们自己的组成部分,减少对外部国家预防机制一揽子计划的依赖,增加数字独立性.
    

* * *

## 开始

### (1) 安装软件包

```bash
npm install @dbcdk/react-components
```

* * *

### (2) 导入全局样式

> **重要内容:** 组件库需要全局样式在您的应用程序中导入一次 .

```ts
import '@dbcdk/react-components/themes/dbc.css'
```

* * *

### (3) 添加 `ThemeScript` 在根布局中( 下一步. js 示例)

图书馆共享的 CSS 基础仍然正常导入, 但是 产品主题切换由 `ThemeScript` + 键 `useTheme()`。 。 。 . `ThemeScript` 恢复持续颜色方案和产品主题 颜料,因此该应用程序避免了第一个负载上错误主题的闪光.

```tsx
import { ReactNode } from 'react'

import { ThemeScript } from '@dbcdk/react-components'
import { TooltipProvider } from '@dbcdk/react-components/client'
import '@dbcdk/react-components/themes/dbc.css'

export default function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html lang="da" suppressHydrationWarning>
      <head>
        <ThemeScript defaultTheme="dbc" />
      </head>
      <body>
        <TooltipProvider>{children}</TooltipProvider>
      </body>
    </html>
  )
}
```

* * *

### 4) 应用程序中切换主题

使用示例 `useTheme()` 当您想要控制主题时 :

```tsx
'use client'

import { AppHeader, Button, useTheme } from '@dbcdk/react-components/client'
import { Moon, Sun } from 'lucide-react'

export default function Header() {
  const { theme, switchTheme } = useTheme({ defaultTheme: 'dbc' })

  return (
    <AppHeader>
      <Button
        variant="outlined"
        onClick={() => switchTheme(theme === 'dbc' ? 'filmstriben' : 'dbc')}
      >
        {theme === 'dbc' ? <Moon /> : <Sun />}
      </Button>
    </AppHeader>
  )
}
```

光是默认的颜色方案,包括水合前. `ThemeScript`, (中文(简体) ), `useColorScheme()`或系统 偏好。 明确默认OS偏好,使用 `<ThemeScript defaultColorScheme="system" />` 财务报告和审定财务报表 `useColorScheme('system')`。 。 。 .

钩子更新 `data-product-theme`,应用选定的产品主题 符号覆盖,并坚持选择.

如果您只需要读取活动主题状态, 请使用 `useGetActiveTheme()` 改为 `useTheme()`数字 :

```tsx
'use client'

import { useGetActiveTheme } from '@dbcdk/react-components/client'

export function ThemeBadge() {
  const { theme, colorScheme, themeKey } = useGetActiveTheme()

  return <span>{themeKey ?? `${theme} / ${colorScheme}`}</span>
}
```

`useGetActiveTheme()` 故意只读。 报告当前 活动主题状态 `ThemeScript`或 另一个挂载的主题控件 . `themeKey` 仅在两者同时设置时 `theme` 财务报告和审定财务报表 `colorScheme` 解决,否则 `null`如果你的应用通过一个 自定义 `storageKey`编号 :`colorSchemeStorageKey` (见下文),通过同样的价值观 在这里,它读到正确的持续状态.

* * *

### 5)在同一来源上运行多个应用程序

`useTheme`, (中文(简体) ), `useColorScheme`, (中文(简体) ), `useGetActiveTheme`, (中文(简体) ), `ThemeScript`, (中文(简体) ), `ThemeButton`编号 :`ThemeMenuSection`,以及 `ColorSchemeButton`编号 :`ColorSchemeMenuSection` 都坚持饼干+ `localStorage` 在共享默认密钥下。 如果两个 在这个库上构建的不同应用程序运行于同一来源( 例如 2) 将阅读并覆盖彼此的主题 默认选择.

为了保持它们的独立性,通过 `storageKey` (产品) 专题)和/或 `colorSchemeStorageKey` (彩色计划, `ThemeScript` 仅 -- 其他地方,这是 `storageKey` 选项 `useColorScheme`:

```tsx
<ThemeScript
  defaultTheme="dbc"
  storageKey="my-app-theme"
  colorSchemeStorageKey="my-app-color-scheme"
/>
```

```tsx
const { theme, switchTheme } = useTheme({ defaultTheme: 'dbc', storageKey: 'my-app-theme' })
const { colorScheme, switchColorScheme } = useColorScheme(undefined, {
  storageKey: 'my-app-color-scheme',
})
```

在给定的应用程序中, 在任何地方使用相同的密钥( O)`ThemeScript`钩子和 ),或数值将不一致地解决.

* * *

## 软件包集成

软件包的目标为捆绑机(Next.js,Vite,webpack)和带有CSS变换的测试跑车 (Vites,带有CSS模块映射器的Jest). 每个入口 - 主入口, `/client`, (中文(简体) ), `/tanstack`, (中文(简体) ), `/tanstack-virtual` 财务报告和审定财务报表 `/markdown` - 进口CSS模块和未捆绑的文件 与无延伸的相对进口, 所以节点自己的 `import`编号 :`require` 无法直接装入.

### 可选表格集成

`Table` 财务报告和审定财务报表 `useTableData` 可从 `@dbcdk/react-components/client` 没有坦斯塔克。 传出同样的 `ColumnItem<T>[]` 到桌子和钩子 `sorting.columns`; 钩子使用每列 `accessor` 和可选 `sortFunction`栏 `id` 作为 `sortBy`。 。 。 .

现有存取器形状的列( E)`accessorKey` 编号 : `accessorFn`),包括类型 TanStack 列, 也不引入 TanStack 依赖性 成为核心宣言。 明确 `columnComparators` 覆盖出列排序 .

`useTableSettings`, (中文(简体) ), `TableSettings`,以及 `TableSettingsMenuSection` 也为 可从 `/client`,及其类型和 `localStorageTableSettingsStorage`他们接受普通表格的列和 荣誉 `hidden` 财务报告和审定财务报表 `canHide`。现有的 TanStack 列带有: `accessorKey`, (中文(简体) ), `meta.hidden`,以及 `enableHiding` 保持兼容性.

安装 `@tanstack/react-table` 页:1 `TanstackTable` 从 `/tanstack`现有 设置导出自 `/tanstack` 继续作为相容性别名.

### 可选的马克下集成

`MarkdownEditor` 财务报告和审定财务报表 `MarkdownViewer` 可从 `@dbcdk/react-components/markdown`,而不是从主条目或 `/client`他们 需求 `markdown-it`,这是一个可选的对等关系:安装 (单位:千美元)`npm i markdown-it`只有你使用它们. `MarkdownViewer` 同时在 服务器组件; `MarkdownEditor` 是客户端组件.

### 下一个.js 配置

添加 `transpilePackages: ['@dbcdk/react-components']` 到您的下一个.js配置 因此,它处理库的 CSS 模块。 导入交互式组件和 来自 `/client`。包装集成检查涵盖下一个.js 16.2.6 有网络包装和19.2.4反应.

## 使用故事书

故事书是这个图书馆的主要文献和探索工具.

### 本地故事书

```bash
npm run storybook
```

故事书运行 `http://localhost:6006`。 。 。 .

### 在故事书中你可以:

1.  在左手导航中浏览组件
2.  打开一个故事来查看变体和状态
3.  调整道具通过 **控件**
4.  阅读准则和使用说明 **文档** 选项卡

* * *

## 主题

使用 \\\\ \\ \\ \\ **主题选择器** 用于在可用主题(例如光和暗)之间切换.

所有组件都使用主题文件中定义的CSS变量来进行样式.

* * *

## 无障碍(a11y)

无障碍是这个图书馆的头等大事.

我们的目标是确保各组成部分:

-   可用键盘导航
-   具有明显和一致的重点状态
-   与屏幕阅读器合作
-   遵循共同的ARIA和语义HTML最佳做法

故事书包括a11y addon,以帮助识别开发过程中的问题.

* * *

## MIME 类型助手

这些助手在服务器和客户端上工作,从根导出 `/client` 切入点:

```ts
import { formatMimeType, getMimeTypeExtension } from '@dbcdk/react-components'

formatMimeType('application/pdf') // 'PDF'
formatMimeType('text/plain; charset=utf-8') // 'Tekst'
getMimeTypeExtension('image/jpeg') // 'jpg'
```

`formatMimeType` 为常见的 MIME 类型提供丹麦标签,保留未知值不变,并返回 `-` 页:1 `null` 或者说 `undefined`。 。 。 . `getMimeTypeExtension` 返回没有常见图像类型和 PDF 的扩展名,或 `undefined` 用于不支持的类型。 在查找已知类型时,两者都忽略了MIME参数,外壳和周围的白空间.

* * *

## 本地选择控制

使用 `NativeSelect` 当你想要浏览器的本地 `<select>` 互动, 包括电话上的取站台. `Select` 是自定义的弹出控制. 从客户端入口导入交互式窗体控制 :

```tsx
'use client'

import { useState } from 'react'
import { NativeSelect } from '@dbcdk/react-components/client'

export function FormatFilter() {
  const [format, setFormat] = useState('')

  return (
    <NativeSelect
      label="Format"
      name="format"
      options={[
        { label: 'Alle formater', value: '' },
        { label: 'PDF', value: 'pdf' },
      ]}
      selectedValue={format}
      onChange={setFormat}
    />
  )
}
```

`NativeSelect` 包含 `InputContainer`: 通过 `labelAction`, (中文(简体) ), `helpText`, (中文(简体) ), `error`, (中文(简体) ), `orientation`,或 `fullWidth` 直接而不是添加另一个标签包装. 它被控制并且是单选的 : `onChange` 接收原始选项值 (字符串、数字或对象 `datakey`),不是DOM事件. 提供的选项 `value: ''` 是一个真正的选择,并替换合成占位符。 否则, 选择引用的占位符 `onClear`,当提供.

原生属性和元素 ref 被转发,包括 `name`, (中文(简体) ), `form`, (中文(简体) ), `required`, (中文(简体) ), `disabled`,以及 `onBlur`。参加 `FormData`, (中文(简体) ), 财务报告和审定财务报表 `required` 使用浏览器验证. `allowClearWhenRequired` 允许清除 但不能绕过验证 使用 `MultiSelect` 用于多个选择.

默认的中文本使用16px主题符号. 粗指头至少会 44px控制高音符,而小/中文本则使用16px符号. 这个 保持移动控件的可读性,而不取代本地交互. 检查 在验证时, 出版了关于 iOS Safari 和 Android Chrome 的 故事集 平台拾取者行为;桌面仿真不验证这些拾取者.

* * *

## 捐款

见 [`CONTRIBUTING.md`](https://npmcn.com/package/%40dbcdk/react-components/CONTRIBUTING.md) 详细指南:

-   文件夹结构
-   造型和主题规则
-   故事书要求
-   类型脚本公约
-   版本和更改

* * *

## 许可证

公务员制度委员会

### 组标签、标题大小和打印内容

这些选项是添加剂;现有默认情况保持不变.

```tsx
import {
  CollapsibleHeadline,
  Headline,
  RadioButtonGroup,
} from '@dbcdk/react-components/client'

// The fieldset's legend stays above the controls. The existing div-based
// orientation/layout remains the default when `as` is omitted.
<RadioButtonGroup
  as="fieldset"
  label="Format"
  direction="row"
  options={[
    { label: 'PDF', value: 'pdf' },
    { label: 'Tekst', value: 'text' },
  ]}
  value={format}
  onChange={setFormat}
  helpText="Vælg ét format."
/>

// An h3 with the theme's 24px/xl type token, without changing heading semantics.
<Headline size={3} textSize="xl">Dokumentoplysninger</Headline>

// Closed on screen initially; includes its content when printing.
<CollapsibleHeadline header="Flere oplysninger" defaultExpanded={false} printExpanded>
  <p>Supplerende indhold.</p>
</CollapsibleHeadline>
```

`Headline.textSize` 接受 `xs`, (中文(简体) ), `sm`, (中文(简体) ), `md`, (中文(简体) ), `lg`, (中文(简体) ), `xl`,以及 `2xl`; 省略为 保留现有的响应标题表。 也致力于 `CollapsibleHeadline`。 。 。 .

`printExpanded` 将被倒闭的孩子挂在屏幕上 从键盘导航和无障碍树。 其状况和影响 保持活动。 违约仍未解除 儿童崩溃。 打印没有 改变扩张状态或其持续价值。 任何应用程序打印流程 必须仍然包括组件及其样式表.

`RadioButtonGroup` 将其标签、错误和帮助文本与组关联到 两种布局. `InputContainer.labelId` 也可用于自定义控制 需要引用其可见标签 `aria-labelledby`。 。 。 .

对于在窄屏幕上必须保持完全可读性的问题,请使用 `<Accordion wrapHeaders items={items} mode="single" defaultOpenIndex={null} />`。 。 。 . 页眉包是选入;现有的截取不变. 封闭的面板是 惰性并被隐藏在辅助技术中,包括打开后. 他们现有的动画和保留的儿童状态得以保存.

使用 `Accordion variant="plain"` 带有分隔符的轻量级问题列表 在行之间,不附加边框或背景. `headerWeight` 可选择 设置问题重 (400, 500, 600, 或 700); 现有的默认值为 400.

`Accordion flushContent` 从每个项目的内容中删除上下粘贴, 包括已填充的变体的开平面上间距. 水平内容编码 并保留每个大小和变体的页眉标记。 就像Tabs,这个 选项默认为 `false`,保持现有的间隔。 巢穴保留 他们自己的内容间隔, 即使在一个冲出Annion.

对于可重复使用的国家政策或持久性,导入 `useAccordionState` 从 客户端进入点 并让它拥有Annion的控制状态:

```tsx
'use client'

import { Accordion, useAccordionState } from '@dbcdk/react-components/client'

const items = [
  { id: 'general', header: 'Generelt', children: <p>Generelle oplysninger</p> },
  { id: 'details', header: 'Detaljer', children: <p>Flere oplysninger</p> },
]

export function Details() {
  const { accordionProps, openAll, closeAll } = useAccordionState({
    itemIds: items.map(item => item.id),
    mode: 'multiple',
    initialOpen: 'all',
    storageKey: 'my-app-details', // Omit for in-memory state only.
  })

  return (
    <>
      <button onClick={openAll}>Åbn alle</button>
      <button onClick={closeAll}>Luk alle</button>
      <Accordion items={items} {...accordionProps} />
    </>
  )
}
```

`itemIds` 必须包含独特、非空、稳定的字符串,顺序与 `items`。钩子拒绝丢失或复制ID,而不是返回到 索引。 Annion本身仍然支持没有ID的项目.

`initialOpen` 是挂载时间默认值 : `'none'` (默认), `'all'`,或数组 身份证 在单一模式下,只打开第一个有效的ID; `'all'` 财务报告和审定财务报表 `openAll()` 打开第一个项目. `closeAll()` 崩溃一切。 结果也暴露了 `openIds`, (中文(简体) ), `setOpenIds(ids)`,以及 `hydrated`。 。 。 .

与 `storageKey`,钩子使用库中本地Storage的持久性和 挂载后恢复。 服务器渲染和第一个客户端渲染相同 初始状态; `hydrated` 恢复完成时的信号。 已保存为空 数组故意会倒塌 数据畸形会回到默认值, 和无法使用的存储状态在内存中可用。 只保存了身份证,所以 重排会保持相同的部分打开;从列表中去掉的ID会被刷新. 对每个独立的手风琴都使用不同的钥匙. 在挂载钩子上切换密钥时, 新的密钥在写入前会恢复 或查取其保存的身份证.

打电话者可以提供 `openIds` 财务报告和审定财务报表 `onOpenIdsChange` 用于外部控制; 此选项将禁用所有存储读取和写入 。 坚持下去 让钩子自己来 状态和通过它 `accordionProps` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}没有压倒他们 独立控制状态。 手风琴没有 `storageKey` 道具及其现有 控制/非控制道具和 `defaultOpenIndexes="all"` 保持不变.

单位 `MarkdownEditor editOn="click"`,则 **陆克** 按钮旁边 **伦克斯特** 结束编辑, 保留当前值, 调用 `onEditEnd`,并恢复焦点 编辑按钮。 它的文本可以定制 `labels.doneButton`行动 也可以从预览和纯文本模式获得; 在文本区域保存中输入 它的正常新线行为。 在窄屏幕上,开关和按钮占用 他们自己的一行.

## 常见问题

### @dbcdk/react-components 是什么？

DBC 项目的再使用组件

### 如何安装 @dbcdk/react-components？

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

### @dbcdk/react-components 支持 TypeScript 吗？

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

### @dbcdk/react-components 支持 ESM 还是 CommonJS？

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

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

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

### @dbcdk/react-components 可以商用吗？

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

### @dbcdk/react-components 的下载量有多少？

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

### @dbcdk/react-components 还在维护吗？

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