@djangocfg/ui-core (英语)
框架-不可知回放 UI 库: 在 Tailwind v4 上 70+ shadcn/ Radix 组件,语义主题符号, Canvas/SVG 的调色板钩子, 加上一个允许相同的路由器-适应器系统 <Link> 编号 : <Sidebar> 编号 : <SSRPagination> 在Next.js、Vite、Electron、Wails或Plain React下工作.
安装
pnpm add @djangocfg/ui-core
在任何反应主机工作. Next.js apps 从这里直接导入组件和
添加下一个路由器适配器 @djangocfg/ui-core/adapters/nextjs (见
路由器适配器 (见下文); 下个具体 服务器 公用事业(用品、保健、,
OG 图像, 配置) 分别存在 @djangocfg/nextjs 软件包.
曾经在app root 导入样式—— 使用金色路径, 它将所有的东西都钉上 到右级联层, 这样导入顺序不能打破布局功能 :
/* 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。 。 。 .
快开始
import { UiProviders, Button, Card } from '@djangocfg/ui-core';
<UiProviders>
<Card><Button>Hello</Button></Card>
</UiProviders>
<UiProviders> 按照正确的顺序挂载工具提示/ 对话框/ 标签 和顶级错误 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。 。 。 .
MoneyField 带一个数量作为整数小单位,而不是一个浮点——见
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) 在一个方案下写作, <owner>.<area>.<name>,比如说.
cfg.ui.sidebar_width, (中文(简体) ), kino.player.volume。关于代理人的完整规则:
@djangocfg/api → @docs/STORAGE_KEYS.md。 。 。 .
- 已经遵循该计划的密钥被沿用至今.
- 赤名( bare
'search-filter'折叠为snake_case并放进 活动所有者 :cfg.ui.search_filter主人是钩子namespace选项,否则最接近<StorageNamespaceProvider owner="kino">,否则 框架默认cfg。 。 。 . - 配额回收只减少我们计划的非个人钥匙, 从来不是象征性的,
草稿、配置文件或第三方密钥(
NEXT_LOCALE) (中文(简体) ).
// app root, once
<StorageNamespaceProvider owner="kino">…</StorageNamespaceProvider>
// 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/ 预写; 权限<BalancedText>是非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路由器调用都流出 通过你的应用程序的路由器。 挂载 一次,靠近根:
// Next.js — inside the client provider stack (below your i18n provider)
import { NextRouterAdapter } from '@djangocfg/ui-core/adapters/nextjs';
<NextRouterAdapter><AppLayout>{children}</AppLayout></NextRouterAdapter>
// Vite / React-Router — INSIDE the router context (an element RouterProvider
// renders, e.g. a layout route wrapping <Outlet/>), NOT around <RouterProvider>.
import { ReactRouterProvider } from '@djangocfg/ui-core/adapters/react-router';
function Shell() {
return <ReactRouterProvider><Layout><Outlet /></Layout></ReactRouterProvider>;
}
反应 - 路特得到了查: 正在安装
ReactRouterProvider周围<RouterProvider>抛出——子树没有路由器上下文,所以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编号 :<Link>变异window.history直接绕过<Outlet/>换,所以 数据路由器的导航解码器。 – 总是在RR SPA上挂起.
对于普通SPA(Wails/Electron/CRA),历史-API默认 实值 右边 后端 – 挂载一无所有 .
链接适配器( 可选, Next.js)
默认 <Link> 从 @djangocfg/ui-core/components 做一个简单的 <a>。 。 。 .
要将 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。 。 。 .
使用
@djangocfg/layouts? 吗?BaseApp已经为您挂载了下一个适配器 - 你不能用手电线.
赛明会/styles(中文(简体) )
带有语义符号的 Tailwind v4, 而非生色平分 :
<Card className="bg-card border-border text-foreground" />
<Button className="bg-primary text-primary-foreground" />
<Alert className="bg-warning-background text-warning-foreground border-warning-border" />
托肯斯住在这里 :root 编号 : .dark 与完全包装的CSS颜色一样; @theme inline 把他们暴露为 --color-X 参考文献,因此不透明bg-card/40, (中文(简体) ), border-foreground/20解决途径 color-mix 页:1 每个 语义符号.
预设文本/填充配对针对紧凑产品UI的WCAG AA. 对于macOS
预设此选项由 pnpm check:contrast; 主要和破坏性
在系统所在的浅墨和深墨之间故意切换前景
填充的光辉需要它.
@custom-variant dark (&:where(.dark, .dark *)) 绑定 dark: 改为: .dark 课开始 <html> (无) prefers-color-scheme)——这个单调的每个主题切换器都切换出那个类.
尾风 text-* 大小的公用设施已连接到预设 --font-size-* 缩放。 产品特有密度在静态预设导入后属于小的 CSS 覆盖- 从未在运行时符号构建器中. 见 src/styles/README.md。 。 。 .
类型尺度. 平面 text-xs … text-xl 身体大小来自
预设 --font-size-* (macOS预设为13/12/11px,默认为14/13px). 消费
应用必须 没有 重设 :root --font-size-* - 这让相同 text-sm
产品之间有所不同,并挫败了共享主题. 产品专有名称
(单位:千美元)text-meta, (中文(简体) ), text-body属于应用程序本身 @theme,而不是在覆盖中
基准尺度.
重叠. bg-overlay 山地是山地;地上霜冻 --overlay-blur
(默认) 5px, (中文(简体) ), 0px / 禁用). 只有无前缀 backdrop-filter 实值
写是因为闪电增加了 -webkit- 本身并丢弃未加前缀的
当两者都存在时。 模糊的地表需要半透明的背景 什么都没有
在一个有 backdrop-filter 可以模糊其背后的一页——
打开它 body细节 : src/styles/README.md § 重叠和玻璃.
程序主题颜色 用于 Canvas / SVG / 美人鱼 :
import { useThemeColor, alpha, useStylePresets } from '@djangocfg/ui-core/styles/palette';
const primary = useThemeColor('primary'); // #00d9ff (hex, not oklch)
const dim = alpha(primary, 0.15); // 'rgba(0, 217, 255, 0.15)'
const { success, warning, danger } = useStylePresets();
总是六弦弦 -- color-mix(...) 编号 : oklch(...) 语法被 Canvas2D fillStyle 拒绝.
现场操场 覆盖了所有的代币,预设和暗模相配.
扶养规则
在对组件或钩子进行任何修改后——更新这个README并撞出包补丁版本. 消费者针入npm版本;此文件中的表面漂移是cononical changlog.
所需资源
- 反应 18 或 19
- 尾风 CSS v4( 主机导入)
@djangocfg/ui-core/styles(中文(简体) )
许可证
麻省理工学院 - djangocfg.