# @erpsquad/common 中文文档 规范地址：https://npmcn.com/package/%40erpsquad/common/ 版本：1\.11\.28 npm 元数据更新时间：2026-11-12T10:58:12.361Z 中文译文更新时间：2026-11-13T21:29:09.457Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40erpsquad/common 原文对照：https://npmcn.com/package/%40erpsquad/common/?lang=original 项目主页：https://github.com/erpforce/common#readme 源码仓库：https://github.com/erpforce/common ## 关键信息（来自 npm 元数据） - 包体积（解压后）：47.8 MB，5899 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：d3 ^7\.8\.5，yup ^1\.7\.1，sass ^1\.69\.5，uuid ^11\.1\.0，axios ^1\.0\.0，dayjs ^1\.11\.10，jspdf ^2\.5\.2，react ^18\.2\.0 \|\| ^19\.0\.0，lodash ^4\.17\.21，marked ^12\.0\.0，moment ^2\.30\.1，i18next ^23\.7\.11，@mui/lab ^5\.0\.0-alpha\.165，recharts ^3\.8\.1，ckeditor5 ^47\.6\.1，notistack ^3\.0\.1，papaparse ^5\.4\.1，react-dnd ^16\.0\.1，react-dom ^18\.2\.0 \|\| ^19\.0\.0，@tiptap/pm ^3\.20\.4，file-saver ^2\.0\.5，pdfjs-dist ^3\.11\.174，html2canvas ^1\.4\.1，react-redux ^8\.1\.0 \|\| ^9\.0\.0，lucide-react ^0\.507\.0，react-select ^5\.7\.0，react-to-pdf ^1\.0\.1，@dnd-kit/core ^6\.3\.1，@mui/material ^5\.15\.0，@tiptap/react ^3\.20\.4，react-i18next ^13\.5\.0，@emotion/react ^11\.0\.0，react-dropzone ^14\.2\.3，@emotion/styled ^11\.0\.0，moment-timezone ^0\.5\.47，react-hook-form ^7\.58\.1，react-hot-toast ^2\.4\.1，@reduxjs/toolkit ^1\.9\.0 \|\| ^2\.0\.0，gantt-task-react ^0\.3\.9，react-date-range ^2\.0\.1，react-datepicker ^6\.1\.0，react-doc-viewer ^0\.1\.14，react-router-dom ^6\.21\.0，socket\.io-client ^4\.8\.1，@dnd-kit/sortable ^10\.0\.0，libphonenumber-js ^1\.11\.11，react-file-viewer ^1\.2\.1，react-grid-layout ^1\.4\.4，@fullcalendar/core ^6\.1\.10，@fullcalendar/list ^6\.1\.10，react-flags-select ^2\.2\.3，react-helmet-async ^2\.0\.4，react-querybuilder ^6\.5\.5，@fullcalendar/react ^6\.1\.10，@hookform/resolvers ^3\.10\.0，@mui/icons-material ^5\.15\.0，@mui/x-date-pickers ^6\.19\.3，@tiptap/starter-kit ^3\.20\.4，react-phone-input-2 ^2\.15\.1，i18next-http-backend ^2\.4\.2，material-react-table ^2\.13\.1，@fullcalendar/daygrid ^6\.1\.10，@asseinfo/react-kanban ^2\.2\.0，@fullcalendar/resource ^6\.1\.10，@fullcalendar/timegrid ^6\.1\.10，@fullcalendar/timeline ^6\.1\.10，@react-pdf-viewer/core ^3\.12\.0，@tiptap/extension-link ^3\.20\.4，@tiptap/extension-color ^3\.20\.4，@tiptap/extension-image ^3\.20\.4，@tiptap/extension-table ^3\.20\.4，react-dnd-html5-backend ^16\.0\.1，@ckeditor/ckeditor5-react ^11\.0\.1，@fullcalendar/interaction ^6\.1\.10，@glideapps/glide-data-grid ^5\.3\.2，@tiptap/extension-highlight ^3\.20\.4，@tiptap/extension-subscript ^3\.20\.4，@tiptap/extension-table-row ^3\.20\.4，@tiptap/extension-underline ^3\.20\.4，@react-querybuilder/material ^6\.5\.5，@tiptap/extension-table-cell ^3\.20\.4，@tiptap/extension-text-align ^3\.20\.4，@tiptap/extension-text-style ^3\.20\.4，@tiptap/extension-font-family ^3\.20\.4，@tiptap/extension-placeholder ^3\.20\.4，@tiptap/extension-superscript ^3\.20\.4，@tiptap/extension-table-header ^3\.20\.4，@fullcalendar/resource-timegrid ^6\.1\.10，@fullcalendar/resource-timeline ^6\.1\.10，@glideapps/glide-data-grid-cells ^5\.3\.2，@react-pdf-viewer/default-layout ^3\.12\.0，@tiptap/extension-code-block-lowlight ^3\.20\.4 - 首次发布：2025-11-06T12:26:27.366Z - 最新版本发布：2026-11-12T10:58:12.153Z - 近 30 天下载量：36968（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：540（近 12 个月 520 个） ## 中文简介 企业资源规划模块共享的UI组件库 ## 安装 ```sh npm install @erpsquad/common ``` 也可以使用：`pnpm add @erpsquad/common`、`yarn add @erpsquad/common`、`bun add @erpsquad/common` ## README # @ erpsquad/ 常见 一个用于ERP应用程序的综合反应组件库,由Material-UI和TypeScript所建. 这个库提供100+可再使用的UI组件,主题系统,公用设施,钩子,以及用于构建现代ERP应用程序的可选Redux集成. ## \* 特性 - **100+ UI 组件**: 一整套形式控制、数据显示、导航和布局组件 - **物质-UI 整合**: 以自定义主题建在材料UI上 - **类型脚本支持**: 所有组件和公用事业的完整类型脚本定义 - **弹性 Redux 集成**: 可选的 Redux 支持 - 组件工作与 Redux 无关 - **主题系统**: 有 RTL/LTR 支持和自定义颜色的浅/暗主题 - **国际化**: 内建的i18n支持语言切换 - **最佳业绩**: 90 qq 捆绑大小减少,并采用模块化进口和打树 - **智能代码分割**: 重依赖的自动块 - **QQ 快装入时间**:75-90%的构建配置优化后更快 - **无障碍**:具有适当ARIA属性的WCAG兼容组件 - **模块结构**: 只导入最小化捆绑大小所需的内容 - **同伴扶养管理**: 不同项目设置的灵活依赖管理 ## & 深度导入 **V1.9.98+中新增**:完全深度进口支持最大性能! ### 深度导入( 建议) 仅导入您需要的最佳捆绑大小 : ```typescript // ✅ Deep imports (recommended) - Only ~50-150KB import { Button } from "@erpsquad/common/components/button"; import { useAuth } from "@erpsquad/common/hooks/useAuth"; import { formatDate } from "@erpsquad/common/utils/dateFormat"; // ❌ Barrel imports (not recommended) - Imports entire library ~2.5MB import { Button, useAuth, formatDate } from "@erpsquad/common"; ``` ### 业绩效益 - **90-97%的小捆包** 有深度进口 - **75-90%的载重速度** 以优化代码分割 - **有效的摇树** 自动删除未使用的代码 - **250个以上个人入境点** 用于组件、钩子、工具、上下文、图标和视图 **在此之前:** 2.5MB捆绑,5至8s装载时间 **之后:** 150-300KB捆绑,1至2s装载时间 ### 快速启动深导入 ```typescript // Components import { Button } from "@erpsquad/common/components/button"; import { TextField } from "@erpsquad/common/components/text-field"; import { MaterialTable } from "@erpsquad/common/components/material-table"; import ProtectedRoute from "@erpsquad/common/components/protected-route"; // Hooks import { useAuth } from "@erpsquad/common/hooks/useAuth"; import { usePermissions } from "@erpsquad/common/hooks/use-permissions"; // Utils import { formatDate } from "@erpsquad/common/utils/dateFormat"; import { api } from "@erpsquad/common/utils/api"; // Contexts import { AuthProvider } from "@erpsquad/common/contexts/AuthContext"; ``` 📚 **见 [完整 引用](https://npmcn.com/package/%40erpsquad/common/DEEP_IMPORTS_COMPLETE_REFERENCE.md) 所有700多条导入路径** 📋 **见 [快速引用](https://npmcn.com/package/%40erpsquad/common/DEEP_IMPORTS_QUICK_REFERENCE.md) 用于普通进口** 📖 **见 [深导入指南](https://npmcn.com/package/%40erpsquad/common/DEEP_IMPORTS_COMPLETE_GUIDE.md) 用于完整文件** ### 发展环境 为本地发展,您可以创建 `.env` 在工程根中带有这些变量。 确保添加 `.env` 给您的 `.gitignore` 用于保证敏感信息安全的文档. ### 生产部署 对于生产部署,将这些环境变量设置在您的主机环境配置面板上. ## \* 安装 ```bash npm install @erpsquad/common ``` ### 同伴依赖关系 库使用对等依赖来避免版本冲突并减少捆绑大小. 根据您的用法安装所需的依赖性 : #### 所需(核心功能) ```bash npm install react react-dom @mui/material @emotion/react @emotion/styled @mui/icons-material ``` #### 可选( 特有) 对于Redux集成: ```bash npm install @reduxjs/toolkit react-redux ``` 日期组件: ```bash npm install @mui/x-date-pickers date-fns ``` 数据网组件: ```bash npm install @mui/x-data-grid ``` 线路公用事业: ```bash npm install react-router-dom ``` 在国际化方面: ```bash npm install react-i18next i18next ``` 对于公用功能: ```bash npm install lodash axios ``` #### 完成安装( 所有特性) ```bash # Install all peer dependencies for full functionality npm install react react-dom @mui/material @emotion/react @emotion/styled @mui/icons-material @reduxjs/toolkit react-redux @mui/x-date-pickers @mui/x-data-grid date-fns react-router-dom react-i18next i18next lodash axios ``` ## QQ 快速启动 ### QQ 重要: 导入样式 **在使用任何组件之前, 您必须导入您主应用程序文件中的 CSS 文件 :** ```tsx // main.tsx or App.tsx or index.tsx import '@erpsquad/common/style.css'; // 👈 REQUIRED - Import this first! ``` 如果没有此导入, 组件将生成但有 **没有样式**。 。 。 . * * * ### 业绩最佳做法 **使用模块导入实现最佳捆绑大小 :** ```tsx // ✅ Good - Only loads what you need (recommended) import { Button, TextField } from '@erpsquad/common/components'; import { useAuth } from '@erpsquad/common/hooks'; import { formatDate } from '@erpsquad/common/utils'; // ❌ Avoid - Loads entire library (deprecated in v2.0.0) import { Button, useAuth, formatDate } from '@erpsquad/common'; ``` **影响 :** 90qq 捆绑大小缩小,75qq 更快的负载时间 📚 **见 [绩效迁移指南](https://npmcn.com/package/%40erpsquad/common/PERFORMANCE_MIGRATION.md) 移民步骤** * * * ### 核心用法(最小依赖) 库提供核心功能而不需要所有对等依赖: ```tsx import React from 'react'; // ⚠️ IMPORTANT: Import styles first (in your main file) import '@erpsquad/common/style.css'; import { configureLibrary, getLibraryConfig, images, DEFAULT_LANG, type LibraryConfig } from '@erpsquad/common'; // Configure library for your application const config: LibraryConfig = { routes: { login: '/auth/login', dashboard: '/dashboard' }, validation: { emailRequired: true, phoneRequired: false }, dataTransforms: { dateFormat: 'dd/MM/yyyy' } }; configureLibrary(config); function App() { const currentConfig = getLibraryConfig(); return (
Logo

