# @feugene/granularity 中文文档规范地址：https://npmcn.com/package/%40feugene/granularity/ 版本：3\.7\.2 npm 元数据更新时间：2026-10-28T18:37:41.340Z 中文译文更新时间：2026-11-14T15:13:20.175Z 软件包许可：LicenseRef-Granularity-EUC-1\.1 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。原始 npm 页面：https://www.npmjs.com/package/%40feugene/granularity 原文对照：https://npmcn.com/package/%40feugene/granularity/?lang=original 项目主页：https://efureev.github.io/granularity 源码仓库：https://github.com/efureev/granularity ## 关键信息（来自 npm 元数据） - 包体积（解压后）：11.8 MB，1390 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：1 个 - peer 依赖：vue ^3\.5\.0，@feugene/granum \>=3\.10\.0 \<4\.0\.0，@floating-ui/dom ^1\.8\.0，@feugene/fint-i18n \>=0\.9\.0 \<1\.0\.0 - 首次发布：2026-04-17T12:58:17.583Z - 最新版本发布：2026-10-28T18:37:40.535Z - 近 30 天下载量：4932（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：117（近 12 个月 117 个） ## 中文简介具有Vue 3组件的外观设计系统包,通过 `@feugene/granum` 修建管道. ## 安装 ```sh npm install @feugene/granularity ``` 也可以使用：`pnpm add @feugene/granularity`、`yarn add @feugene/granularity`、`bun add @feugene/granularity` ## README # `@feugene/granularity` `@feugene/granularity` 是一个 `Vue 3` 设计系统软件包,帮助您更快、更清洁和更多构建界面可以预测:有现成的部件、透明的造型系统、颗粒进口和建造运输机器生成的货单而不是设置指令. 它是为设计系统需要不仅仅是一组UI部件 ——工作工程而建造的工具:对于一个产品团队来说是方便的,对于一个大应用程序来说是可扩展的,对于不同的采用来说是足够灵活的战略. ## 为什么它存在 - 在单一的视觉基础上推出新的屏幕和功能; - 逐步采用软件包,不改写整个应用程序; - 来控制 `JS` 财务报告和审定财务报表 `CSS` 船,当它真正重要; - 既可以使用同一软件包作为现成组件库,也可以作为低等软件包级API的来源. ## 为什么 `granularity` 不错 - **快速开始没有不必要的魔法.** 只需导入组件和现成的样式入口即可. - **颗粒进口.** 每个组件都是自己的子路径导出, 所以捆绑背负的正是你导入, 旁边没有. - **出自"圣德"风格.** 托肯斯(tokens),基底样式,主题,和组件级CSS被分出为清晰的地层. - **准备真正的规模.** 该软件包用于“只是插入几个组件”以及情景: 具有依赖意识的进口、安全清单和精确的CSS管道调试物质. - **一个插件, 不扫描 .** 货船 `granum.manifest.json`班级消耗的代币, 依赖性、主题文件和组件 CSS 在构建软件包时进行计算,所以应用程序读取它们而不是扫描 `node_modules`。。。 . - **不只是组件.** 除了UI之外,您还获得指令、文件验证 API 和工具条目基础设施设想. ## 技术要点 - 根导出 : `@feugene/granularity` ——插件,可堆肥,公用设施,常数和类型. 部件来了他们的子道: `granum`,从根部导入的组件是 `ComponentRootImportError`, (中文(简体) ), 因为选择只能从它的子路径看到一个组件,而根会加载整个包; - 组件子路径导出 : `@feugene/granularity/components/`· ; - 现成CSS入口: `@feugene/granularity/styles.css` - 那个 `slate` 两种模式中的主题 (单位:千美元)`light`, (中文(简体) ), `dark`) 核心组件符号和基层在一个文件中,供消费者使用不要运行建设管道。一个模式被对对切换 `data-theme="slate-dark"`A级组件自己的 CSS 不存在 : `granum` 它从仪表里出来; - 低级基础出口:按部别排列目录的现成主题—— `@feugene/granularity/themes//root.css` 加号 `themes//.css` 用于您需要的模式—— 或整个模式, `themes/.css`· ; `@feugene/granularity/styles/base.css`, (中文(简体) ), `@feugene/granularity/styles/preflight.css`· ; - 软件包级 API : `@feugene/granularity/directives`, (中文(简体) ), `@feugene/granularity/fileValidation`· ; - 设计符号作为数据: `@feugene/granularity/tokens`; 全球符号、主题数据和主题构建者生活在 [`@feugene/granularity-tokens`](https://npmcn.com/package/%40feugene/granularity-tokens/README.md),该套件的依赖性; - 构建列表 : `@feugene/granularity/granum.manifest.json` - 申请是什么 `granum()` 插件读取;它也记录各类所属的实用词汇 `engine` 块。这个供应商登记处本身作为 `@feugene/granularity/granular-provider` 页:1 包可以扩展它. ## 限制 **RTL 不被支持 .** 部件本身有物理方向(`pl-`编号 :`pr-`, (中文(简体) ), `ml-`编号 :`mr-`, (中文(简体) ), `left-`编号 :`right-`),以及 `dir="rtl"` 无法在任何地方读取:右到左文档将制取镜像粘贴、相抵和浮动面板。这是有意决定 `1.x` 线条 — 移动到逻辑属性会改变每个组件的外观, 也就是视觉断开更改并属于主发布,而不是补丁。见 [`docs/styling.md`](https://npmcn.com/package/%40feugene/granularity/docs/styling.md)。。。 . ## 快开始 ```bash yarn add @feugene/granularity vue @floating-ui/dom ``` `@floating-ui/dom` 是一个需要的对等依赖,而不是捆绑的:每个浮面板——选择, 菜单、工具提示、弹出器 —— 被定位在它的位置上, 所有使它变成一个的(数据) 也一样表格、页形、侧边栏、取色器; 从包根导入总是拉出进来没有它,应用程序的构建无法解决从 `dist/composables/useFloating.js`。保持外部表示已经使用的应用程序活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活. 叠加组件`GrModal`, (中文(简体) ), `GrDrawer`, (中文(简体) ), `GrDialog`, (中文(简体) ), `GrImageViewer`) 不需要其他东西—— 他们的焦点陷阱,层叠和卷轴锁是包自己的原始. `@headlessui/vue` 于0.15.0中投放,不是同位相依;如果仅为这个软件包安装, 它可以被删除. 支持的设置是 `granum` 插件 : ```bash yarn add -D @feugene/granum @feugene/granum-engine-wind ``` 两个包,不是一个: `granum` 是管道和船只没有自己的通用发动机,所以应用程序选择词汇表,并移交实例. `@feugene/granum-engine-wind` 这是默认执行 - `preset-wind3` 加上附加规则组件被绘制. ```ts // granum.config.ts import { defineGranumConfig } from '@feugene/granum/vite' import { windEngine } from '@feugene/granum-engine-wind' export default defineGranumConfig({ engine: windEngine(), providers: ['@feugene/granularity'], appSources: { dirs: ['src'] }, }) ``` 该软件包宣布其类的词汇被写作反对—— `unocss/preset-wind3+granum@66`。有不同方言的引擎会 `granum` 报告 `provider-dialect-mismatch` 并命名它必须掉下的每一类,而不是让组件变成半型。见 [`docs/granum.md`](https://npmcn.com/package/%40feugene/granularity/docs/granum.md)。。。 . ```ts // src/main.ts import 'virtual:granum.css' ``` 单模块包含五个级联层: 符号、基础、主题、组件的CSS 选中的, 以及它们创建的功能类 . 部件是从它们的子路径导入的: ```vue ``` 没有插件,仍然有静态回落—— `@feugene/granularity/styles.css` 以物证, 基础层、飞行前和内置 `light`编号 :`dark` 主题。它不携带的是工具类,所以组件用自己的CSS来渲染,但没有布局. ## 颗粒进口,数量 | 您导入的 | 齐普 | 枪管 | | --- | --- | --- | | 来自根的整个软件包 | 646.5千贝 | 100% | | 最轻的部件—— `GrSkeleton` | 1.7千贝 | < 1% (中文(简体) ) | | 中间部分 - `GrTextarea` | 19.5千贝 | 3% 妇女 | | 五个最重的在一起 | 251.8千贝 | 占39%(含) | 这些数字 **不要加起来**:共享代码在每行中再次被计算,但支付一次,这就是为什么组合显示为结合而非和. 它们是一个上界,是万物的分道扬镳离开 `dist`,在应用程序捆绑器进一步摇动并再修改之前. 每个组成部分的重量—— [`docs/entry-sizes.md`](https://npmcn.com/package/%40feugene/granularity/docs/entry-sizes.md)。。。 . ## 其余的家属核心船为通用部件。任何具有严重依赖性的东西,属于 ,或少数消费者需要生活在一个配套的套装中 `peer` 在这张上,核心保持倾斜, 你只安装你伸手要的东西. | 软件包 | 版本 | 上面写的 | | --- | --- | --- | | [`@feugene/granularity-charts`](https://npmcn.com/package/%40feugene/granularity-charts) | 4.0.0 (单位:千美元) | 图表——自有SVG,零依赖,以主题符号绘制. | | [`@feugene/granularity-chrono`](https://npmcn.com/package/%40feugene/granularity-chrono) | 4.0.1 (中文(简体) ) | 日历,日期和时间组件——没有第三方日期部件,没有日期库. | | [`@feugene/granularity-code`](https://npmcn.com/package/%40feugene/granularity-code) | 4.0.1 (中文(简体) ) | 代码表面:取景,编辑和diff——取景器和diff完全没有依赖性. | | [`@feugene/granularity-dashboard`](https://npmcn.com/package/%40feugene/granularity-dashboard) | 3.0.1 (中文(简体) ) | 部件网格——拖动,调整大小,断点和布局持久性,零依赖. | | [`@feugene/granularity-datasource`](https://npmcn.com/package/%40feugene/granularity-datasource) | 0.1.2 (中文(简体) ) | 列表状态: 排序、过滤、呼呼、 URL 同步和无种族获取到一个可堆叠的后面 . | | [`@feugene/granularity-devtools`](https://npmcn.com/package/%40feugene/granularity-devtools) | 2.1.1 国家 | Vue DevTools面板——一个道具值来自何处,覆盖层堆栈和设计系统警告. | | [`@feugene/granularity-editor`](https://npmcn.com/package/%40feugene/granularity-editor) | 4.0.1 (中文(简体) ) | Rich-text编辑:一个由 TipTap 支撑的 GrRichText 字段,有一个设计系统工具栏. | | [`@feugene/granularity-forms-schema`](https://npmcn.com/package/%40feugene/granularity-forms-schema) | 3.0.1 (中文(简体) ) | Schema驱动的形式——zod和JSON Schema进入了真实的形式字段,零依赖. | | [`@feugene/granularity-media`](https://npmcn.com/package/%40feugene/granularity-media) | 4.0.0 (单位:千美元) | 媒体组件:图像裁剪,相机捕捉,代码扫描和视频回放. | | [`@feugene/granularity-test-kit`](https://npmcn.com/package/%40feugene/granularity-test-kit) | 2.4.0 (中文(简体) ) | 测试 @ feugene/ granulaity 设计-系统包的门 — 标志、登记和默认合同作为可重复使用的工厂. | | [`@feugene/granularity-tokens`](https://npmcn.com/package/%40feugene/granularity-tokens) | 2.5.0 (中文(简体) ) | @feugene/granulality的设计符和主题: 符号注册,按模式和主题构建器的主题数据. | | [`@feugene/unplugin-granularity`](https://npmcn.com/package/%40feugene/unplugin-granularity) | 1.2.1 国家 | unplugin-vue-组件解析器——组件和指令的颗粒自动进口. | | | | | ## 文档 - [`docs/README.md`](https://npmcn.com/package/%40feugene/granularity/docs/README.md) 概览和文件地图 - [`docs/installation.md`](https://npmcn.com/package/%40feugene/granularity/docs/installation.md) 设施、公共入境点和收养战略 - [`docs/styling.md`](https://npmcn.com/package/%40feugene/granularity/docs/styling.md) 样式层、主题和导入顺序 - [`docs/tokens.md`](https://npmcn.com/package/%40feugene/granularity/docs/tokens.md) —— 组件符号参考(来自每个组件的) `tokens.json`);全球标志和主题—— [`@feugene/granularity-tokens`](https://npmcn.com/package/%40feugene/granularity-tokens/docs/tokens.md) - [`docs/entry-sizes.md`](https://npmcn.com/package/%40feugene/granularity/docs/entry-sizes.md) ——每个组件作为子道的重量(由建筑产生) - [`docs/modes.md`](https://npmcn.com/package/%40feugene/granularity/docs/modes.md) ——应用程序中的模式:切换,岛屿,SSR,配置中你自己的模式 - [`themes.md`](https://npmcn.com/package/%40feugene/granularity-tokens/docs/themes.md) 联合国 `@feugene/granularity-tokens` ——主题:角色,对比规则,构建自己的模式或主题 - [`docs/keyboard.md`](https://npmcn.com/package/%40feugene/granularity/docs/keyboard.md) ——每个组件的键盘合同 - [`docs/overlays.md`](https://npmcn.com/package/%40feugene/granularity/docs/overlays.md) 重叠合同:门户、层叠、Esc, `inert`,焦点 - [`docs/z-index.md`](https://npmcn.com/package/%40feugene/granularity/docs/z-index.md) ——分层尺度 - [`docs/ssr.md`](https://npmcn.com/package/%40feugene/granularity/docs/ssr.md) ——服务器侧渲染合同 - [`docs/granum.md`](https://npmcn.com/package/%40feugene/granularity/docs/granum.md) —— 说 `granum` 融合 - [`docs/localization.md`](https://npmcn.com/package/%40feugene/granularity/docs/localization.md) ——软件包插件如何将应用程序本地化 - [`docs/directives.md`](https://npmcn.com/package/%40feugene/granularity/docs/directives.md) ——包裹级指令 - [`docs/file-validation.md`](https://npmcn.com/package/%40feugene/granularity/docs/file-validation.md) ——文件验证 API - [`docs/components.md`](https://npmcn.com/package/%40feugene/granularity/docs/components.md) ——已公布组件目录 - [`docs/ADDING_COMPONENTS.md`](https://npmcn.com/package/%40feugene/granularity/docs/ADDING_COMPONENTS.md) ——新增部分内部指南 ## 常见问题 ### @feugene/granularity 是什么？具有Vue 3组件的外观设计系统包,通过 @feugene/granum 修建管道\. ### 如何安装 @feugene/granularity？在项目目录运行 npm install @feugene/granularity，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.5\.0）、@feugene/granum（\>=3\.10\.0 \<4\.0\.0）、@floating-ui/dom（^1\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @feugene/granularity 支持 TypeScript 吗？支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @feugene/granularity 支持 ESM 还是 CommonJS？以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @feugene/granularity 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @feugene/granularity 可以商用吗？ @feugene/granularity 使用 LicenseRef-Granularity-EUC-1\.1 许可。声明的许可为 LicenseRef-Granularity-EUC-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。 ### @feugene/granularity 的下载量有多少？根据 npm 官方下载统计，@feugene/granularity 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,932 次，日均约 164 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @feugene/granularity 还在维护吗？最新版本 3\.7\.2 发布于 2026/10/29（16 天前）；至今共发布 117 个版本，其中过去 12 个月发布了 117 个；首次发布于 2026/04/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。