# @djangocfg/ui-core 中文文档 规范地址：https://npmcn.com/package/%40djangocfg/ui-core/ 版本：2\.1\.655 npm 元数据更新时间：2026-11-12T12:34:29.712Z 中文译文更新时间：2026-11-12T12:11:31.836Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40djangocfg/ui-core 原文对照：https://npmcn.com/package/%40djangocfg/ui-core/?lang=original 项目主页：https://djangocfg.com/ 源码仓库：https://github.com/markolofsen/django-cfg ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.6 MB，356 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：48 个 - peer 依赖：zod ^4\.3\.6，next \>=14\.0\.0，react ^19\.0\.0，moment ^2\.30\.1，sonner ^2\.0\.7，consola ^3\.4\.2，zustand ^5\.0\.0，react-dom ^19\.0\.0，next-themes ^0\.4\.6，tailwindcss ^4\.1\.18，lucide-react ^1\.68\.0，react-router \>=7，@djangocfg/api ^2\.1\.655，@djangocfg/i18n ^2\.1\.655，react-hook-form ^7\.69\.0，react-device-detect ^2\.2\.3 - 首次发布：2025-12-04T09:39:14.196Z - 最新版本发布：2026-11-12T12:34:29.394Z - 近 30 天下载量：18702（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：568（近 12 个月 568 个） ## 中文简介 纯React UI 组件库 无 Next.js 依赖性 - 为 Electron, Vite, CRA apps ## 安装 ```sh npm install @djangocfg/ui-core ``` 也可以使用：`pnpm add @djangocfg/ui-core`、`yarn add @djangocfg/ui-core`、`bun add @djangocfg/ui-core` ## README ![@djangocfg/ui-core](https://raw.githubusercontent.com/markolofsen/assets/main/libs/djangocfg/ui-core.webp) # @djangocfg/ui-core (英语) 框架-不可知回放 UI 库: 在 Tailwind v4 上 70+ shadcn/ Radix 组件,语义主题符号, Canvas/SVG 的调色板钩子, 加上一个允许相同的路由器-适应器系统 `` 编号 : `` 编号 : `` 在Next.js、Vite、Electron、Wails或Plain React下工作. **部分 [强哥CFG](https://djangocfg.com/)。 。 。 . [现场演示](https://djangocfg.com/demo/)。 。 。 .** ## 安装 ```bash pnpm add @djangocfg/ui-core ``` 在任何反应主机工作. Next.js apps 从这里直接导入组件和 添加下一个路由器适配器 `@djangocfg/ui-core/adapters/nextjs` (见 **路由器适配器** (见下文); 下个具体 _服务器_ 公用事业(用品、保健、, OG 图像, 配置) 分别存在 [`@djangocfg/nextjs`](https://npmcn.com/package/%40djangocfg/nextjs) 软件包. 曾经在app root 导入样式—— 使用金色路径, 它将所有的东西都钉上 到右级联层, 这样导入顺序不能打破布局功能 : ```css /* FIRST style import in your app entry CSS */ @import "@djangocfg/ui-core/styles/full"; /* Tailwind v4 + tokens + base + utilities, layer-safe */ ``` 平原上 `@djangocfg/ui-core/styles` 条目不导入尾风并发送 它的 CSS 未分层—— 如果您使用它, 您拥有层排序( 导入) `tailwindcss` (第一编) 见 `src/styles/README.md` § 应用设置为什么. 偏爱 `…/styles/full`。 。 。 . ## 快开始 ```tsx import { UiProviders, Button, Card } from '@djangocfg/ui-core'; ``` `` 按照正确的顺序挂载工具提示/ 对话框/ 标签 **和顶级错误 `Boundary`** (崩溃显示可恢复倒计时,而不是白屏幕). **挂在根上** - 图书馆组成部分(以及图书馆内的一切) `@djangocfg/ui-tools`相信它在那里,永远不筑巢 他们自己的(一秒钟) `TooltipProvider` 是"工具提示必须在工具提示提供器"陷阱内使用"的犬形. 过 `onError` 向您的日志转发崩溃, `errorFallback` 用于自定义(例如 i18n) 崩溃屏幕,或 `errorBoundary={false}` 选择退出. ## 目录 | 组 | 实例 | | --- | --- | | `components/data/` | 阿凡达·阿凡达集团·徽章·徽章·相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相相接相接相接相接相`timeZone` 平面图(平面图) `/chart`(中文(简体) ) | | `components/forms/` | 按钮 控制 SIZE 下载按钮 按钮 按钮组 输入 输入组 输入 输入 · 标记输入 · 文本区 · 切换 · 检查框 · 检查组 · 检查组 · 幻灯片 · 表格 · 可编辑 · 设置Row / 设置 Block · 日期 · 时间 · 日期 · 日期 · 日期 · 地点 · 货币 · 过滤按钮 · 过滤器 · 梅努 · 流行动作按钮 · 时间选择器( legacy) | | `components/select/` | 选择 · 组合框 · 组合框 Async · 多选择 · 多选择Pro · 国家 · 选择语言 · 选择时区 | | `components/feedback/` | 警报 · 吐司 (声纳) · 班纳 · 空 · 预装机 · 斯平纳 | | `components/overlay/` | 对话框 – 提醒对话框 – 抽取器 – 工作表 – 响应板 – 侧面小组 – 弹出器 – 工具提示 – HoverCard | | `components/navigation/` | **菜单构建器** · 滴下梅努 · 上下文梅努 · 菜单巴尔 · 导航梅努 · 侧边栏 · 标签 · 面包屑 · 接线人 · 接线人 · 可折叠 · 披露 · 命令 · 链接 · 弹出Row按钮 | | `components/layout/` | · 相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相相相相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 | | `components/effects/` | 光滑背景 · 交换 | | `components/specialized/` | 复制按钮 · 复制字段 · Kbd · 旗帜 · 图像与背面 · 物品 · 托克尼孔 · 门户 · 存在 · 原始 · 视觉隐藏 | | `components/boundary/` | 边界(错误边界,由 `UiProviders`(中文(简体) ) | ### 控制大小 `Button` 每一个类似野外的控制 读取一个高梯, `CONTROL_SIZE` (单位:千美元)`forms/control-size.ts`),所以一行他们排出每行 尺寸。 永远不要写 `h-9` 编号 : `h-10` 在控件上:读取地图,或者通过大小. | 大小 | 高度 | 按钮 `size` | `Input` 编号 : `InputGroup` 编号 : `DateField` `inputSize` | `SelectTrigger` `size` | | --- | --- | --- | --- | --- | | `xs` | 28px (中文(简体) )`h-7`(中文(简体) ) | 对 | 对 | 对 | | `sm` | 32px (英语:`h-8`(中文(简体) ) | 对 | 对 | 对 | | `default` | 36px (英语:`h-9`(中文(简体) ) | 对 | 对 | 对 | | `lg` | 44px (英语:`h-11`(中文(简体) ) | 对 | 对 | 对 | | `huge` | 56px (英语:`h-14`(中文(简体) ) | 对 | 没有 | 没有 | 在粗糙的指头上,每只指头 `huge` 升至44px层 (单位:千美元)`pointer-coarse:min-h-11`,由龙自己携带,所以 `Button`, (中文(简体) ), `Input`, (中文(简体) ), `SelectTrigger` 和日期字段在电话中保持平平 图标 `Button` 宽度也为44px `TabsTrigger` 高为44px (其 `TabsList` 音轨生长到周围48px. 一只老鼠把高度放在桌子上 文本 字段 16px 电话和 14px 从 `md` (单位:千美元)`text-base md:text-sm`: `Input` 默认大小, `Textarea` 财务报告和审定财务报表 `SelectTrigger`。 。 。 . `Button` 还有 `icon` (有鼠标的36px正方形). 建构在 `Button` (单位:千美元)`Combobox`, (中文(简体) ), `LanguageSelect`, (中文(简体) ), `DatePicker`从按钮取出高度 大小; 多选择的触发器使用 `minHeight` 所以芯片可以包装 但永远不会 坐在固定的控制之下。 不是在梯子上,故意的: `FilterButton` (数量) `FilterBar` 设置高度),OTP/分块细胞(平方码细胞), 财务报告和审定财务报表 `Textarea` (多线, `min-h-[60px]`) (中文(简体) ). `control-size.test.tsx` 失败, 如果 `Button`, (中文(简体) ), `Input` 或者说 `SelectTrigger` 停下来 同意;故事书故事 `Controls / Alignment` 绘制向导行. ### 菜单构建器 声明菜单:通过 `MenuItem[]` 和触发器,它通过 `DropdownMenu*` 原始的 原始的 原始的. `kind` 歧视者`item`, (中文(简体) ), `submenu`, (中文(简体) ), 复选框 / 收音机行、 分隔符、 标签; 列 `icon`, (中文(简体) ), `description`, (中文(简体) ), `shortcut`, (中文(简体) ), `href`, (中文(简体) ), `hidden`, (中文(简体) ), `disabled`, (中文(简体) ), `variant: 'destructive'`。行文本为 `text-sm`。 。 。 . `@djangocfg/layouts` 用它构建其用户菜单 (单位:千美元)`useAccountMenuItems` 编号 : `AccountMenuButton`()——重用而不是习惯 菜单. 进口保持平稳——组文件夹为组织. 原生引擎日期/时间 字段( r)`DateField` 编号 : `TimeField` 编号 : `DateTimeField`)本身的参考文献有: [`forms/datetime-field/README.md`](https://npmcn.com/package/%40djangocfg/ui-core/src/components/forms/datetime-field/README.md)。 。 。 . `MoneyField` 带一个数量作为整数小单位,而不是一个浮点——见 [`forms/money-field/README.md`](https://npmcn.com/package/%40djangocfg/ui-core/src/components/forms/money-field/README.md)。 。 。 . ## 钩子`/hooks`(中文(简体) ) | 专题 | 钩子 | | --- | --- | | `dom/` | `useSize` • 妇女 `useResizeObserver` • 妇女 `useMeasure` • 妇女 `useMutationObserver` • 妇女 `useIntersection` • 妇女 `useHighlight` | | `device/` | `useIsMobile` • 妇女 `useIsTouch` • 妇女 `useMediaQuery` • 妇女 `useOnline` • 妇女 `useViewportSize` • 妇女 `useOrientation` | | `state/` | `useDebounce` • 妇女 `useDebouncedCallback` • 妇女 `useStateMachine` • 妇女 `useCallbackRef` • 妇女 `usePrevious` | | `storage/` | `useLocalStorage` • 妇女 `useSessionStorage` • 妇女 `useStoredValue` · 关键计划(`storage-namespace`(中文(简体) ) | | `events/` | `useEventListener` • 妇女 `useClickOutside` • 妇女 `useKeyPress` • 妇女 `useFocusWithin` | | `theme/` | `useTheme` • 妇女 `useResolvedTheme` • 妇女 `useThemePreset` | | `feedback/` | `useToast` • 妇女 `useDialog` • 妇女 `useClipboard` • 妇女 `useConfirm` | | `hotkey/` | `useHotkey` (单键+和弦) | | `audio/` | `useBeep` • 妇女 `useSpeak` (网络演讲) | | `tabs/` | `useCrossTab` (广播频道协调) | | `media/` | `useMediaPermissions` • 妇女 `useUserMedia` • 妇女 `useDevices` | | `time/` | `useNow` • 妇女 `useInterval` • 妇女 `useTimeout` | | `router/` | `useLink` • 妇女 `useRouter` (路由调整器消费者) | ### 存储密钥和命名空间`hooks/storage`(中文(简体) ) `useLocalStorage`, (中文(简体) ), `useSessionStorage` 财务报告和审定财务报表 `useStoredValue` (每个组成部分) `storageKey` prop) 在一个方案下写作, `..`,比如说. `cfg.ui.sidebar_width`, (中文(简体) ), `kino.player.volume`。关于代理人的完整规则: `@djangocfg/api` → `@docs/STORAGE_KEYS.md`。 。 。 . - 已经遵循该计划的密钥被沿用至今. - 赤名( bare`'search-filter'`折叠为 `snake_case` 并放进 活动所有者 : `cfg.ui.search_filter`主人是钩子 `namespace` 选项,否则最接近 ``,否则 框架默认 `cfg`。 。 。 . - 配额回收只减少我们计划的非个人钥匙, 从来不是象征性的, 草稿、配置文件或第三方密钥(`NEXT_LOCALE`) (中文(简体) ). ```tsx // app root, once … // lib/storage.ts, fixed keys declared once export const kino = createStorageNamespace('kino'); export const VOLUME = kino.key('player', 'volume'); // kino.player.volume const [volume, setVolume] = useLocalStorage(VOLUME, 1); kino.keys(); // every kino.* key in localStorage kino.clear(); // "reset preferences" (personal cfg keys survive) ``` 帮助者 : `resolveStorageKey`, (中文(简体) ), `isSchemeKey`, (中文(简体) ), `listStorageKeys(owner, area)`, (中文(简体) ), `clearStorageNamespace(owner, { area, includePersonal })`, (中文(简体) ), `createStorageNamespace(owner)` (单位:千美元)`key`, (中文(简体) ), `storage` = 注意阅读/写作/变化, `keys`, (中文(简体) ), `clear`) (中文(简体) ). 不写 `localStorage` 元件中的字元键或相加键. ## 公用设施`/lib`(中文(简体) ) - `cn(...)` —— 说 `clsx` + 键 `tailwind-merge` 快捷键 - `getIntensity(value, thresholds)` ——将数值分解成离散的桶(热映射、测量仪) - `createLogger()` 平面控制台记录器 - `dialog-service` ——必须 `confirm()` 编号 : `alert()` 编号 : `prompt()` 返回承诺 - `persist` 键入本地Storage/会话Storage钩 - `pretext` (传教士) `@djangocfg/ui-core/lib/pretext`)——通过: [@ cunglou/ 预写](https://github.com/chenglou/pretext); 权限 `` 是非CSS线的原始平衡 ## 路由器适配器 路由器 - 认识原始人(`Sidebar`, (中文(简体) ), `Link`, (中文(简体) ), `SSRPagination`,则 `useRouter` 编号 : `useNavigate` 编号 : `useLocation` 钩子) **可插入 适配器**,因此相同的组件在任何主机下工作. ui核本身是 路由器不可知并有 **零路由器依赖性** - 为您选择适配器 宿主并挂载它一次靠近根. ### 哪个主机的适配器 | 东道主 | 挂载这个 | 您安装的额外依赖 | | --- | --- | --- | | **下一个.js** (App路由器) (中文(简体) ) | `NextRouterAdapter` 从 `@djangocfg/ui-core/adapters/nextjs` | `next` (你已经拥有它) | | **维特/反应-鲁特SPA** | `ReactRouterProvider` 从 `@djangocfg/ui-core/adapters/react-router` | `react-router` **第7条** 加入你的应用软件 `dependencies` | | **哀号/电号/平正反应/故事本** | **无** — 默认历史- API 适配器被自动使用 | 无( 0 度) | `next` 财务报告和审定财务报表 `react-router` 为: **选项同伴**: 基包从不导入 他们。 只有匹配的子路径条目才有, 所以解析器已解析 _仅限_ 何时 输入适配器。 千万不要同时添加 —— 导入您的主机的子路径 . ### 上哪儿去装 两个供应商的适配器都包起子树; 里面的每一个ui-core路由器调用都流出 通过你的应用程序的路由器。 挂载 **一次**,靠近根: ```tsx // Next.js — inside the client provider stack (below your i18n provider) import { NextRouterAdapter } from '@djangocfg/ui-core/adapters/nextjs'; {children} // Vite / React-Router — INSIDE the router context (an element RouterProvider // renders, e.g. a layout route wrapping ), NOT around . import { ReactRouterProvider } from '@djangocfg/ui-core/adapters/react-router'; function Shell() { return ; } ``` > **反应 - 路特得到了查:** 正在安装 `ReactRouterProvider` _周围_ `` 抛出——子树没有路由器上下文,所以 `useNavigate` 失败。 总是挂起它 _内部_。 。 。 . ### 跳过会怎样 没有适配器,钩子就掉回 **默认历史- API 适配器** (单位:千美元)`window.history.pushState` + 键 `window.location`) (中文(简体) ). 这是故意的,而且很有效 到处都是零分,但是 _框架_ {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}它悄悄地失去了它 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}它会失去它 框架的路由行为 : - **下一个。 `NextRouterAdapter`数字 :** 导航上没有 RSC retract, 没有路由 装填器,不预取. 链接仍然更改 URL, 但是 App 路由器没有 反应 总是挂在下一个应用程序. - **反应-无路透器 `ReactRouterProvider`数字 :** 方案 `useNavigate` 编号 : `` 变异 `window.history` 直接绕过 `` 换,所以 数据路由器的导航解码器。 – 总是在RR SPA上挂起. 对于普通SPA(Wails/Electron/CRA),历史-API默认 _实值_ 右边 后端 – 挂载一无所有 . ### 链接适配器( 可选, Next.js) 默认 `` 从 `@djangocfg/ui-core/components` 做一个简单的 ``。 。 。 . 要将 Next 的预选 / RSC 处理通过它, 请挂载 `NextLinkProvider` 并行 `NextRouterAdapter`。对于地方前缀的树脂 `next-intl`,通过 `createNextIntlLinkAdapter(IntlLink)` 作为 `AppLayout`是因为 `linkAdapter` 都活下来了 内 `@djangocfg/ui-core/adapters/nextjs`。 。 。 . > **更深潜:** 完全适配器参考 `useRouter` 编号 : `useNavigate` 编号 : `useLocation` 编号 : `useQueryState` 钩子表面, 和一个~20行配方 **自定义** 路由器(TanStack路由器、wouter、Remix、自定义运输) [`src/hooks/router/README.md`](https://npmcn.com/package/%40djangocfg/ui-core/src/hooks/router/README.md)。 。 。 . > 使用 `@djangocfg/layouts`? 吗? `BaseApp` 已经为您挂载了下一个适配器 - 你不能用手电线. ## 赛明会`/styles`(中文(简体) ) 带有语义符号的 Tailwind v4, 而非生色平分 : ```tsx