Default language: {DEFAULT_LANG}

Login route: {currentConfig.routes?.login}

); } export default App; ``` ### 可用核心导出 下列出口没有同伴依赖关系: ```tsx // Configuration system import { configureLibrary, getLibraryConfig, getConfigFunction, type LibraryConfig } from '@erpsquad/common'; // Static assets import { default as images } from '@erpsquad/common'; // Constants import { DEFAULT_LANG, LANGUAGES, S3_BUCKET_URL } from '@erpsquad/common'; // TypeScript types import type { BaseComponentProps, ThemeConfig, SelectOption, TableColumn, User, Permission } from '@erpsquad/common'; ``` ### 完全使用( 有同行依赖) 在安装对等依赖后, 您可以使用所有组件 : ```tsx import React from 'react'; // ⚠️ Import styles first! import '@erpsquad/common/style.css'; // Note: Import from specific paths to avoid dependency issues import { ERPUIProvider } from '@erpsquad/common/contexts'; import { Button, TextField } from '@erpsquad/common/components'; function App() { return (
); } export default App; ``` ### 带有自定义主题 ```tsx import React from 'react'; // ⚠️ Import styles first! import '@erpsquad/common/style.css'; import { ERPUIProvider } from '@erpsquad/common/contexts'; import { Button } from '@erpsquad/common/components'; import { createLightTheme } from '@erpsquad/common/theme'; function App() { const { theme } = createLightTheme('#2196f3', 'ltr'); return ( ); } ``` ## QQ 主题系统 图书馆包括一个综合主题系统,支持光/暗模式、RTL/LTR方向和自定义颜色. ### 主题配置 ```tsx import { ERPUIProvider } from '@erpsquad/common/contexts'; ; ``` ### 自定义主题对象 ```tsx import { createLightTheme, createDarkTheme } from '@erpsquad/common/theme'; import { ERPUIProvider } from '@erpsquad/common/contexts'; // Create custom theme const { theme } = createLightTheme('#1976d2', 'ltr'); // Or create dark theme const { darkTheme } = createDarkTheme('#1976d2', 'ltr'); ; ``` ### 可用颜色 库支持各种颜色格式 : - 十六进制颜色 : `#1976d2` - RGB: (英语) `rgb(25, 118, 210)` - 颜色名称 : `blue`, (中文(简体) ), `red`, (中文(简体) ), `green` - 材料- UI 颜色对象 ## & SCSS 样式 该图书馆提供一套全面的造型系统,其中包含编译的CSS,SCSS变量,混音,公用类和动画. ### 导入编译的 CSS( 建议) 将此添加到您的主应用程序文件中 : ```tsx // main.tsx or App.tsx import '@erpsquad/common/style.css'; ``` 这给你: - 所有组件样式 - 快速发展的公用事业类 - 响应样式 - 动画 ### 使用工具类 ```tsx

