# @almadar/ui 中文文档 规范地址：https://npmcn.com/package/%40almadar/ui/ 版本：6\.66\.0 npm 元数据更新时间：2026-10-14T09:10:35.665Z 中文译文更新时间：2026-11-06T15:25:43.037Z 软件包许可：BSL-1\.1 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40almadar/ui 原文对照：https://npmcn.com/package/%40almadar/ui/?lang=original 项目主页：https://github.com/almadar-io/almadar#readme 源码仓库：https://github.com/almadar-io/almadar-ui ## 关键信息（来自 npm 元数据） - 包体积（解压后）：21.1 MB，248 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：32 个 - peer 依赖：react \>=18\.0\.0，three ^0\.160\.0，postcss ^8\.4\.35，react-dom \>=18\.0\.0，tailwindcss ^3\.4\.0，react-router-dom ^7\.0\.0，@react-three/drei ^10\.7\.7，@react-three/fiber ^9\.0\.0，@tanstack/react-query ^5\.0\.0，@react-three/postprocessing ^3\.0\.0 - 首次发布：2026-02-04T23:38:08.351Z - 最新版本发布：2026-10-14T09:10:35.505Z - 近 30 天下载量：2911（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：723（近 12 个月 723 个） ## 中文简介 对应 Almadar 的 UI 组件、 钩和提供者 ## 安装 ```sh npm install @almadar/ui ``` 也可以使用：`pnpm add @almadar/ui`、`yarn add @almadar/ui`、`bun add @almadar/ui` ## README # 轨道设计系统 用于轨道应用的可主题,有域-意识组件库. 生成客户特定设计系统 `.orb` 计划. ## 特征 - **CSS 变量主题**: 所有组件都使用 CSS 变量, 方便主题切换 - **域检测**: 从计划自动检测域(花园、保健、金融等) - **构成部分建议**: 根据计划分析建议特定域的组件 - **故事书集成**: 带有主题切换的视觉组件文档 - **静态导出**: 导出用于客户端发送的静态 HTML 设计系统 ## 快速启动 ```bash # Install dependencies npm install # Start Storybook for development npm run storybook # Generate a client-specific design system npm run generate path/to/schema.orb ``` ## 可用主题 | 主题 | 说明 | 最佳服务 | | --- | --- | --- | | `wireframe` | 高对比度,尖锐的边缘 | 原型制作 | | `minimalist` | 柔软,优雅,微妙 | 公司应用程序 | | `almadar` | 特定品牌的样式 | Al-Madar项目 | | `winning-11` | 花园/有机主题 | 农业、自然 | ## 脚本 ### `npm run storybook` 在端口6006上启动故事本开发服务器. ### `npm run build-storybook` 构建静态故事书文档. ### `npm run generate [options]` 生成完整的客户特定设计系统. 选项 : - `--output ` - 输出目录(默认:./导出) - `--name ` - 客户名覆盖 - `--no-storybook` - 跳过故事书构建 - `--no-components` - 跳过组件生成 示例 ```bash npm run generate ../architecture/winning-11.orb --output ./clients ``` ### `npm run generate:theme [output.css]` 仅从计划生成主题 CSS . ### `npm run suggest:components [--generate ]` 分析计划并推荐特定域的组件. ## 构成部分库结构 ``` components/ ├── atoms/ # Basic building blocks │ ├── Button │ ├── Input │ ├── Badge │ ├── Card │ └── ... ├── molecules/ # Composite components │ ├── Alert │ ├── Modal │ ├── Tabs │ └── ... ├── organisms/ # Complex components │ ├── DataTable │ ├── Header │ ├── Sidebar │ └── ... └── templates/ # Page layouts ├── AuthLayout ├── FormTemplate └── ... ``` ## 他们 ### 使用主题 通过设置应用主题 `data-design-theme` 属性 : ```html ... ``` 或者在反应中: ```tsx
``` ### CSS 变量 所有组件都使用CSS变量进行主题: ```css /* Colors */ --color-primary --color-primary-hover --color-primary-foreground --color-secondary --color-secondary-foreground --color-accent --color-muted --color-muted-foreground --color-background --color-foreground --color-border /* Shadows */ --shadow-sm --shadow-main --shadow-lg --shadow-hover /* Border Radius */ --radius-sm --radius-md --radius-lg --radius-xl /* Transitions */ --transition-fast --transition-normal --transition-slow ``` ### 创建自定义主题 1. 在其中创建 CSS 文件 `themes/`数字 : ```css [data-design-theme="my-theme"] { --color-primary: #your-color; --color-secondary: #your-color; /* ... other variables */ } ``` 2. 导入 `themes/index.css`数字 : ```css @import './my-theme.css'; ``` 3. 添加到故事本预览( E)`.storybook/preview.tsx`: ```tsx themes: { // ...existing themes 'my-theme': 'my-theme', } ``` ## 特定域组件 生成器根据计划分析提出了特定域的组件: ### 花园/农业领域 - `GardenView` - 视觉花园布局 - `PlantCard` - 有护理指标的植物展示 - `GrowthMeter` - 增长进度指标 - `TrustMeter` - 信托/关系指标 - `CareIndicator` - 水/太阳/营养需要 ### 保健领域 - `PatientCard` - 病人信息显示 - `VitalsDisplay` - 重要标志紧凑视图 - `AppointmentSlot` - 时间安排部分 ### 电子商务领域 - `ProductCard` - 有价格和推车动作的产品 - `CartSummary` - 计算机概览 - `PriceTag` - 格式价格显示 ### 游戏域 - `CharacterStats` - 火箭筒式Stat显示器 - `QuestTracker` - 积极探索面板 ## 与提案文件合并 生成的设计系统可以包含在客户建议书中: 1. 生成设计系统 : ```bash npm run generate ../architecture/winning-11.orb --output ./exports ``` 2. 出口包括: - 主题 CSS 文件 - 组件根( 如果检测到域) - 故事书文档 - 用元数据表示 3. 在提案文件中提及或作为单独一揽子交付. ## 客户端特定组件 客户特有组件在以客户端命名的专用文件夹中直播. 这些组成部分: - **扩展核心库** - 使用现有的原子/分子,不要重现它们 - **跟随原子设计** - 分为原子、分子、生物、模板 - **包含故事书故事** - 每个部件必须有一个 `.stories.tsx` 文件 - **可重复使用** - 可用于同一客户的未来项目 ### 目录结构 ``` orbital-shared/design-system/ ├── components/ # Core component library (shared across all clients) │ ├── atoms/ │ ├── molecules/ │ ├── organisms/ │ └── templates/ ├── clients/ # Client-specific components │ ├── winning-11/ # Winning-11 client │ │ ├── atoms/ # Client-specific atoms (rare) │ │ ├── molecules/ # Client-specific molecules │ │ ├── organisms/ # Client-specific organisms │ │ ├── templates/ # Client page templates/showcases │ │ └── index.ts # Barrel export │ └── [other-client]/ # Another client folder └── ... ``` ### 何时创建客户端特定组件 | 假设 | 何处添加 | | --- | --- | | 对任何项目有用的通用组件 | `components/` (核心图书馆) | | 现有组件的特定域型 | 有组成的客户文件夹 | | 独特的业务逻辑组件 | 客户端文件夹 | | 页面模板/显示 | `clients/[name]/templates/` | ### 创建客户端特定组件 1. **在客户端文件夹中创建**数字 : ``` clients/winning-11/organisms/GardenLayout.tsx clients/winning-11/organisms/GardenLayout.stories.tsx ``` 2. **从核心库导入**数字 : ```tsx import { Card, Badge } from '../../../components/atoms'; import { Grid } from '../../../components/molecules'; ``` 3. **从客户端索引导出**数字 : ```tsx // clients/winning-11/index.ts export * from './organisms/GardenLayout'; ``` 4. **创建故事本故事**数字 : ```tsx // GardenLayout.stories.tsx import type { Meta, StoryObj } from '@storybook/react'; import { GardenLayout } from './GardenLayout'; const meta: Meta = { title: 'Clients/Winning-11/Organisms/GardenLayout', component: GardenLayout, }; export default meta; ``` ### 客户端模板 模板显示针对客户端的完整页面布局. 它们表明: - 组件如何组合 - 现实数据模式 - 特定品牌的样式 ```tsx // clients/winning-11/templates/GardenDashboard.tsx export const GardenDashboard = () => (
); ``` ### 同步到项目 生成客户端项目时, 将特定客户端组件复制 : ```bash npm run generate schema.orb --client winning-11 --output ../projects/winning-11 ``` 此副本: - 核心 `components/` 图书馆 - 客户专用 `clients/winning-11/` 文件夹 - 主题和钩子 ## 发展 ### 添加新组件 1. 在适当类别中创建组件( E)`atoms/`, (中文(简体) ), `molecules/`, (中文(简体) ), `organisms/`(中文(简体) ) 2. 创建相应的 `.stories.tsx` 文件 3. 从类别中导出 `index.ts` 4. 在故事书中校验 ### 添加新主题 1. 创建主题 CSS 在 `themes/` 2. 遵循 CSS 变量的现有主题结构 3. 添加导入到 `themes/index.css` 4. 添加到故事书主题选择器 ### 添加特定域组件 1. 添加域配置到 `scripts/suggest-components.ts` 2. 定义关键词和组件建议 3. 用此域的图谋进行测试 ## 常见问题 ### @almadar/ui 是什么？ 对应 Almadar 的 UI 组件、 钩和提供者 ### 如何安装 @almadar/ui？ 在项目目录运行 npm install @almadar/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）、react-router-dom（^7\.0\.0）、@tanstack/react-query（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @almadar/ui 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @almadar/ui 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @almadar/ui 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @almadar/ui 可以商用吗？ @almadar/ui 使用 BSL-1\.1 许可。声明的许可为 BSL-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。 ### @almadar/ui 的下载量有多少？ 根据 npm 官方下载统计，@almadar/ui 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,911 次，日均约 97 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @almadar/ui 还在维护吗？ 最新版本 6\.66\.0 发布于 2026/10/14（24 天前）；至今共发布 723 个版本，其中过去 12 个月发布了 723 个；首次发布于 2026/02/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。