# @devslab/dds-react 中文文档

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

版本：0\.33\.0
npm 元数据更新时间：2026-11-11T19:00:02.844Z
中文译文更新时间：2026-11-12T07:08:17.057Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40devslab/dds-react
原文对照：https://npmcn.com/package/%40devslab/dds-react/?lang=original
项目主页：https://devslab.kr/brand/
源码仓库：https://github.com/devslab-kr/dds

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

- 包体积（解压后）：453 kB，104 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^18\.3\.0 \|\| ^19\.0\.0，react-dom ^18\.3\.0 \|\| ^19\.0\.0
- 首次发布：2026-10-11T07:11:33.502Z
- 最新版本发布：2026-11-11T19:00:02.348Z
- 近 30 天下载量：2702（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

用于 DevsLab 设计系统的可访问反应原始

## 安装

```sh
npm install @devslab/dds-react
```

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

## README

# DDS 反应

使用Ark UI 5.39.3并共享DDS令牌,CSS和图标的可访问回放原始相. React和React DOM为同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等同等 在应用程序中导入 CSS 一次 :

```tsx
import '@devslab/dds-react/styles.css';
import { Button, Field, Select, Dialog, Tabs, TabList, Tab, TabPanel } from '@devslab/dds-react';

<Field label="Country" helpText="Choose a country">
  {control => <Select {...control} defaultValue="kr"><option value="kr">Korea</option></Select>}
</Field>
<Button tone="primary" onClick={() => setOpen(true)}>Edit</Button>
<Dialog open={open} onOpenChange={setOpen} title="Edit country" description="Changes apply to your profile">
  <Button onClick={() => setOpen(false)}>Done</Button>
</Dialog>
<Tabs defaultValue="overview">
  <TabList aria-label="Sections"><Tab value="overview">Overview</Tab></TabList>
  <TabPanel value="overview">Content</TabPanel>
</Tabs>
```

输出 : `Button`, (中文(简体) ), `IconButton`, (中文(简体) ), `Field`, (中文(简体) ), `Checkbox`, (中文(简体) ), `Radio`, (中文(简体) ), `Select`, (中文(简体) ), `Switch`, (中文(简体) ), `RadioGroup`, (中文(简体) ), `Dialog`, (中文(简体) ), `Tabs`, (中文(简体) ), `TabList`, (中文(简体) ), `Tab`, (中文(简体) ), `TabPanel`, (中文(简体) ), `Tooltip`, (中文(简体) ), `Icon`, (中文(简体) ), `ToastProvider`, (中文(简体) ), `useToast`, (中文(简体) ), `ConsoleShell`及其道具类型。 标签、工具提示信息、对话框标题和通知副本来自呼叫者。 没有翻译后退副本.