Welcome

Description text

``` 可用的工具类 : - **版式**数字 : `d-flex`, (中文(简体) ), `flex-direction-column`, (中文(简体) ), `justify-content-center`, (中文(简体) ), `align-items-center` - **间距**数字 : `mb-1`, (中文(简体) ), `mt-2`, (中文(简体) ), `p-0`, (中文(简体) ), `pl-2` (铺设/边缘设施) - **类型**数字 : `h1`\- 说吧`h5` (标题), `s1`\- 说吧`s5` (正文), (中文(简体) ), `bold`, (中文(简体) ), `medium`, (中文(简体) ), `normal` - **宽度/ 高**数字 : `w-100`, (中文(简体) ), `w-50`, (中文(简体) ), `h-100`, (中文(简体) ), `vh-100` - **文本对齐**数字 : `text-center`, (中文(简体) ), `text-left`, (中文(简体) ), `text-right` ### 使用SCSS变量(高级) 导入您的 SCSS 变量 `.scss` 文件 : ```scss // your-component.scss @import '@erpsquad/common/styles/variables'; .custom-component { background-color: $primary-600; color: $neutral-100; border: 1px solid $neutral-300; } ``` 可用色度( 100-1000) : - `$primary-*` (绿色), `$neutral-*` (gray), (英语), `$error-*` (红色) - `$blue-*`, (中文(简体) ), `$magenta-*`, (中文(简体) ), `$olive-*`, (中文(简体) ), `$green-*`, (中文(简体) ), `$lightGreen-*` ### 使用 SCSS Mixins (高级) ```scss // your-component.scss @import '@erpsquad/common/styles/mixins'; .responsive-layout { @include flex(center, space-between, row); @include media-md { flex-direction: column; } } ``` 可用混音符 : - `@include flex($align, $justify, $direction)` - Flexbox 缩写 - `@include transition($time, $motion)` - 过渡简写 - `@include center` - 绝对中心定位 - 响应断点 : `@include media-sm`, (中文(简体) ), `@include media-md`, (中文(简体) ), `@include media-l`等 (中文(简体) ). ### 导入全部 SCSS 特性 ```scss // For complete access to variables, mixins, utilities, and animations @import '@erpsquad/common/styles/all'; ``` **详细文档样式见:** - [完整样式文档](https://npmcn.com/package/%40erpsquad/common/src/styles/README.md) - [样式使用指南](https://npmcn.com/package/%40erpsquad/common/STYLES_USAGE.md) - [移徙指南](https://npmcn.com/package/%40erpsquad/common/STYLES_MIGRATION.md) ## 模块导入系统 该图书馆使用模块化的导入系统来防止依赖性问题. 根据您的需要从特定路径导入 : ```tsx // Core functionality (no peer dependencies required) import { configureLibrary, images } from '@erpsquad/common'; // Components (requires React, MUI peer dependencies) import { Button, TextField } from '@erpsquad/common/components'; // Hooks (requires React peer dependencies) import { useAuth, useLanguage } from '@erpsquad/common/hooks'; // Contexts (requires React peer dependencies) import { ERPUIProvider, AuthProvider } from '@erpsquad/common/contexts'; // Theme utilities (requires MUI peer dependencies) import { createLightTheme, createDarkTheme } from '@erpsquad/common/theme'; // Utility functions (may require specific peer dependencies) import { formatDate, validateEmail } from '@erpsquad/common/utils'; // Redux integration (requires Redux peer dependencies) import { createLibraryStore, slices } from '@erpsquad/common/redux'; // API clients (requires axios peer dependency) import { AccountingAPI, InventoryAPI } from '@erpsquad/common/api-client'; // Styles (CSS bundle - recommended) import '@erpsquad/common/style.css'; // Styles (SCSS imports for advanced usage) // Import in .scss files only: // @import '@erpsquad/common/styles/variables'; // @import '@erpsquad/common/styles/mixins'; // @import '@erpsquad/common/styles/all'; ``` ## API 客户端 图书馆包括不同企业资源规划模块的预先配置的API客户端: ```tsx import { AccountingAPI, InventoryAPI, ManufacturingAPI, PurchaseAPI, SalesAPI, RentalAPI, RbacAPI, DriveAPI, SystemFeatureAPI } from '@erpsquad/common/api-client'; // Configure base API client const baseConfig = { baseURL: 'https://api.example.com', timeout: 10000, headers: { 'Content-Type': 'application/json' } }; // Use specific API clients const accountingClient = new AccountingAPI(baseConfig); const inventoryClient = new InventoryAPI(baseConfig); // Example usage const users = await accountingClient.getUsers(); const products = await inventoryClient.getProducts(); ``` ## 组件 ### 窗体控件 ```tsx import { TextField, Select, DatePicker, Checkbox, Radio, ToggleSwitch, Button } from '@erpsquad/common/components'; // Text input // Select dropdown