Browse Source
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com> Co-authored-by: zoomdong <1344492820@qq.com>pull/11718/head
Alex Zhu
5 months ago
committed by
GitHub
GitHub
11 changed files with 59 additions and 990 deletions
@ -0,0 +1,4 @@ |
|||||
|
module.exports = function mdRawLoader(source) { |
||||
|
this.cacheable?.(); |
||||
|
return `export default ${JSON.stringify(String(source))};`; |
||||
|
}; |
||||
@ -1,475 +0,0 @@ |
|||||
const content = `# Ant Design Pro Cheatsheet
|
|
||||
|
|
||||
|
|
||||
|
|
||||
## Getting Started |
|
||||
|
|
||||
**Requirements:** Node.js >= 20 |
|
||||
|
|
||||
**Create a project:** |
|
||||
|
|
||||
\`\`\`bash
|
|
||||
git clone --depth 1 https://github.com/ant-design/ant-design-pro.git my-project
|
|
||||
cd my-project |
|
||||
npm install |
|
||||
\`\`\` |
|
||||
|
|
||||
The project offers two modes: |
|
||||
|
|
||||
- **Full mode**: Includes all demo pages (Dashboard, Forms, Lists, Access, etc.), great for reference and learning |
|
||||
- **Simple mode**: Only keeps login page and basic layout, ideal for starting from scratch |
|
||||
|
|
||||
Switch to simple mode: |
|
||||
|
|
||||
\`\`\`bash
|
|
||||
git add -A && git commit -m "chore: save before simple" # Commit first to allow revert |
|
||||
npm run simple # Remove demo pages and unused deps |
|
||||
npm install # Update dependencies |
|
||||
\`\`\` |
|
||||
|
|
||||
> 💡 Start with full mode to learn the project structure, then switch to simple mode for development. |
|
||||
|
|
||||
**Directory structure:** |
|
||||
|
|
||||
\`\`\` |
|
||||
├── config/ # Configuration (routes, proxy, theme) |
|
||||
│ ├── config.ts # Main config |
|
||||
│ ├── routes.ts # Route definitions |
|
||||
│ ├── defaultSettings.ts # Layout & theme settings |
|
||||
│ └── proxy.ts # Dev proxy config |
|
||||
├── mock/ # Mock data |
|
||||
├── src/ |
|
||||
│ ├── components/ # Shared components |
|
||||
│ ├── locales/ # i18n resources |
|
||||
│ ├── models/ # Global data models |
|
||||
│ ├── services/ # API service layer |
|
||||
│ ├── utils/ # Utility functions |
|
||||
│ ├── access.ts # Permission definitions |
|
||||
│ └── app.tsx # Runtime configuration |
|
||||
├── docs/ # Project documentation |
|
||||
└── types/ # Type declarations |
|
||||
\`\`\` |
|
||||
|
|
||||
**Common commands:** |
|
||||
|
|
||||
| Command | Description | |
|
||||
|---------|-------------| |
|
||||
| \`npm start\` | Start dev server (UMI_ENV=dev, with Mock) |
|
|
||||
| \`npm run dev\` | Start dev server (no Mock) |
|
|
||||
| \`npm run start:dev\` | Same as dev, UMI_ENV=dev, no Mock |
|
|
||||
| \`npm run start:no-mock\` | Start without Mock |
|
|
||||
| \`npm run start:pre\` | Pre-production environment |
|
|
||||
| \`npm run start:test\` | Test environment |
|
|
||||
| \`npm run build\` | Build for production |
|
|
||||
| \`npm run preview\` | Build and preview locally (port 8000) |
|
|
||||
| \`npm run analyze\` | Analyze bundle size |
|
|
||||
| \`npm run lint\` | Lint (Biome + TypeScript) |
|
|
||||
| \`npm run biome\` | Auto-fix with Biome |
|
|
||||
| \`npm test\` | Run tests |
|
|
||||
| \`npm run test:coverage\` | Test with coverage |
|
|
||||
| \`npm run openapi\` | Generate API code from OpenAPI schema |
|
|
||||
| \`npm run simple\` | Strip demo pages and unused deps |
|
|
||||
|
|
||||
> 💡 \`UMI_ENV\` switches environment configs, mapping to different proxy rules in \`config/proxy.ts\`.
|
|
||||
|
|
||||
> 💡 \`npm run simple\` removes demo pages (dashboard, form, list etc.) and unused dependencies (plots, etc.), replacing with minimal routes. Ideal for starting from scratch. **Commit your code first so you can revert if needed.**
|
|
||||
|
|
||||
**Build tool:** This project uses [utoopack](https://github.com/utooland/utoo) (a next-gen bundler powered by Turbopack) as the default build tool, configured via the \`utoopack\` field in \`config/config.ts\`. utoopack is Webpack-compatible and supports \`module.rules\` for custom loaders.
|
|
||||
|
|
||||
→ See [umi Getting Started](https://umijs.org/docs/guides/getting-started), [utoo Docs](https://utoo.land)
|
|
||||
|
|
||||
## Routes & Menu |
|
||||
|
|
||||
**Route config** is in \`config/routes.ts\`:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export default [ |
|
||||
{ |
|
||||
path: '/welcome', |
|
||||
name: 'welcome', // maps to menu.welcome i18n key
|
|
||||
icon: 'home', |
|
||||
component: './Welcome', |
|
||||
}, |
|
||||
{ |
|
||||
path: '/admin', |
|
||||
name: 'admin', |
|
||||
icon: 'crown', |
|
||||
access: 'canAdmin', // route-level access control
|
|
||||
routes: [...], |
|
||||
}, |
|
||||
{ path: '/', redirect: '/dashboard/analysis' }, |
|
||||
{ component: '404', path: './*' }, |
|
||||
]; |
|
||||
\`\`\` |
|
||||
|
|
||||
**Route navigation:** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { useNavigate, useParams, useLocation } from '@umijs/max'; |
|
||||
|
|
||||
const navigate = useNavigate(); |
|
||||
navigate('/dashboard'); // navigate
|
|
||||
navigate(-1); // go back
|
|
||||
|
|
||||
const { id } = useParams(); // dynamic param /user/:id
|
|
||||
const location = useLocation(); // current route info
|
|
||||
\`\`\` |
|
||||
|
|
||||
**Menu & access:** The \`access\` field in route config controls menu visibility — unauthorized routes won't appear in the menu.
|
|
||||
|
|
||||
> 💡 The \`name\` field is automatically mapped to \`menu.xxx\` i18n keys. Configure translations in \`src/locales/\`.
|
|
||||
|
|
||||
→ See [umi Routes](https://umijs.org/docs/guides/routes), [Umi Max Layout & Menu](https://umijs.org/docs/max/layout-menu)
|
|
||||
|
|
||||
## Layout |
|
||||
|
|
||||
**ProLayout config** is in \`config/defaultSettings.ts\`:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export default { |
|
||||
navTheme: 'light', // nav theme: light / dark
|
|
||||
colorPrimary: '#1890ff', // primary color
|
|
||||
layout: 'mix', // layout mode: side / top / mix
|
|
||||
contentWidth: 'Fluid', // content width: Fluid / Fixed
|
|
||||
fixSiderbar: true, // fixed sidebar
|
|
||||
}; |
|
||||
\`\`\` |
|
||||
|
|
||||
**Layout modes:** |
|
||||
- \`side\` — Side navigation
|
|
||||
- \`top\` — Top navigation
|
|
||||
- \`mix\` — Top + side mixed navigation
|
|
||||
|
|
||||
**Page container:** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { PageContainer } from '@ant-design/pro-components'; |
|
||||
|
|
||||
const Page = () => ( |
|
||||
<PageContainer |
|
||||
header={{ title: 'Page Title' }} |
|
||||
content="Page description" |
|
||||
> |
|
||||
{/* Page content */} |
|
||||
</PageContainer> |
|
||||
); |
|
||||
\`\`\` |
|
||||
|
|
||||
**Custom areas:** Top-right \`src/components/RightContent\`, footer \`src/components/Footer\`.
|
|
||||
|
|
||||
→ See [Umi Max Layout & Menu](https://umijs.org/docs/max/layout-menu)
|
|
||||
|
|
||||
## Data Flow |
|
||||
|
|
||||
**useModel — lightweight global state:** Create a file in \`src/models/\` to auto-register:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
// src/models/counter.ts
|
|
||||
import { useState } from 'react'; |
|
||||
|
|
||||
export default function useCounter() { |
|
||||
const [count, setCount] = useState(0); |
|
||||
const increment = () => setCount(c => c + 1); |
|
||||
return { count, increment }; |
|
||||
} |
|
||||
\`\`\` |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
// Use in any component
|
|
||||
import { useModel } from '@umijs/max'; |
|
||||
|
|
||||
const { count, increment } = useModel('counter'); |
|
||||
\`\`\` |
|
||||
|
|
||||
**useRequest — data fetching:** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { useRequest } from '@umijs/max'; |
|
||||
|
|
||||
const { data, loading, error } = useRequest(getUserInfo); |
|
||||
\`\`\` |
|
||||
|
|
||||
**React Query — server state management:** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'; |
|
||||
|
|
||||
// Query
|
|
||||
const { data, isLoading } = useQuery({ |
|
||||
queryKey: ['user', id], |
|
||||
queryFn: () => getUser(id), |
|
||||
}); |
|
||||
|
|
||||
// Mutation
|
|
||||
const mutation = useMutation({ |
|
||||
mutationFn: updateUser, |
|
||||
onSuccess: () => { |
|
||||
queryClient.invalidateQueries({ queryKey: ['user'] }); |
|
||||
}, |
|
||||
}); |
|
||||
\`\`\` |
|
||||
|
|
||||
**Initial state — getInitialState:** Define in \`src/app.tsx\`, accessible globally:
|
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
// src/app.tsx
|
|
||||
export async function getInitialState() { |
|
||||
const currentUser = await fetchUserInfo(); |
|
||||
return { currentUser }; |
|
||||
} |
|
||||
|
|
||||
// Use in components
|
|
||||
import { useModel } from '@umijs/max'; |
|
||||
const { initialState } = useModel('@@initialState'); |
|
||||
\`\`\` |
|
||||
|
|
||||
> 💡 \`getInitialState\` runs once on app startup, ideal for fetching global info (user identity, permissions).
|
|
||||
|
|
||||
→ See [Umi Max Data Flow](https://umijs.org/docs/max/data-flow)
|
|
||||
|
|
||||
## Request |
|
||||
|
|
||||
**Request config** is in \`src/app.tsx\`:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export const request: RequestConfig = { |
|
||||
baseURL: 'https://api.example.com', |
|
||||
timeout: 10000, |
|
||||
requestInterceptors: [], // request interceptors
|
|
||||
responseInterceptors: [], // response interceptors
|
|
||||
}; |
|
||||
\`\`\` |
|
||||
|
|
||||
**Error handling** is in \`src/requestErrorConfig.ts\`, customize error code mapping and notification logic.
|
|
||||
|
|
||||
**Using request:** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { request } from '@umijs/max'; |
|
||||
|
|
||||
// GET
|
|
||||
const data = await request('/api/users', { params: { page: 1 } }); |
|
||||
|
|
||||
// POST
|
|
||||
await request('/api/users', { method: 'POST', data: { name: 'test' } }); |
|
||||
\`\`\` |
|
||||
|
|
||||
**OpenAPI code generation:** |
|
||||
|
|
||||
\`\`\`bash
|
|
||||
npm run openapi |
|
||||
\`\`\` |
|
||||
|
|
||||
Auto-generates API calling code under \`src/services/\` based on \`config/openapi.json\`.
|
|
||||
|
|
||||
> 💡 Generated code uses \`import { request } from '@umijs/max'\` directly — no manual wrapping needed.
|
|
||||
|
|
||||
→ See [Umi Max Request](https://umijs.org/docs/max/request)
|
|
||||
|
|
||||
## Access Control |
|
||||
|
|
||||
**Define permissions** in \`src/access.ts\`:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export default function access(initialState: { currentUser?: API.CurrentUser }) { |
|
||||
const { currentUser } = initialState; |
|
||||
return { |
|
||||
canAdmin: currentUser?.access === 'admin', |
|
||||
canUser: !!currentUser, |
|
||||
}; |
|
||||
} |
|
||||
\`\`\` |
|
||||
|
|
||||
**Route-level access:** Add \`access\` field in route config:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
{ path: '/admin', access: 'canAdmin' } |
|
||||
\`\`\` |
|
||||
|
|
||||
**Component-level access:** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { Access, useAccess } from '@umijs/max'; |
|
||||
|
|
||||
// Declarative
|
|
||||
<Access accessible={access.canAdmin}> |
|
||||
<AdminPanel /> |
|
||||
</Access> |
|
||||
|
|
||||
// Imperative
|
|
||||
const access = useAccess(); |
|
||||
if (access.canAdmin) { /* ... */ } |
|
||||
\`\`\` |
|
||||
|
|
||||
→ See [Umi Max Access](https://umijs.org/docs/max/access)
|
|
||||
|
|
||||
## Internationalization |
|
||||
|
|
||||
**Config** in \`config/config.ts\`:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
locale: { |
|
||||
default: 'zh-CN', |
|
||||
antd: true, // sync antd component locale
|
|
||||
baseNavigator: true, // follow browser language
|
|
||||
}, |
|
||||
\`\`\` |
|
||||
|
|
||||
**File structure:** |
|
||||
|
|
||||
\`\`\` |
|
||||
src/locales/ |
|
||||
├── zh-CN.ts # Chinese entry |
|
||||
├── zh-CN/ |
|
||||
│ ├── menu.ts # Menu translations |
|
||||
│ ├── pages.ts # Page translations |
|
||||
│ └── ... |
|
||||
├── en-US.ts # English entry |
|
||||
└── en-US/ |
|
||||
└── ... |
|
||||
\`\`\` |
|
||||
|
|
||||
**Usage:** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { useIntl, FormattedMessage } from '@umijs/max'; |
|
||||
|
|
||||
// Hook
|
|
||||
const intl = useIntl(); |
|
||||
intl.formatMessage({ id: 'menu.welcome' }); |
|
||||
|
|
||||
// Component
|
|
||||
<FormattedMessage id="menu.welcome" /> |
|
||||
\`\`\` |
|
||||
|
|
||||
**Switch locale:** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { setLocale } from '@umijs/max'; |
|
||||
setLocale('en-US', false); // false = no page reload
|
|
||||
\`\`\` |
|
||||
|
|
||||
→ See [Umi Max i18n](https://umijs.org/docs/max/i18n)
|
|
||||
|
|
||||
## Styling |
|
||||
|
|
||||
**CSS Modules:** Name files \`*.module.less\` or \`*.module.css\`:
|
|
||||
|
|
||||
\`\`\`css
|
|
||||
/* example.module.less */ |
|
||||
.container { padding: 24px; } |
|
||||
.title { font-size: 16px; } |
|
||||
\`\`\` |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import styles from './example.module.less'; |
|
||||
<div className={styles.container} /> |
|
||||
\`\`\` |
|
||||
|
|
||||
**antd-style (CSS-in-JS):** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { createStyles } from 'antd-style'; |
|
||||
|
|
||||
const useStyles = createStyles(({ token, css }) => ({ |
|
||||
card: css\` |
|
||||
background: \${token.colorBgContainer}; |
|
||||
border-radius: \${token.borderRadiusLG}px; |
|
||||
\`,
|
|
||||
})); |
|
||||
|
|
||||
const { styles } = useStyles(); |
|
||||
<div className={styles.card} /> |
|
||||
\`\`\` |
|
||||
|
|
||||
**Tailwind CSS (v4):** Use directly in className: |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
<div className="flex items-center gap-4 p-6 rounded-lg bg-white dark:bg-[#141414]" /> |
|
||||
\`\`\` |
|
||||
|
|
||||
**Dynamic theme:** Set in \`config/config.ts\` \`antd\` config:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
antd: { |
|
||||
configProvider: { |
|
||||
theme: { |
|
||||
token: { |
|
||||
colorPrimary: '#1890ff', |
|
||||
borderRadius: 6, |
|
||||
}, |
|
||||
}, |
|
||||
}, |
|
||||
}, |
|
||||
\`\`\` |
|
||||
|
|
||||
Use SettingDrawer in dev mode to switch themes in real-time. |
|
||||
|
|
||||
> 💡 Three styling approaches can coexist: Tailwind for layout, CSS Modules for component styles, antd-style when consuming theme tokens. |
|
||||
|
|
||||
→ See [umi Styling](https://umijs.org/docs/guides/styling), [Umi Max antd Dynamic Theme](https://umijs.org/docs/max/antd#动态主题)
|
|
||||
|
|
||||
## Testing & Debugging |
|
||||
|
|
||||
**Jest testing:** |
|
||||
|
|
||||
\`\`\`bash
|
|
||||
npm test # Run all tests |
|
||||
npm run test:coverage # With coverage report |
|
||||
npm run test:update # Update snapshots |
|
||||
\`\`\` |
|
||||
|
|
||||
Test files go next to the component, named \`*.test.ts(x)\`.
|
|
||||
|
|
||||
**Mock data:** Create files in \`mock/\`:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
// mock/user.ts
|
|
||||
export default { |
|
||||
'GET /api/currentUser': { name: 'Serati Ma', access: 'admin' }, |
|
||||
'POST /api/login': (req, res) => { res.end('ok'); }, |
|
||||
}; |
|
||||
\`\`\` |
|
||||
|
|
||||
Umi auto-registers mocks, active in dev mode. |
|
||||
|
|
||||
**Proxy config** is in \`config/proxy.ts\`:
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export default { |
|
||||
dev: { |
|
||||
'/api/': { |
|
||||
target: 'http://localhost:8080', |
|
||||
changeOrigin: true, |
|
||||
}, |
|
||||
}, |
|
||||
}; |
|
||||
\`\`\` |
|
||||
|
|
||||
> 💡 Use \`MOCK=none\` to skip mock and proxy to backend: \`npm run start:no-mock\`.
|
|
||||
|
|
||||
→ See [umi Testing](https://umijs.org/docs/guides/testing), [umi Mock](https://umijs.org/docs/guides/mock)
|
|
||||
|
|
||||
## FAQ |
|
||||
|
|
||||
**Q: How to disable Mock?** |
|
||||
\`npm run start:no-mock\` or \`cross-env MOCK=none max dev\` |
|
||||
|
|
||||
**Q: How to change the primary color?** |
|
||||
Edit \`colorPrimary\` in \`config/defaultSettings.ts\`. Use SettingDrawer for live preview in dev mode.
|
|
||||
|
|
||||
**Q: How to add a new page?** |
|
||||
1. Create component in \`src/pages/\` 2. Add route in \`config/routes.ts\` 3. Add menu translation in \`src/locales/\` (if needed)
|
|
||||
|
|
||||
**Q: How to add global state?** |
|
||||
Create a file in \`src/models/\` exporting a custom Hook, then use \`useModel('filename')\` in components.
|
|
||||
|
|
||||
**Q: How to deploy?** |
|
||||
\`npm run build\` generates \`dist/\`. Deploy to any static file server. Set \`publicPath\` for non-root deployments.
|
|
||||
|
|
||||
**Q: How to use OpenAPI code generation?** |
|
||||
1. Configure \`openAPI\` in \`config/config.ts\` 2. Run \`npm run openapi\` 3. Code is auto-generated under \`src/services/\` |
|
||||
|
|
||||
→ See [umi FAQ](https://umijs.org/docs/guides/faq)`;
|
|
||||
|
|
||||
export default content; |
|
||||
@ -1,475 +0,0 @@ |
|||||
const content = `# Ant Design Pro Cheatsheet
|
|
||||
|
|
||||
|
|
||||
|
|
||||
## 快速开始 |
|
||||
|
|
||||
**环境要求：** Node.js >= 20 |
|
||||
|
|
||||
**创建项目：** |
|
||||
|
|
||||
\`\`\`bash
|
|
||||
git clone --depth 1 https://github.com/ant-design/ant-design-pro.git my-project
|
|
||||
cd my-project |
|
||||
npm install |
|
||||
\`\`\` |
|
||||
|
|
||||
项目提供两种模式： |
|
||||
|
|
||||
- **完整模式**：包含所有示例页面（Dashboard、表单、列表、权限等），适合参考学习 |
|
||||
- **精简模式**：仅保留登录页和基础布局，适合从零开发 |
|
||||
|
|
||||
切换精简模式： |
|
||||
|
|
||||
\`\`\`bash
|
|
||||
git add -A && git commit -m "chore: save before simple" # 先提交，以便回退 |
|
||||
npm run simple # 删除示例页面和多余依赖 |
|
||||
npm install # 更新依赖 |
|
||||
\`\`\` |
|
||||
|
|
||||
> 💡 建议先用完整模式熟悉项目结构，再切换精简模式开始开发。 |
|
||||
|
|
||||
**目录结构：** |
|
||||
|
|
||||
\`\`\` |
|
||||
├── config/ # 配置文件（路由、代理、主题） |
|
||||
│ ├── config.ts # 主配置 |
|
||||
│ ├── routes.ts # 路由配置 |
|
||||
│ ├── defaultSettings.ts # 布局主题设置 |
|
||||
│ └── proxy.ts # 开发代理配置 |
|
||||
├── mock/ # Mock 数据 |
|
||||
├── src/ |
|
||||
│ ├── components/ # 公共组件 |
|
||||
│ ├── locales/ # 国际化资源 |
|
||||
│ ├── models/ # 全局数据模型 |
|
||||
│ ├── services/ # API 服务层 |
|
||||
│ ├── utils/ # 工具函数 |
|
||||
│ ├── access.ts # 权限定义 |
|
||||
│ └── app.tsx # 运行时配置 |
|
||||
├── docs/ # 项目文档 |
|
||||
└── types/ # 类型声明 |
|
||||
\`\`\` |
|
||||
|
|
||||
**常用命令：** |
|
||||
|
|
||||
| 命令 | 说明 | |
|
||||
|------|------| |
|
||||
| \`npm start\` | 启动开发服务器（UMI_ENV=dev，带 Mock） |
|
|
||||
| \`npm run dev\` | 启动开发服务器（无 Mock） |
|
|
||||
| \`npm run start:dev\` | 同 dev，UMI_ENV=dev，无 Mock |
|
|
||||
| \`npm run start:no-mock\` | 无 Mock 启动 |
|
|
||||
| \`npm run start:pre\` | 预发布环境启动 |
|
|
||||
| \`npm run start:test\` | 测试环境启动 |
|
|
||||
| \`npm run build\` | 构建生产产物 |
|
|
||||
| \`npm run preview\` | 构建并本地预览（端口 8000） |
|
|
||||
| \`npm run analyze\` | 构建产物体积分析 |
|
|
||||
| \`npm run lint\` | 代码检查（Biome + TypeScript） |
|
|
||||
| \`npm run biome\` | Biome 自动修复 |
|
|
||||
| \`npm test\` | 运行测试 |
|
|
||||
| \`npm run test:coverage\` | 测试覆盖率 |
|
|
||||
| \`npm run openapi\` | 根据 OpenAPI 生成 API 代码 |
|
|
||||
| \`npm run simple\` | 精简模式（删除示例页面和多余依赖） |
|
|
||||
|
|
||||
> 💡 \`UMI_ENV\` 用于切换环境配置，对应 \`config/proxy.ts\` 中的不同代理规则。
|
|
||||
|
|
||||
> 💡 \`npm run simple\` 会删除示例页面（dashboard、form、list 等）和多余依赖（plots 等），替换为精简路由，适合从零开始开发。**建议先提交代码，以便需要时回退。**
|
|
||||
|
|
||||
**构建工具：** 本项目使用 [utoopack](https://github.com/utooland/utoo)（基于 Turbopack 的新一代打包器）作为默认构建工具，通过 \`config/config.ts\` 中的 \`utoopack\` 字段配置。utoopack 兼容 Webpack 配置格式，支持 \`module.rules\` 配置自定义加载器。
|
|
||||
|
|
||||
→ 更多内容见 [umi 入门指南](https://umijs.org/docs/guides/getting-started)、[utoo 文档](https://utoo.land)
|
|
||||
|
|
||||
## 路由与菜单 |
|
||||
|
|
||||
**路由配置** 位于 \`config/routes.ts\`：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export default [ |
|
||||
{ |
|
||||
path: '/welcome', |
|
||||
name: 'welcome', // 对应 menu.welcome 国际化 key
|
|
||||
icon: 'home', |
|
||||
component: './Welcome', |
|
||||
}, |
|
||||
{ |
|
||||
path: '/admin', |
|
||||
name: 'admin', |
|
||||
icon: 'crown', |
|
||||
access: 'canAdmin', // 路由级权限控制
|
|
||||
routes: [...], |
|
||||
}, |
|
||||
{ path: '/', redirect: '/dashboard/analysis' }, |
|
||||
{ component: '404', path: './*' }, |
|
||||
]; |
|
||||
\`\`\` |
|
||||
|
|
||||
**路由导航：** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { useNavigate, useParams, useLocation } from '@umijs/max'; |
|
||||
|
|
||||
const navigate = useNavigate(); |
|
||||
navigate('/dashboard'); // 跳转
|
|
||||
navigate(-1); // 后退
|
|
||||
|
|
||||
const { id } = useParams(); // 获取动态参数 /user/:id
|
|
||||
const location = useLocation(); // 当前路由信息
|
|
||||
\`\`\` |
|
||||
|
|
||||
**菜单与权限联动：** 路由配置中 \`access\` 字段控制菜单可见性，未授权路由不会出现在菜单中。
|
|
||||
|
|
||||
> 💡 \`name\` 字段自动映射为 \`menu.xxx\` 国际化 key，在 \`src/locales/\` 中配置翻译。
|
|
||||
|
|
||||
→ 更多内容见 [umi 路由文档](https://umijs.org/docs/guides/routes)、[Umi Max 布局与菜单](https://umijs.org/docs/max/layout-menu)
|
|
||||
|
|
||||
## 布局 |
|
||||
|
|
||||
**ProLayout 配置** 位于 \`config/defaultSettings.ts\`：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export default { |
|
||||
navTheme: 'light', // 导航主题：light / dark
|
|
||||
colorPrimary: '#1890ff', // 主题色
|
|
||||
layout: 'mix', // 布局模式：side / top / mix
|
|
||||
contentWidth: 'Fluid', // 内容宽度：Fluid / Fixed
|
|
||||
fixSiderbar: true, // 固定侧边栏
|
|
||||
}; |
|
||||
\`\`\` |
|
||||
|
|
||||
**布局模式：** |
|
||||
- \`side\` — 左侧导航
|
|
||||
- \`top\` — 顶部导航
|
|
||||
- \`mix\` — 顶部 + 侧边混合导航
|
|
||||
|
|
||||
**页面容器：** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { PageContainer } from '@ant-design/pro-components'; |
|
||||
|
|
||||
const Page = () => ( |
|
||||
<PageContainer |
|
||||
header={{ title: '页面标题' }} |
|
||||
content="页面描述" |
|
||||
> |
|
||||
{/* 页面内容 */} |
|
||||
</PageContainer> |
|
||||
); |
|
||||
\`\`\` |
|
||||
|
|
||||
**自定义区域：** 右上角 \`src/components/RightContent\`，底部 \`src/components/Footer\`。
|
|
||||
|
|
||||
→ 更多内容见 [Umi Max 布局与菜单](https://umijs.org/docs/max/layout-menu)
|
|
||||
|
|
||||
## 数据流 |
|
||||
|
|
||||
**useModel — 轻量全局状态：** 在 \`src/models/\` 下创建文件即自动注册：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
// src/models/counter.ts
|
|
||||
import { useState } from 'react'; |
|
||||
|
|
||||
export default function useCounter() { |
|
||||
const [count, setCount] = useState(0); |
|
||||
const increment = () => setCount(c => c + 1); |
|
||||
return { count, increment }; |
|
||||
} |
|
||||
\`\`\` |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
// 任意组件中使用
|
|
||||
import { useModel } from '@umijs/max'; |
|
||||
|
|
||||
const { count, increment } = useModel('counter'); |
|
||||
\`\`\` |
|
||||
|
|
||||
**useRequest — 数据请求：** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { useRequest } from '@umijs/max'; |
|
||||
|
|
||||
const { data, loading, error } = useRequest(getUserInfo); |
|
||||
\`\`\` |
|
||||
|
|
||||
**React Query — 服务端状态管理：** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'; |
|
||||
|
|
||||
// 查询
|
|
||||
const { data, isLoading } = useQuery({ |
|
||||
queryKey: ['user', id], |
|
||||
queryFn: () => getUser(id), |
|
||||
}); |
|
||||
|
|
||||
// 变更
|
|
||||
const mutation = useMutation({ |
|
||||
mutationFn: updateUser, |
|
||||
onSuccess: () => { |
|
||||
queryClient.invalidateQueries({ queryKey: ['user'] }); |
|
||||
}, |
|
||||
}); |
|
||||
\`\`\` |
|
||||
|
|
||||
**初始状态 — getInitialState：** 在 \`src/app.tsx\` 中定义，全局可访问：
|
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
// src/app.tsx
|
|
||||
export async function getInitialState() { |
|
||||
const currentUser = await fetchUserInfo(); |
|
||||
return { currentUser }; |
|
||||
} |
|
||||
|
|
||||
// 组件中使用
|
|
||||
import { useModel } from '@umijs/max'; |
|
||||
const { initialState } = useModel('@@initialState'); |
|
||||
\`\`\` |
|
||||
|
|
||||
> 💡 \`getInitialState\` 在应用启动时执行一次，适合获取全局信息（如用户身份、权限）。
|
|
||||
|
|
||||
→ 更多内容见 [Umi Max 数据流](https://umijs.org/docs/max/data-flow)
|
|
||||
|
|
||||
## 请求 |
|
||||
|
|
||||
**请求配置** 位于 \`src/app.tsx\`：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export const request: RequestConfig = { |
|
||||
baseURL: 'https://api.example.com', |
|
||||
timeout: 10000, |
|
||||
requestInterceptors: [], // 请求拦截器
|
|
||||
responseInterceptors: [], // 响应拦截器
|
|
||||
}; |
|
||||
\`\`\` |
|
||||
|
|
||||
**错误处理** 位于 \`src/requestErrorConfig.ts\`，可自定义错误码映射和提示逻辑。
|
|
||||
|
|
||||
**使用请求：** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { request } from '@umijs/max'; |
|
||||
|
|
||||
// GET
|
|
||||
const data = await request('/api/users', { params: { page: 1 } }); |
|
||||
|
|
||||
// POST
|
|
||||
await request('/api/users', { method: 'POST', data: { name: 'test' } }); |
|
||||
\`\`\` |
|
||||
|
|
||||
**OpenAPI 代码生成：** |
|
||||
|
|
||||
\`\`\`bash
|
|
||||
npm run openapi |
|
||||
\`\`\` |
|
||||
|
|
||||
根据 \`config/openapi.json\` 自动生成 \`src/services/\` 下的 API 调用代码。
|
|
||||
|
|
||||
> 💡 生成后的代码直接用 \`import { request } from '@umijs/max'\` 发起请求，无需手动封装。
|
|
||||
|
|
||||
→ 更多内容见 [Umi Max 请求](https://umijs.org/docs/max/request)
|
|
||||
|
|
||||
## 权限 |
|
||||
|
|
||||
**定义权限** 在 \`src/access.ts\`：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export default function access(initialState: { currentUser?: API.CurrentUser }) { |
|
||||
const { currentUser } = initialState; |
|
||||
return { |
|
||||
canAdmin: currentUser?.access === 'admin', |
|
||||
canUser: !!currentUser, |
|
||||
}; |
|
||||
} |
|
||||
\`\`\` |
|
||||
|
|
||||
**路由级权限：** 在路由配置中添加 \`access\` 字段：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
{ path: '/admin', access: 'canAdmin' } |
|
||||
\`\`\` |
|
||||
|
|
||||
**组件级权限：** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { Access, useAccess } from '@umijs/max'; |
|
||||
|
|
||||
// 声明式
|
|
||||
<Access accessible={access.canAdmin}> |
|
||||
<AdminPanel /> |
|
||||
</Access> |
|
||||
|
|
||||
// 命令式
|
|
||||
const access = useAccess(); |
|
||||
if (access.canAdmin) { /* ... */ } |
|
||||
\`\`\` |
|
||||
|
|
||||
→ 更多内容见 [Umi Max 权限](https://umijs.org/docs/max/access)
|
|
||||
|
|
||||
## 国际化 |
|
||||
|
|
||||
**配置** 在 \`config/config.ts\`：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
locale: { |
|
||||
default: 'zh-CN', |
|
||||
antd: true, // 同步 antd 组件语言
|
|
||||
baseNavigator: true, // 跟随浏览器语言
|
|
||||
}, |
|
||||
\`\`\` |
|
||||
|
|
||||
**文件结构：** |
|
||||
|
|
||||
\`\`\` |
|
||||
src/locales/ |
|
||||
├── zh-CN.ts # 中文入口 |
|
||||
├── zh-CN/ |
|
||||
│ ├── menu.ts # 菜单翻译 |
|
||||
│ ├── pages.ts # 页面翻译 |
|
||||
│ └── ... |
|
||||
├── en-US.ts # 英文入口 |
|
||||
└── en-US/ |
|
||||
└── ... |
|
||||
\`\`\` |
|
||||
|
|
||||
**使用方式：** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { useIntl, FormattedMessage } from '@umijs/max'; |
|
||||
|
|
||||
// Hook 方式
|
|
||||
const intl = useIntl(); |
|
||||
intl.formatMessage({ id: 'menu.welcome' }); |
|
||||
|
|
||||
// 组件方式
|
|
||||
<FormattedMessage id="menu.welcome" /> |
|
||||
\`\`\` |
|
||||
|
|
||||
**切换语言：** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { setLocale } from '@umijs/max'; |
|
||||
setLocale('en-US', false); // false = 不刷新页面
|
|
||||
\`\`\` |
|
||||
|
|
||||
→ 更多内容见 [Umi Max 国际化](https://umijs.org/docs/max/i18n)
|
|
||||
|
|
||||
## 样式 |
|
||||
|
|
||||
**CSS Modules：** 文件命名为 \`*.module.less\` 或 \`*.module.css\`：
|
|
||||
|
|
||||
\`\`\`css
|
|
||||
/* example.module.less */ |
|
||||
.container { padding: 24px; } |
|
||||
.title { font-size: 16px; } |
|
||||
\`\`\` |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import styles from './example.module.less'; |
|
||||
<div className={styles.container} /> |
|
||||
\`\`\` |
|
||||
|
|
||||
**antd-style（CSS-in-JS）：** |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
import { createStyles } from 'antd-style'; |
|
||||
|
|
||||
const useStyles = createStyles(({ token, css }) => ({ |
|
||||
card: css\` |
|
||||
background: \${token.colorBgContainer}; |
|
||||
border-radius: \${token.borderRadiusLG}px; |
|
||||
\`,
|
|
||||
})); |
|
||||
|
|
||||
const { styles } = useStyles(); |
|
||||
<div className={styles.card} /> |
|
||||
\`\`\` |
|
||||
|
|
||||
**Tailwind CSS（v4）：** 直接在 className 中使用： |
|
||||
|
|
||||
\`\`\`tsx
|
|
||||
<div className="flex items-center gap-4 p-6 rounded-lg bg-white dark:bg-[#141414]" /> |
|
||||
\`\`\` |
|
||||
|
|
||||
**动态主题：** 在 \`config/config.ts\` 的 \`antd\` 配置中设置：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
antd: { |
|
||||
configProvider: { |
|
||||
theme: { |
|
||||
token: { |
|
||||
colorPrimary: '#1890ff', |
|
||||
borderRadius: 6, |
|
||||
}, |
|
||||
}, |
|
||||
}, |
|
||||
}, |
|
||||
\`\`\` |
|
||||
|
|
||||
开发环境可通过右下角 SettingDrawer 实时切换主题。 |
|
||||
|
|
||||
> 💡 三种样式方案可以共存：Tailwind 适合布局、CSS Modules 适合组件样式、antd-style 适合需要消费主题 token 的场景。 |
|
||||
|
|
||||
→ 更多内容见 [umi 样式文档](https://umijs.org/docs/guides/styling)、[Umi Max antd 动态主题](https://umijs.org/docs/max/antd#动态主题)
|
|
||||
|
|
||||
## 测试 & 调试 |
|
||||
|
|
||||
**Jest 测试：** |
|
||||
|
|
||||
\`\`\`bash
|
|
||||
npm test # 运行所有测试 |
|
||||
npm run test:coverage # 带覆盖率报告 |
|
||||
npm run test:update # 更新快照 |
|
||||
\`\`\` |
|
||||
|
|
||||
测试文件放在对应组件目录下，命名为 \`*.test.ts(x)\`。
|
|
||||
|
|
||||
**Mock 数据：** 在 \`mock/\` 目录下创建文件：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
// mock/user.ts
|
|
||||
export default { |
|
||||
'GET /api/currentUser': { name: 'Serati Ma', access: 'admin' }, |
|
||||
'POST /api/login': (req, res) => { res.end('ok'); }, |
|
||||
}; |
|
||||
\`\`\` |
|
||||
|
|
||||
Umi 自动注册 mock，开发模式下生效。 |
|
||||
|
|
||||
**代理配置** 位于 \`config/proxy.ts\`：
|
|
||||
|
|
||||
\`\`\`ts
|
|
||||
export default { |
|
||||
dev: { |
|
||||
'/api/': { |
|
||||
target: 'http://localhost:8080', |
|
||||
changeOrigin: true, |
|
||||
}, |
|
||||
}, |
|
||||
}; |
|
||||
\`\`\` |
|
||||
|
|
||||
> 💡 用 \`MOCK=none\` 启动可跳过 Mock，直接代理到后端：\`npm run start:no-mock\`。
|
|
||||
|
|
||||
→ 更多内容见 [umi 测试](https://umijs.org/docs/guides/testing)、[umi Mock](https://umijs.org/docs/guides/mock)
|
|
||||
|
|
||||
## FAQ |
|
||||
|
|
||||
**Q: 如何关闭 Mock？** |
|
||||
\`npm run start:no-mock\` 或 \`cross-env MOCK=none max dev\` |
|
||||
|
|
||||
**Q: 如何修改主题色？** |
|
||||
修改 \`config/defaultSettings.ts\` 的 \`colorPrimary\`，开发时可用 SettingDrawer 实时调整。
|
|
||||
|
|
||||
**Q: 如何添加新页面？** |
|
||||
1. 在 \`src/pages/\` 下创建组件 2. 在 \`config/routes.ts\` 添加路由 3. 在 \`src/locales/\` 添加菜单翻译（如需）
|
|
||||
|
|
||||
**Q: 如何添加全局状态？** |
|
||||
在 \`src/models/\` 下创建文件，导出自定义 Hook，组件中通过 \`useModel('文件名')\` 使用。
|
|
||||
|
|
||||
**Q: 如何部署？** |
|
||||
\`npm run build\` 生成 \`dist/\` 目录，部署到任意静态服务器。配置 \`publicPath\` 处理非根目录部署。
|
|
||||
|
|
||||
**Q: 如何使用 OpenAPI 代码生成？** |
|
||||
1. 在 \`config/config.ts\` 配置 \`openAPI\` 2. 运行 \`npm run openapi\` 3. 自动生成 \`src/services/\` 下的代码
|
|
||||
|
|
||||
→ 更多内容见 [umi FAQ](https://umijs.org/docs/guides/faq)`;
|
|
||||
|
|
||||
export default content; |
|
||||
@ -1,4 +1,3 @@ |
|||||
module.exports = { |
module.exports = { |
||||
content: ['./src/**/*.tsx'], |
content: ['./src/**/*.tsx'], |
||||
darkMode: 'class', |
|
||||
}; |
}; |
||||
|
|||||
@ -0,0 +1 @@ |
|||||
|
module.exports = 'mock-md-content'; |
||||
Loading…
Reference in new issue