本地 DOM 属性使用 React 拼写(`className`, (中文(简体) ), `htmlFor`, (中文(简体) ), `onChange`DOM 组件接受 React 对象或召回 refers; 选择 refs 目标其选择和 Dialog 目标内容 。 按钮默认为 `type="button"`;加载会阻止活化并保持按钮的名称和大小:标签被隐藏,而不会被去掉,而自旋器被划过(D-043),所以在加载时保持标签不变. 复选框、无线电和切换接受 `checked`编号 :`defaultChecked`, (中文(简体) ), `onCheckedChange(boolean)` 和本地输入属性。 选择使用本地 `value`编号 :`defaultValue` 财务报告和审定财务报表 `onChange`。无线电组 `label` 财务报告和审定财务报表 `options: { value, label, disabled? }[]`,与 `value`编号 :`defaultValue` 财务报告和审定财务报表 `onValueChange(string)`。 。 。 .

标签扩展 方舟根选项 `onValueChange(string)`;部件接受普通的方舟DOM道具,包括 `asChild`对话框接受 方舟根选项 `onOpenChange(boolean)`, (中文(简体) ), `closeOnOutside`, (中文(简体) ), `initialFocus`, (中文(简体) ), `finalFocus`, (中文(简体) ), `contentProps`, (中文(简体) ), `actions`, (中文(简体) ), `frame(parts)` 财务报告和审定财务报表 `unstyled`。默认对话框门户;使用 `portal={false}` 用于内置标记,包括开放的安全部门改革内容。 方舟拥有巢式模式隔离,聚焦,逃逸处理和滚动锁等功能. Solid 包中的额外焦点容器没有被仿真;使用 Ark `persistentElements` 财务报告和审定财务报表 `modal`编号 :`trapFocus` 根据申请需要.

工具提示接受一个元素子( Ark) `asChild`)或接受本地按钮触发道具的渲染函数. 使用可聚焦触发器并保存所提供的事件. `ToastProvider` 接受可选的呼叫者 `regionLabel` 财务报告和审定财务报表 `dismissLabel` (字符串或记录到字符串函数);无 `dismissLabel` 它没有关闭按钮. `useToast()` 返回时 `show`, (中文(简体) ), `loading`, (中文(简体) ), `update`, (中文(简体) ), `promise`, (中文(简体) ), `dismiss`,以及 `clear`;持续时间为0。 供应商卸载时清除通知。 这个 [餐饮指南](https://npmcn.com/package/docs/toast.md) 涵盖相同的反应/Solid/Vue合同.

```tsx
const toast = useToast(); // inside ToastProvider
const id = toast.loading({ message: "Saving…" });
toast.update(id, { message: "Saved", tone: "success" });

const pending = toast.promise(() => save(), {
  loading: { message: "Saving…" },
  success: { message: "Saved", action: { label: "View result", onClick: openResult } },
  error: { message: "Save failed" },
});
const result = await pending; // original result, or original rejection
// pending.id can also be passed to update/dismiss while the operation runs.
```

`action: { label, onClick }` 添加按钮和 `action: null` 把它删除通过 `update`在援引回电之前,行动解除。 继续装入; 设置终端语气 `update` 开始正常的过期。 手动更新, 解除合同、解除合同或解除合同使未兑现的承诺无法被推翻 或重新创建该通知。 信件要素例外 仍为当前通知,而不更改任务结果/错误。 没有重试或请求 取消了; 呼叫者仍然处理拒绝的操作 .

高级组成部件导出为 `ArkDialog`, (中文(简体) ), `ArkTabs`, (中文(简体) ), `ArkTooltip`, (中文(简体) ), `ArkRadioGroup`, (中文(简体) ), `ArkCheckbox`, (中文(简体) ), `ArkSwitch`, (中文(简体) ), `ArkField`,以及 `ArkToast`它们是被钉住的上方方方舟命名空间,在方便部分内有用,或用于应用程序的构成.

ConsoleShell 接受呼叫者品牌/导航/标题/标签/脚槽和独特的每英寸地标标识. 其铁路采用呼号线路状态;不包含路由器或商铺. 导入和服务器渲染不需要浏览器 Global; 安装后只启动客户端效果 。 反应 `useId` 通过水合保持标签关联的稳定。 反应 JSX,反应参考和方舟 `asChild` 元素构成不同于固态回调/存取器。 网格是一个单独的依赖:使用 `@devslab/dds-table-react` 为AG网格.

无害环境管理和申报被运出; 反应、反应DOM和方舟仍然处于DDS捆绑之外。 此软件包在包含的 LICENSE 下可获取源, 匹配 DDS 寄存器 .

## 日期选择器

```tsx
import { DatePicker } from "@devslab/dds-react";
<DatePicker label="시작 날짜" value={date} onChange={setDate} />
```

已控制 `value` 用途 `YYYY-MM-DD` 或者一个空字符串. `locale` 默认为 `ko-KR`, (中文(简体) ), `timeZone` 改为 `Asia/Seoul`可选 `min`, (中文(简体) ), `max` 财务报告和审定财务报表 `disabled` 限制选择。 导入软件包样式表 。 时间选择是一个单独的字段. 方舟子拥有日历焦点,键盘导航和弹出解职.

## 创建状态Pill

```tsx
const StatusPill = createStatusPill({
  tones: { job: { ready: "success" } },
  label: (domain, value, locale) => value === "ready" ? "준비됨" : undefined,
});
<StatusPill domain="job" value="ready" locale="ko" />
```

未知的闭域状态值会丢出以曝光不完整的目录 。 所列领域 `openDomains` 将未知值显示为已逃出文本 .

## 使用待定动作

屏幕上有数个按钮 需要知道哪个开始工作 把一个共享旗子传到每个按钮上,它们都一击就旋转.

```tsx
const action = usePendingAction<"approve" | "reject">();
<Button tone="danger" loading={action.is("reject")} disabled={action.busy}
  onClick={() => action.run("reject", () => decide("reject"))}>Reject</Button>
<Button loading={action.is("approve")} disabled={action.busy}
  onClick={() => action.run("approve", () => decide("approve"))}>Approve</Button>
```

和Solid的合同一样 `createPendingAction`,以数值取代访问者. `is(key)` 仅适用于运行中的行动; `busy` 锁住其他的. `run` 清除任务解决时的状态, 传出错误, 并在另一个动作运行时无所事事, 即使在同一事件循环转弯中, 在 React 完成第一个动作之前, 过 `{ replace: true }` 最近的请求应当获胜,例如重新装入列表。 任务收到 `AbortSignal` 终止于 `reset()`在替换它的跑道上,在卸载时: `signal.aborted` 各人等待到状态建立之前,或传到 `fetch`. 完成时间过晚永远无法清除新的行动.

### DatePicker 手动输入和保存

`value`编号 :`onChange` 只保留条形日期 `YYYY-MM-DD` 字符串( 或故意清晰) `''`) (中文(简体) ). 输入时执行完整的真实日期; 无效/不完整的文本保持可见, 永远不会成为替换日期 . `required` 推进本地/无障碍所需状态; `readOnly` 防止编辑/日历打开。 被锁定的过渡关闭了门户. 无效的持久值在未解析或清除的情况下产生错误 .

