# @bundu/ui 中文文档 规范地址：https://npmcn.com/package/%40bundu/ui/ 版本：0\.13\.0 npm 元数据更新时间：2026-11-05T14:13:06.875Z 中文译文更新时间：2026-11-08T19:50:59.177Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bundu/ui 原文对照：https://npmcn.com/package/%40bundu/ui/?lang=original 项目主页：https://github.com/mzizi-dev/packages-npm#readme 源码仓库：https://github.com/mzizi-dev/packages-npm ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.4 MB，250 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：5 个 - 首次发布：2026-07-03T06:17:07.713Z - 最新版本发布：2026-11-05T14:13:06.504Z - 近 30 天下载量：3735（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：14（近 12 个月 14 个） ## 中文简介 Bundu生态系统的营销UI工具包——Nyuchi实施Mzizi设计系统. 所有21个Mzizi彩色家族(7个矿物、7个遗产、7个实验性)在一个 -- -- 彩色\*命名空间、9步地表梯子、连接状态t ## 安装 ```sh npm install @bundu/ui ``` 也可以使用：`pnpm add @bundu/ui`、`yarn add @bundu/ui`、`bun add @bundu/ui` ## README # @bundu/ ui (英语) > Bundu生态系统的营销UI工具箱——编辑Astro的构件外加Mzizi活字牌上的Shadcn风格回放原始(所有21个彩色家族). [![npm](https://img.shields.io/npm/v/%40bundu%2Fui?style=flat-square&logo=npm)](https://www.npmjs.com/package/@bundu/ui) [![Lint](https://img.shields.io/github/actions/workflow/status/mzizi-dev/packages-npm/lint.yml?branch=main&label=lint&style=flat-square)](https://github.com/mzizi-dev/packages-npm/actions/workflows/lint.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT) **重现 :** [mzizi-dev/packages-npm (英语:](https://github.com/mzizi-dev/packages-npm) | **结构 :** [mzizi.dev (英语)](https://mzizi.dev/) * * * ## 这是什么 销售站点背后的共享组件层(bundu, nyuchi, mukoko). 这是Nyuchi执行 [姆齐兹](https://mzizi.dev/) 设计 - Bundu基金会的一个开放建筑项目,运营和 由Nyuchi开发。 这个包裹不是Mzizi本身. - **Astro营销组件** —— 说 `Hero`, (中文(简体) ), `Section`, (中文(简体) ), `SectionHeader`, (中文(简体) ), `Container`, (中文(简体) ), `MineralStrip`, (中文(简体) ), `Icon`, (中文(简体) ), `SocialIcon`,以及 `Breadcrumb` (emits 有效计划.org) `BreadcrumbList` JSON-LD for Google rich results. (原始内容存档于2018-09-27). - **Astro形式和媒体组件** —— 说 `SegmentedControl` (本地无线电), `NativeSelect`, (中文(简体) ), `Toaster` (单位:千美元)`window.toast()` )和 `SafeAreaFrame` (几何学: `safeAreaBands` 从软件包根中导入,以 `@bundu/ui/.astro`,除登记原始人 `Alert`, (中文(简体) ), `Button`, (中文(简体) ), `Card`, (中文(简体) ), `Input`, (中文(简体) ), `Label`, (中文(简体) ), `Skeleton` 财务报告和审定财务报表 `StatusBadge`各自保持其登记册 合同(`contracts/ui/`); 应用模式处于下 `@bundu/ui/app/*` (下关. - **Markdown,通过建筑安全** —— 说 `MarkdownRenderer` (单位:千美元)`@bundu/ui/MarkdownRenderer.astro`, (中文(简体) ), 合同 `ui/markdown-renderer`) (中文(简体) ). 它解释 `content` 绘制成 元素,从不通过 HTML 字符串。 源代码中的 Raw HTML 显示为文本, 链接通过 方案允许列表( :`links="safe"`、默认值、保存 https、 https、 mailto、 电话和相对 地址; `links="https"` 仅保留 https; 拒绝的链接保留其单词. `from="html"` 或者说 `"auto"` 阅读编辑的丰富文本 `headingBase` 设置关卡 a `#` 标题 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你还好吧? 它从中吸取的解析器是 `@bundu/ui/markdown-parse`数字 : `markdownBlocks()`, (中文(简体) ), `safeHref()` 和块和内线类型, 对于代码需要树,而不是标记. ```astro --- import MarkdownRenderer from "@bundu/ui/MarkdownRenderer.astro"; --- ``` - **阴影 CVA + `cn()` 反应原始人** —— 说 `Button`, (中文(简体) ), `Card`, (中文(简体) ), `Badge`, (中文(简体) ), `Input`, (中文(简体) ), `Textarea`, (中文(简体) ), `Select`, (中文(简体) ), `Label`, (中文(简体) ), `Alert`, (中文(简体) ), `Avatar`, (中文(简体) ), `Separator`, (中文(简体) ), `Skeleton`, (中文(简体) ), `Switch`, (中文(简体) ), `Checkbox`, (中文(简体) ), `Tabs`, (中文(简体) ), `Tooltip`。 。 。 . - **整个Mzizi调色板** —— 说 `styles/tokens.css` 全部携带 **21个有色家庭** 在一个下 `--color-*` 命名空间:7个矿物,7个遗产色调,7个实验色调. 加九步地表梯(`--pitch`, (中文(简体) ), `--void`, (中文(简体) ), `--base`, (中文(简体) ), `--surface`, (中文(简体) ), `--container`, (中文(简体) ), `--overlay`, (中文(简体) ), `--raised`, (中文(简体) ), `--scrim`, (中文(简体) ), `--wash`)和连通性 状态三进制( r)`--syncing`, (中文(简体) ), `--offline`, (中文(简体) ), `--neutral`) (中文(简体) ). - **尾风 v3 和 v4** —— 说 `styles/theme.css` 是一个本地 v4 `@theme` 入场点; `tailwind-preset.mjs` 是 v3- 形状的预设, 仍在发运并仍在工作( v4 载重) 它穿过 `@config`) (中文(简体) ). - **品牌覆盖** —— 说 `brand-bundu`, (中文(简体) ), `brand-nyuchi`, (中文(简体) ), `brand-mukoko`, (中文(简体) ), `brand-shamwari`, (中文(简体) ), `brand-mzizi`和子应用程序 `brand-events` (木科克事件), `brand-lingo`, (中文(简体) ), `brand-bushtrade`, (中文(简体) ), `brand-campfire`, (中文(简体) ), `brand-news`, (中文(简体) ), `brand-weather`, (中文(简体) ), `brand-kweli`, (中文(简体) ), `brand-learning` 财务报告和审定财务报表 `brand-circles` (木科克圆. `brand-nhimbe` 是再出口的已贬值的别名 `brand-events` (nhimbe品牌已退役;事件平台为Mukoko事件). 每个重点 `--primary` 财务报告和审定财务报表 `--ring` 矿物质来自 克能生态系统表. `brand-circles` 另设 `--brand-accent` (特拉科塔语), 哪个牌子的手杖排着一个口音. - **`tokens.json`** ——机器可读值相同,包括每个自定义属性 对于完全无法消耗 CSS 的表面, 解为每个模式的字面六进制 : 博览会( E)`mukoko-weather-mobile`)和以佐藤里为主的OG-图像/电子邮件/PDF生成器. ## 生成, 不转录 `styles/tokens.css`, (中文(简体) ), `styles/theme.css`, (中文(简体) ), `tokens.json`, (中文(简体) ), `tailwind-palette.mjs` 和每个 `styles/brand-*.css` 为: **生成** 以 `scripts/generate-tokens.mjs` 从 `tokens/canon.snapshot.json`,它本身是机器写 `scripts/fetch-canon.mjs` 从划道上 : | 来源 | 用品 | | --- | --- | | `https://api.mzizi.dev/api/v1/brand` | 21个家庭,语义符号,背景阶梯,光线,品牌-矿表 | | `mzizi-dev/mzizi-registry` → `lib/tokens/palette.source.ts` | 矿物 `onContainer` 成对, 哪个 `/v1/brand` 不预测 | 两人在每逢交接的时候,都要互相考核。如果他们对一击有分歧, 获取失败 而不是默默地偏爱它。 这种分歧就是遗产 最后是四个不同的地铁. 十六进制值 **没有** 生活在数据库中。 Mzizi没有品牌或原始的象征数据 在Supabase或其他任何地方——0.1.1's `tokens.css` 信头说错了. 三道城门,都不得空出: | 命令 | 网络 | 运行 | 失败的时间 | | --- | --- | --- | --- | | `pnpm tokens:check` | 没有 | 每一个CI工作, `prepack` | 生成的文件与生成器不一致 | | `pnpm canon:parity` | 对 | **仅CI** | 承诺的快照已经从活的峡谷飘来飘去 | | `pnpm canon:fetch` | 对 | 需求 | aPI和 `palette.source.ts` 异议 | `canon:parity` 拒绝在CI以外运行 `--force`因此它不能爬入建筑物 或运行时路径。 手机回家制作一个页面的标志性软件包是一页 aPI的下午是空白的,情况不妙. 每个值都通过 CSS 自定义属性来流动 / Tailwind sords —— **从来没有生六分之一英寸 来源**。 。 。 . ## 安装 ```sh pnpm add @bundu/ui # peer deps (for the React primitives) pnpm add react react-dom ``` ## 快速使用 **1a. 尾风v4(建议)** - 一个样式表,没有 `tailwind.config.mjs` 完全没有: ```css @import "tailwindcss"; @import "@bundu/ui/styles/theme.css"; /* @imports tokens.css, adds @theme */ @import "@bundu/ui/styles/globals.css"; /* the @layer rules the Astro components use, and density.css */ @import "@bundu/ui/styles/color-scheme.css"; /* optional: follow the OS dark setting */ @import "@bundu/ui/styles/brand-nyuchi.css"; @source "../../node_modules/@bundu/ui/src"; /* v4 does not scan node_modules itself */ ``` `color-scheme.css` 选择进入. `tokens.css` 只变暗 `.dark` 或者说 `[data-theme="dark"]`,此文件在 `prefers-color-scheme: dark`,用于没有主题脚本的网站。 明确 `data-theme="light"` 仍然赢了。 在品牌覆盖前导入. `theme.css` 搭载调色板、类型比例(`text-display` . `text-caption`页:1 读取宽度( r)`max-w-narrow`和命名的间隔,所以 `globals.css`是因为 `@apply` 规则 而组件的类解而无预设。 尾风进口 `tokens.css` 一次 尽管两个文件都提到它。 Astro组件使反应原生 (例如 `Hero`按钮,所以一个Astro网站也需要 `@astrojs/react`没有 `client:*` 他们向静态 HTML 提供指令, 并且没有JavaScript . **平地和密度.** `globals.css` 进口 `styles/density.css`从 登记:正文文本 17px, 标题 14px, 每个控件上的49px击出区域( 控件可能 在桌面密度下绘制 28-40px,以及 a `hit-area` 覆盖保持49px命中区域, 以及作为公用事业的部件的作用大小(`h-control`, (中文(简体) ), `h-control-sm`, (中文(简体) ), `h-control-lg`, (中文(简体) ), `size-control-icon`, (中文(简体) ), `h-field`, (中文(简体) ), `min-h-touch-min`) (中文(简体) ). 这些公用设施解决了 没有它,什么都没有。 将棋子分别导入的应用程序( Q)`theme.css` 财务报告和审定财务报表 `tokens.css`,没有 `globals.css`必须在其后面加上: ```css @import "@bundu/ui/styles/theme.css"; @import "@bundu/ui/styles/density.css"; ``` `` 恢复地板前的尺寸( 16px 身体, 12px) 标题, 48/ 56px 控件), 直到一个应用程序迁移 。 移民表:mzizi-注册 `docs/sizes-and-density.md`。 。 。 . **1b. 有尾风v3或v4通过 `@config`** - 与0.1.x不变,仍然支持: ```css @import "tailwindcss"; @import "@bundu/ui/styles/tokens.css"; /* or globals.css for the @layer rules */ @import "@bundu/ui/styles/brand-nyuchi.css"; @config "../../tailwind.config.mjs"; ``` ```js // tailwind.config.mjs import preset from "@bundu/ui/tailwind-preset"; export default { presets: [preset], content: ["./src/**/*.{astro,html,js,jsx,md,mdx,ts,tsx,vue}"], }; ``` **2\. 浏览器外部** - 博览会、佐藤里会、PDF: ```js import tokens from "@bundu/ui/tokens.json" with { type: "json" }; tokens.resolved.dark["--color-sodalite"]; // "#3d5afe" tokens.color.heritage.savanna.dark; // "#e5c158" tokens.surface.base.light; // "#f3f3f1" ``` **3\. 组件:** ```astro --- import Hero from "@bundu/ui/Hero.astro"; import Container from "@bundu/ui/Container.astro"; import MineralStrip from "@bundu/ui/MineralStrip.astro"; import Breadcrumb from "@bundu/ui/Breadcrumb.astro"; import { deriveBreadcrumbs } from "@bundu/ui"; const crumbs = deriveBreadcrumbs(Astro.url.pathname, { about: "About" }, "Nyuchi"); --- ``` ```tsx import { Button } from "@bundu/ui/ui/button"; import { Alert, AlertTitle } from "@bundu/ui/ui/alert"; export function CTA() { return ( <> Saved ); } ``` ## 英雄们 ```astro --- import Hero from "@bundu/ui/Hero.astro"; ---
``` | Prop | 类型 | 默认 | 页:1 | | --- | --- | --- | --- | | `title` | `string` | —— 说 | 这个 `h1`。 。 。 . | | `subtitle` | `string` | —— 说 | 眉从头而上. | | `description` | `string` | —— 说 | 分文一段. | | `primaryCTA` | `{ text, href, external? }` | —— 说 | 药扣. | | `secondaryCTA` | `{ text, href, external? }` | —— 说 | 以一箭为鬼扣. | | `variant` | `"default" | "gradient" | "light" | "showcase"` | `"default"` | `showcase` 洗了这个牌子 `--primary` 和钴过 `--background`; 只有符号. | | `align` | `"start" | "center"` | `"start"` | | | `layout` | `"stack" | "split"` | `"stack"` | `split` 设置文本和 `media` 位置并肩从 `lg`。 。 。 . | | `badge` | `string` | —— 说 | 头条上面的状态药丸 它被理解为权利主张,所以要准确. | | `mediaLabel` | `string` | —— 说 | 媒体区域无障碍名称(`role="group"`) (中文(简体) ). | | `media` (分数) | 标记 | —— 说 | 文本列旁或下方的(分块). | 没有 `media` 插槽,没有 `badge`, (中文(简体) ), `layout` 左侧 `stack` 和一个0.1.x `variant`, (中文(简体) ), `Hero` 调制 **字节相同** 标记为0.1.1。 每一个建筑都检查过了 与公布的0.1.1 焦油球相配合. 见 [建 议.md](https://github.com/mzizi-dev/packages-npm/blob/main/packages/bundu-ui/BUILDING.md) 用于完整的工具链——mzizi MCP、shadcn CLI、 21个有色人种,和"无生克"规则. ## App图案 (0. 3. 0) 服务器为已登录的应用程序和控制台提供组件 `@bundu/ui/app/*`他们是 **纯天体**: 无反应( 或任何框架) 他们和没有客户JavaScript, 正如Mzizi学说有它为Astro。 过滤器 是获取表单, 调用是链接, 菜单是 `
`祝酒词被取消 带有隐藏复选框标签。 每个颜色都是一种标志, 所以光和暗 跟着 `tokens.css` 编号 : `color-scheme.css`。分类食谱与 反应原始人通过 `@bundu/ui/ui/variants`,所以两个建筑看起来都是一样的. | 构成部分 | 它会做什么 | | --- | --- | | `AppShell.astro` | 粘性顶条( R)`brand`, (中文(简体) ), `account` 边栏导航 `lg` 和下面的披露, `main#main` | | `SideNav.astro` | 附有标签和摘要的部分清单; `aria-current="page"` 关于当前项目; 48px目标 | | `AccountMenu.astro` | 签名者、 账户动作的插槽( 外观窗体、 链接) 和签出 POST 格式 | | `PageHeader.astro` | 这页是一页 `

`描述,面包屑, `actions` 插槽 | | `DataTable.astro` | 真实的 `` 带有标题和范围标题; 窄屏幕上每行一张牌; 单元格是数据而不是标记 | | `FilterBar.astro` | 搜索并选择过滤器为 a `role="search"` 获取窗体; 设置时“ 清除 ” | | `Pagination.astro` | "显示112的26-50"和上个,编号和下个链接;当一个页面足够时隐藏 | | `DetailPanel.astro` | 一个记录作为描述列表,一个可选的"全面记录"JSON披露,一个 `actions` 插槽 | | `FormLayout.astro` | 有标题的表单卡;卡宽时分出两个栏(容器查询);表单级别提醒; `enctype` 用于文件 | | `FormField.astro` | 可见标签和一个输入(文本、数字、日期、文件.)、文本区域或选择,并带有提示和有线错误 `aria-describedby` 财务报告和审定财务报表 `aria-invalid`· ; `wide` 横跨两列 | | `StateMessage.astro` | 空、 出错、 不配置、 不可用和装入( skeleton) 有固定措辞的状态 | | `Toast.astro` | 最后一项行动的结果是:一个有礼貌的居住区;在被解雇之前继续居住(WCAG 2.2.3) | | `StatTile.astro` | A 中的一个标题图 `
`: 标签, 值 ("不可用", 从不可用 0) 以文字写成的趋势 | | `BarChart.astro` | 列或行为 SVG, 标题 `
`,从不拥挤的轴线标签,以及披露下真实表格中的确切数字 | | `Button.astro` | `` 与 `href`,则 `