# @asteby/metacore-ui 中文文档
规范地址：https://npmcn.com/package/%40asteby/metacore-ui/
版本：2\.32\.1
npm 元数据更新时间：2026-11-04T00:05:58.020Z
中文译文更新时间：2026-11-07T00:47:43.279Z
软件包许可：Apache-2\.0
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40asteby/metacore-ui
原文对照：https://npmcn.com/package/%40asteby/metacore-ui/?lang=original
源码仓库：https://github.com/asteby/metacore-sdk
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：1.1 MB，679 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：28 个
- peer 依赖：react \>=18，date-fns \>=3，react-dom \>=18，tailwindcss \>=4，react-i18next \>=13，react-hook-form \>=7，@tanstack/react-query \>=5，@tanstack/react-table \>=8，@tanstack/react-router \>=1\.100
- 首次发布：2026-04-20T20:25:12.920Z
- 最新版本发布：2026-11-04T00:05:57.843Z
- 近 30 天下载量：2127（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：58（近 12 个月 58 个）
## 中文简介
Metacore UI 工具包 — 数据表,布局外壳,命令菜单,钩子 y 原始 shadcn reutilizables
## 安装
```sh
npm install @asteby/metacore-ui
```
也可以使用：`pnpm add @asteby/metacore-ui`、`yarn add @asteby/metacore-ui`、`bun add @asteby/metacore-ui`
## README
# @asteby/metacore-ui (英语)
用于Metacore生态系统的可再使用的UI工具包:一个模块化的TanStack-Table数据表,一个外壳准备版式(侧边栏+头部+认证外壳),一个键盘驱动的命令调色板,钩子,对话框,以及一组被编织的shadcn/ui原始人——全部被构建在React 19,Tailwind 4和Radix的对照下.
## 安装
```bash
pnpm add @asteby/metacore-ui @asteby/metacore-theme react react-dom react-i18next \
@tanstack/react-router @tanstack/react-table @tanstack/react-query
```
有意松动同伴的依赖关系(反应) `>=18`坦斯塔克包 用于使用它们, `tailwindcss >=4`) (中文(简体) ).
## 快开始
导入 Tailwind 令牌 + shadcn 从 `@asteby/metacore-theme`,然后从相应的子路径取出组件:
```tsx
import { AuthenticatedLayout, AppSidebar, NavUser } from '@asteby/metacore-ui/layout'
import { DataTableToolbar, DataTablePagination } from '@asteby/metacore-ui/data-table'
import { CommandMenu } from '@asteby/metacore-ui/command-menu'
import { useTableUrlState } from '@asteby/metacore-ui/hooks'
import { Button, Input } from '@asteby/metacore-ui/primitives'
import { cn } from '@asteby/metacore-ui/lib'
```
## 子路径导出
| 条目 | 住在这里的东西 |
| --- | --- |
| `@asteby/metacore-ui` | 一切(避免——用子道来震树). |
| `@asteby/metacore-ui/data-table` | `DataTableToolbar`, (中文(简体) ), `DataTableBulkActions`, (中文(简体) ), `DataTableFacetedFilter`, (中文(简体) ), `DataTableViewOptions`, (中文(简体) ), `DataTablePagination`, (中文(简体) ), `DataTableColumnHeader`, (中文(简体) ), `FilterableColumnHeader`。 。 。 . |
| `@asteby/metacore-ui/layout` | `AuthenticatedLayout`, (中文(简体) ), `AppSidebar`, (中文(简体) ), `Header`, (中文(简体) ), `NavGroup`, (中文(简体) ), `NavUser`, (中文(简体) ), `TeamSwitcher`, (中文(简体) ), `ProfileDropdown`, (中文(简体) ), `OrganizationCard`。 。 。 . |
| `@asteby/metacore-ui/dialogs` | `ConfirmDialog`, (中文(简体) ), `LearnMore`, (中文(简体) ), `LongText`, (中文(简体) ), `PasswordInput`, (中文(简体) ), `SelectDropdown`, (中文(简体) ), `SkipToMain`。 。 。 . |
| `@asteby/metacore-ui/command-menu` | `CommandMenu` (路由-不可知论). |
| `@asteby/metacore-ui/hooks` | `useTableUrlState`, (中文(简体) ), `useDialogState`, (中文(简体) ), `useIsMobile`。 。 。 . |
| `@asteby/metacore-ui/primitives` | shadcn/ui原始语: `Button`, (中文(简体) ), `Input`, (中文(简体) ), `Dialog`, (中文(简体) ), `DropdownMenu`, (中文(简体) ), `Popover`, (中文(简体) ), `Command`, (中文(简体) ), `Select`, (中文(简体) ), `Sidebar`, (中文(简体) ), `Sheet`, (中文(简体) ), `Table`, (中文(简体) ), `Tabs`, (中文(简体) ), `Tooltip`, (中文(简体) ), `ScrollArea`, (中文(简体) ), `Sonner`, (中文(简体) ), `Form`, (中文(简体) ), `Textarea`, (中文(简体) ), `Switch`, (中文(简体) ), `Badge`, (中文(简体) ), `Avatar`, (中文(简体) ), `Checkbox`, (中文(简体) ), `Label`, (中文(简体) ), `Separator`, (中文(简体) ), `Skeleton`, (中文(简体) ), `Collapsible`, (中文(简体) ), `AlertDialog`。 。 。 . |
| `@asteby/metacore-ui/profile` | 详细页包(机动第一): `ProfileHeader`, (中文(简体) ), `SectionCard`, (中文(简体) ), `StatStrip`, (中文(简体) ), `DefinitionList`, (中文(简体) ), `RecordList`编号 :`RecordRow`, (中文(简体) ), `ContactLink`, (中文(简体) ), `EmptyState`, (中文(简体) ), `PillTabsList`编号 :`PillTabsTrigger`。 。 。 . |
| `@asteby/metacore-ui/lib` | `cn`, (中文(简体) ), `getPageNumbers`, (中文(简体) ), `getCookie`编号 :`setCookie`编号 :`removeCookie`, (中文(简体) ), `resolveColorCss`编号 :`resolveColorHex`编号 :`generateBadgeStyles`。 。 。 . |
`Button` 大小 : `default | sm | lg | icon` 加上选入室者 `comfortable` (h-11), (中文(简体) ), `comfortable-lg` (h-12) 和(h-12) `icon-comfortable` (大小为-11). 所有按钮都得到按下状态( E)`scale .98`,在 `prefers-reduced-motion`) (中文(简体) ). `Sidebar` 尊重可选主机变量 `--app-topbar-h`, (中文(简体) ), `--app-notice-h` (固定上铬)和 `--app-bottombar-h` (移动平面底部偏移);全部默认为0.
## 与应用程序内部脱钩
源代码应用程序中依赖 zustand 的多个组件 `auth-store`,一个 Vite 特定的 `api` 客户端,或 破旧路由器 `` 已通过道具重新设计接收数据:
- **`AppSidebar`** ——收到 `navGroups`, (中文(简体) ), `currentHref`, (中文(简体) ), `LinkComponent`, (中文(简体) ), `header`, (中文(简体) ), `footer`,以及 `isLoading` 作为道具(没有内部认证/导航获取).
- **`NavGroup`** 编号 : **`NavUser`** 编号 : **`ProfileDropdown`** ——不再从认证商店读取. `NavUser` 编号 : `ProfileDropdown` 接受孩子的菜单正文和可选的退出召回.
- **`CommandMenu`** ——收到 `navGroups`, (中文(简体) ), `onNavigate`选择 `onThemeChange` 而不是从 `useSearch` 编号 : `useTheme` / 硬码 `sidebarData`。 。 。 .
- **`AuthenticatedLayout`** 纯外壳 消费者将自己的提供者树(主题、i18n、查询客户端、网络锁子等)组成,并传出 `sidebar`, (中文(简体) ), `headerChildren`, (中文(简体) ), `topBanner`,以及 `widget` 插槽 .
- **`FilterableColumnHeader`** 具体应用软件 `date_range` 筛选类型和远程 `filterSearchEndpoint` 变体被移除,以避免拉入 `react-day-picker` 和一个HTTP客户端. `select`, (中文(简体) ), `boolean`, (中文(简体) ), `text`,以及 `number_range` 留下来.
故意特征 **没有** 销售商: `branch-switcher`, (中文(简体) ), `organization`, (中文(简体) ), `top-nav`, (中文(简体) ), `config-drawer`, (中文(简体) ), `notifications-dropdown`, (中文(简体) ), `ai-chat` ——这些专有应用,属于消费者应用.
## 状态、页眉、QR和分块控制
只有主题符号(应用程序设置调色板),键盘和屏幕阅读器准备:
```tsx
import { DataState, PageHeader, QrCodeFrame } from '@asteby/metacore-ui/shared'
import { SegmentedControl } from '@asteby/metacore-ui/primitives'
import { PillTabsList, PillTabsTrigger } from '@asteby/metacore-ui/profile'
// Every non-success state of a query-backed surface
// kinds: loading | empty | error | forbidden | offline | stale | partial | demo
Demo}
actions={}
overflowActions={[{ key: 'export', label: 'Exportar', onSelect: exportCsv }]}
/>
Abiertas
```
可选 i18n 键(西班牙语后退) : `data_state.`, (中文(简体) ), `data_state.retry`, (中文(简体) ), `page_header.more`, (中文(简体) ), `qr_frame.loading`, (中文(简体) ), `qr_frame.expired`, (中文(简体) ), `qr_frame.refresh`。 。 。 .
## 页面页眉,动作栏,PageShell和后链接(移动先行)
```tsx
import { ActionBar, BackLink, PageHeader, PageShell, type ActionItem } from '@asteby/metacore-ui/shared'
const items: ActionItem[] = [
{ key: 'dispatch', label: 'Despachar', priority: 'primary', run: dispatch },
{ key: 'edit', label: 'Editar', icon: , run: edit },
{ key: 'print', label: 'Imprimir', icon: , priority: 'overflow', run: print },
{ key: 'delete', label: 'Eliminar', destructive: true, confirm: { title: '¿Eliminar SO-00004?' }, run: remove },
]
Órdenes}
title='SO-00004' titleKind='identifier' subtitle={customerLink}
badges={Por surtir}
actions={}
/>
}>
{body}
```
`ActionBar` 规则(纯规划器导出为 `planActionBar` 适用于适配器/测试:
- **一个初级.** 第一个 `priority: 'primary'` 是唯一一个 `variant=default`;后被降为二级.
- **通过测量折叠,不仅仅是断点.** A 类 `ResizeObserver` 测量栏,并将二进制移入qq从尾到初级+二进制+qq适中. `maxVisible` (默认) `{ base: 2, md: 3, lg: 4 }`,初等包含,取景口断点)是上界和先漆计划. 栏从不包入两行;主行从不倒塌(取而代之的是其标签包入).
- **破坏性** 项从不向内渲染:它们最后在 qq 中,在分隔符后,在 `text-destructive`,并确认(`ConfirmDialog destructive`) 之前 `run`。通过 `confirm: false` 如果主机已经确认; 通过 `{ title, description, confirmLabel, cancelLabel }` 来定制.
- **过多** 从 `md` (768px, (英语), `MOBILE_BREAKPOINT`上并作下面的底板(`overflowAs='auto' | 'menu' | 'sheet'`) (中文(简体) ). 以下 `md`,带有 `icon` 仅转换图标( 有标签) 按钮使用44px `comfortable` 尺寸.
- `run` 可能返回一个承诺:按钮显示自旋器和其他动作锁定,直到它解决为止。 错误发生到 `onActionError` 或被重新驱逐. `disabledReason` 禁用动作并解释原因(桌面上的工具提示,菜单/表格中的文本).
- 栏中填充其父( :`w-full`内置大小的封装: 给它可能使用的房间.
`PageHeader` 以自己的宽度表示(`@container`:在448px下,它堆放领导~标题+徽章~动作;更宽,标题左(最大为60%,收缩)和动作右. `titleKind='identifier'` 保持单行/SKU(`truncate`,在 `title`(三); `text` (默认)包装。 标题大小为流体 (Y)`clamp(1.25rem, 1rem + 2vw, 1.5rem)`) (中文(简体) ). `overflowActions` 还在工作,但是 `ActionBar` 优先选择.
`PageShell` 是页面容器:单行沟 `px-4 sm:px-6 lg:px-8`, (中文(简体) ), `min-w-0`底部安全区, `@container/page`, (中文(简体) ), `width='narrow' | 'default' | 'wide' | 'full'`。 。 。 . `BackLink` 是一个44px «‹ Atrás",它使一个 ``页:1 `