订阅 `onValidityChange(state: DatePickerValidity)` 显示准确的 `inputValue`,犬类 `value` (或无效时无效), `valid`,和理由(`valid`, (中文(简体) ), `required`, (中文(简体) ), `incomplete`, (中文(简体) ), `invalid`, (中文(简体) ), `rangeUnderflow`, (中文(简体) ), `rangeOverflow`) (中文(简体) ). 原生形式使用可见输入的自定义有效性. API/按钮/shortcut 保存 MUST 也检查回调状态;在可见的草稿无效时,一个canonic父值可能仍然包含最后一个有效的选择. 开始未知/ 锁定直到初始回调 。 不推断有效性从 `value` 一个人.

```tsx
const [date, setDate] = useState('2028-02-28');
const [dateValidity, setDateValidity] = useState<DatePickerValidity | null>(null);
<DatePicker label="Date" value={date} onChange={setDate}
  required onValidityChange={setDateValidity} />
// In every save handler (including shortcuts):
if (!dateValidity?.valid || dateValidity.value === null) return;
await save({ date: dateValidity.value });
```

严格的Gregorian日期和兼容并蓄的分数/分数在不实现时区正常化或无声夹的情况下被验证. 总是清除报告 `onChange('')`; 所需的清晰度仍然无效。 保持权威服务器验证. 仅靠图书馆的测试并不能确定消费者的请求处理者使用这个守护. 韩语( A)`ko`, (中文(简体) ), `ko-KR`显示 `YYYY/MM/DD`· ; `value`, (中文(简体) ), `onChange`,分钟/最大和 `DatePickerValidity.value` 保留 `YYYY-MM-DD`消费者不得取代分离者或坚持 `inputValue`。ISO 粘贴被普通解析器接受,只有当它是一个完整的有效日期时才正常化。 只日期值不随时间区变化.

`onValidityChange` 初始报告和关于语义草稿/约束/控制值的修改,包括无效/部分编辑,不发出 `onChange`。用于肮脏/导航守护,并在输入变化时取消待公布确认。 只替换回调函数不会重放相同的报告 : 这样会防止内置设置状态渲染循环 。 通过文档身份/重置修订按键自有编辑器,并与使用Callback保持回调稳定. 新的按键实例收到一份新的初始报告,即使日期相同。 在跟踪原始基线时比较有效日期和无效草稿的原始输入值;不要生成消费者侧显示格式。 重载/重置基准,只针对有意编辑器更改/重置.

```tsx
<PolicyDateEditor key={`${document.id}:${document.revision}`} document={document} />
// Inside PolicyDateEditor (one editor identity):
const baseline = useRef<string | undefined>(undefined);
const previous = useRef<string | undefined>(undefined);
const onDateValidity = useCallback((state: DatePickerValidity) => {
  setDateValidity(state);
  const stateKey = JSON.stringify(state.valid ? [true, state.value] : [false, state.inputValue]);
  if (baseline.current === undefined) baseline.current = stateKey;
  setDirty(stateKey !== baseline.current);
  if (previous.current !== undefined && previous.current !== stateKey) {
    closePublishConfirmation();
  }
  previous.current = stateKey;
}, [closePublishConfirmation]); // Keep closePublishConfirmation stable too.
// Every button/API/shortcut Save checks valid and persists state.value only.
```

延迟的可控回声与未清的局部排放相匹配,确认发生时没有替换更新的草稿。 重复的 B/C/B 保留为 三起; 重复模糊/ Enter 不再发出 。 不在待排排放量中的变化值是外部重置和清理待排历史。 只有字符串的 API 无法区分有意重置到一个仍然未清的同值的确认;使用按键编辑器重挂一个明确的重置. 保持局部可控状态同步,并分别坚持到服务器上. 未确认的排放在确认、外部重置或卸载之前保留.

## 输入、选择、重叠和共享日历

输入/输入组是通用的本土输入,不只搜索,有标签放置和明确的动作. Combobox/SelectPicker支持固定行虚拟化; DropdownMenu/Popover提供可访问的覆盖; Calendar/DatePicker/DateRangPicker/MonthPicker共享日历视图.

使用明确的子路径 `@devslab/dds-react/input`, (中文(简体) ), `/combobox`, (中文(简体) ), `/select-picker`, (中文(简体) ), `/dropdown-menu`, (中文(简体) ), `/popover`, (中文(简体) ), `/calendar`, (中文(简体) ), `/date-picker`, (中文(简体) ), `/date-range-picker`, (中文(简体) ), `/month-picker`,或现有的根导出。 继续导入 `styles.css` 一次 一次吗 见 [通用使用指南](https://github.com/devslab-kr/dds/blob/main/docs/components-input-choice-calendar.md)。 。 。 . 使用明确的子路径 `@devslab/dds-react/input`, (中文(简体) ), `/combobox`, (中文(简体) ), `/select-picker`, (中文(简体) ), `/dropdown-menu`, (中文(简体) ), `/popover`, (中文(简体) ), `/calendar`, (中文(简体) ), `/date-picker`, (中文(简体) ), `/time-picker`, (中文(简体) ), `/date-range-picker`, (中文(简体) ), `/month-picker`, (中文(简体) ), `/segmented-control`, (中文(简体) ), `/number-input`,或现有的根导出。 继续导入 `styles.css` 一次 一次吗 见 [通用使用指南](https://github.com/devslab-kr/dds/blob/main/docs/components-input-choice-calendar.md)。 。 。 .

## 可选控制台导航组

`ConsoleShell` 继续扩大传统团体。 设置一个独特的,稳定的 `id` 财务报告和审定财务报表 `collapsible: true` 在一组中选择披露按钮。 一个项目可选 `icon` 是装饰性的;保留其文本 `label`。 。 。 .

```tsx
<ConsoleShell {...shellProps}
  nav={[{ id: "settings", label: "Settings", collapsible: true,
    items: [{ id: "policies", href: "/policies", label: "Policies", icon: <Icon name="check" /> }] }]}
  expandedGroups={expandedGroups}
  onExpandedGroupsChange={setExpandedGroups}
/>
```

奥米 `expandedGroups` 内部状态. `defaultExpandedGroups` 供应 初始值; `[]` 启动所有相撞组关闭 。 没有道具,只有 包含活动项目的组合开始打开。 其他团体总是保持开放. 多个群体可以扩大。 失踪的身份证回落到 `group-<index>`; 首选 用于持久性或重排的稳定的独特ID。 应用程序拥有路由更改 扩大和坚持。 水分后读取浏览器存储, 保存服务器 和初始客户状态相等。 DDS 从未访问存储或覆盖 a 控制选择。 输入/空间和 `aria-expanded`编号 :`aria-controls` 双方的工作 桌面铁路和移动抽屉.

## 共享应用程序布局

布局,LftNav和TopNav使用常见的几何和打字规则. 见 [组成和确切的维度](https://npmcn.com/package/docs/layouts.md)。 。 。 .

## 常见问题

### @devslab/dds-react 是什么？

用于 DevsLab 设计系统的可访问反应原始

### 如何安装 @devslab/dds-react？

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

### @devslab/dds-react 支持 TypeScript 吗？

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

### @devslab/dds-react 支持 ESM 还是 CommonJS？

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

### @devslab/dds-react 可以商用吗？

@devslab/dds-react 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @devslab/dds-react 的下载量有多少？

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

### @devslab/dds-react 还在维护吗？

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