I am blue
+I am red
+
+
{msg}
; +} +``` + +注意，用于赋值的键值对对象应当作为 `formatMessage()` 方法的第二个参数传递。 + +渲染的结果如下： + +```html + +张三，今天也是美好的一天！
+ + +张三, what a nice day!
+``` + +## 在组件的参数中使用 + +在某些情况下，您需要将多语言内容作为参数传递给某个组件。可以通过 `intl` 对象来实现： + +```ts | purex +import { Alert } from 'antd'; +import { useIntl } from '@umijs/max'; + +export default function Page() { + const intl = useIntl(); + const msg = intl.formatMessage({ + id: 'welcome', + }); + + return
+
{msg}
; +} +``` + +注意，用于赋值的键值对对象应当作为 `formatMessage()` 方法的第二个参数传递。 + +渲染的结果如下： + +```html + +张三，今天也是美好的一天！
+ + +张三, what a nice day!
+``` + +## 常用接口介绍 + +### `addLocale` 动态添加多语言支持 + +无需创建并编写单独的多语言文件，使用 `addLocale()` 接口可以在运行时动态添加语言支持。它接受三个参数： + +| 参数 | 类型 | 介绍 | +| --------- | -------- | ----------------------------- | +| `name` | `String` | 多语言的 Key | +| `message` | `Object` | 多语言的内容对象 | +| `options` | `Object` | `momentLocale` 和 `antd` 配置 | + +例如，您想要动态引入繁体中文的多语言支持，可以编写代码如下： + +```ts | pure +import { addLocale } from '@umijs/max'; +import zhTW from 'antd/es/locale/zh_TW'; + +addLocale( + 'zh-TW', + { + welcome: '歡迎光臨 Umi 的世界！', + }, + { + momentLocale: 'zh-tw', + antd: zhTW, + }, +); +``` + +### `getAllLocales` 获取多语言列表 + +通过 `getAllLocales()` 接口可以获取当前所有多语言选项的数组，包括通过 `addLocale()` 方法添加的多语言选项。该接口默认会在 `src/locales` 目录下寻找形如 `zh-CN.(js|json|ts)` 的文件，并返回多语言的 Key。 + +```ts | pure +import { getAllLocales } from '@umijs/max'; + +getAllLocales(); +// [en-US, zh-CN, ...] +``` + +### `getLocale` 获取当前选择的语言 + +通过 `getLocale()` 接口可以获取当前选择的语言： + +```ts | pure +import { getLocale } from '@umijs/max'; + +getLocale(); +// zh-CN +``` + +### `useIntl` 获取 `intl` 对象 + +`useIntl()` 很有可能会是您开发中最常用的接口，通过它可以获取 `intl` 对象，并进一步执行 `formatMessage()` 等方法来实现您多元的需求： + +```json +// src/locales/en-US.json +{ + "welcome": "Hi, {name}." +} +``` + +```ts | pure +import { useIntl } from '@umijs/max'; + +const intl = useIntl(); +const msg = intl.formatMessage( + { + id: 'welcome', + }, + { + name: 'Jackson', + }, +); +console.log(msg); +// Hi, Jackson. +``` + +关于 `intl` 对象的更多用法，请参阅 `react-intl` 的[接口文档](https://github.com/formatjs/formatjs/blob/main/website/docs/react-intl/api.md)。 + +### `setLocale` 设置语言 + +通过 `setLocale()` 接口可以使用编程的方法动态设置当前的语言。它有两个参数： + +| 参数 | 类型 | 介绍 | +| ------------ | --------- | ------------------------------------------ | +| `lang` | `String` | 切换到的语言 | +| `realReload` | `Boolean` | 切换时是否刷新页面，默认为 `true` 刷新页面 | + +```ts | pure +import { setLocale } from '@umijs/max'; + +// 切换时刷新页面 +setLocale('en-US'); + +// 切换时不刷新页面 +setLocale('en-US', false); +``` + +## 配置插件 + +您可以在 `config.ts` 中配置国际化插件。默认值如下： + +```ts | pure +export default { + locale: { + antd: false, // 如果项目依赖中包含 `antd`，则默认为 true + baseNavigator: true, + baseSeparator: '-', + default: 'zh-CN', + title: false, + useLocalStorage: true, + }, +}; +``` + +配置的详细介绍如下： + +| 配置项 | 类型 | 默认值 | 介绍 | +| ----------------- | --------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `antd` | `Boolean` | `false`；如果项目包含 `antd` 依赖，则为 `true` | `antd` 的国际化支持。更多介绍可参见[此文档](https://ant.design/docs/react/i18n-cn)。 | +| `baseNavigator` | `Boolean` | `true` | 开启**浏览器语言检测**。默认情况下，当前语言环境的识别按照：`localStorage` 中 `umi_locale` 值 > 浏览器检测 > `default` 设置的默认语言 > `zh-CN` | +| `baseSeparator` | `String` | `-` | 语言（Language）与国家（Country） 之间的**分割符**。默认情况下为 `-`，返回的语言及目录文件为 `zh-CN`、`en-US` 和 `sk` 等。若指定为 `_`，则 `default` 默认为 `zh_CN`。 | +| `default` | `String` | `zh-CN` | 项目**默认语言**。当检测不到具体语言时，使用 `default` 设置的默认语言。 | +| `title` | `Boolean` | `false` | 开启[**标题国际化**](#标题国际化)。 | +| `useLocalStorage` | `Boolean` | `true` | 自动使用 `localStorage` 保存当前使用的语言。 | + +### 标题国际化 + +在路由配置中添加 `title` 项即可启用国际化支持，自动将页面的标题转为对应的多语言内容。 + +例如，编写多语言文件如下： + +```ts | pure +// src/locales/zh-CN.ts +export default { + 'site.title': 'Umi - 企业级 React 应用开发框架', + 'about.title': 'Umi - 关于我', +}; +``` + +```ts | pure +// src/locales/en-US.ts +export default { + 'site.title': 'Umi - Enterprise-level React Application Framework', + 'about.title': 'Umi - About me', +}; +``` + +配置路由内容如下： + +```json +// route.json + [ + { + "path": "/login", + "component": "@/layouts/UserLayout" + }, + { + "path": "/", + "component": "@/layouts/BasicLayout", + "routes": [ + { + "path": "/", + "redirectTo": "/welcome" + }, + { + "path": "/welcome", + "name": "首页", + "icon": "welcome", + "locale": "welcome", + "component": "@/pages/Index/index" + }, + ] + } + ], +``` + +## 运行时拓展 + +国际化插件允许您在运行时对它进行一些拓展与定制。 + +### 自定义 `getLocale` + +您可以自定义获取页面语言 `getLocale()` 方法的逻辑，例如通过识别链接 `?locale=en-US`，将 `en-US` 作为当前页面的语言： + +```ts | pure +// src/app.ts +import qs from 'qs'; + +export const locale = { + getLocale() { + const { search } = window.location; + const { locale = 'zh-CN' } = qs.parse(search, { ignoreQueryPrefix: true }); + return locale; + }, +}; +``` + +## FAQ + +### 为什么不直接使用 `formatMessage` 这个语法糖？ + +虽然 `formatMessage` 直接使用起来会非常方便，但是它脱离了 React 的生命周期，最严重的问题就是切换语言时无法触发 DOM 的重新渲染。为了解决这个问题，我们切换语言时就需要刷新一下浏览器，用户体验很差。所以推荐大家使用 `useIntl` 或者 `injectIntl`，可以实现同样的功能。 + +## License + +Licensed under the MIT License. diff --git a/examples/website2/docs/guide/mock.md b/examples/website2/docs/guide/mock.md new file mode 100644 index 000000000..4280a8863 --- /dev/null +++ b/examples/website2/docs/guide/mock.md @@ -0,0 +1,143 @@ +--- +nav: 教程 +group: 页面开发 +order: 4 +--- + +# Mock + +antdp 提供了开箱即用的 Mock 功能，能够用方便简单的方式来完成 Mock 数据的设置。 + + +什么是 Mock 数据：在前后端约定好 API 接口以后，前端可以使用 Mock 数据来在本地模拟出 API 应该要返回的数据，这样一来前后端开发就可以同时进行，不会因为后端 API +还在开发而导致前端的工作被阻塞。 + + +## 目录约定 + +Umi 约定 /mock 目录下的所有文件为 Mock 文件，例如这样的目录结构： + +```text +. +├── mock + ├── todos.ts + ├── items.ts + └── users.ts +└── src + └── pages + └── index.tsx +``` + +则 /mock 目录中的 todos.ts, items.ts 和 users.ts 就会被 Umi 视为 Mock 文件 来处理。 + +## Mock 文件 + +Mock 文件默认导出一个对象，而对象的每个 Key 对应了一个 Mock 接口，值则是这个接口所对应的返回数据，例如这样的 Mock 文件： + +```ts +// ./mock/users.ts + +export default { + // 返回值可以是数组形式 + 'GET /api/users': [ + { id: 1, name: 'foo' }, + { id: 2, name: 'bar' }, + ], + + // 返回值也可以是对象形式 + 'GET /api/users/1': { id: 1, name: 'foo' }, +}; +``` + +就声明了两个 Mock 接口，透过 GET /api/users 可以拿到一个带有两个用户数据的数组，透过 GET /api/users/1 可以拿到某个用户的模拟数据。 + +## 请求方法 + +当 Http 的请求方法是 GET 时，可以省略方法部分，只需要路径即可，例如： + +```ts +// ./mock/users.ts + +export default { + '/api/users': [ + { id: 1, name: 'foo' }, + { id: 2, name: 'bar' }, + ], + + '/api/users/1': { id: 1, name: 'foo' }, +}; +``` + +也可以用不同的请求方法，例如 POST: + +```ts +// ./mock/users.ts + +export default { + 'POST /api/users': { result: 'true' }, + + 'PUT /api/users/1': { id: 1, name: 'new-foo' }, +}; +``` + +## 自定义函数 + +除了直接静态声明返回值，也可以用函数的方式来声明如何计算返回值，例如： + +```ts +export default { + 'POST /api/users/create': (req, res) => { + // 添加跨域请求头 + res.setHeader('Access-Control-Allow-Origin', '*'); + res.end('ok'); + }, +}; +``` + +关于 `req` 和 `res` 的 API 可参考 [Express@4](https://moexpressjs.com/en/api.html) 官方文档 来进一步了解。 + +## defineMock + +另外，也可以使用 defineMock 类型帮助函数来提供编写 mock 对象的代码提示，如： + +```ts +import { defineMock } from '@umijs/max'; + +export default defineMock({ + '/api/users': [ + { id: 1, name: 'foo' }, + { id: 2, name: 'bar' }, + ], + '/api/users/1': { id: 1, name: 'foo' }, + 'GET /api/users/2': (req, res) => { + res.status(200).json({ id: 2, name: 'bar' }); + }, +}); +``` + +`defineMock` 仅仅提供类型提示，入参与出参完全一致。 + +或是用环境变量的方式关闭： + +```bash +MOCK=none max dev +``` + +## 引入 Mock.js + +在 Mock 中我们经常使用 [Mock.js](http://mockjs.com/) 来帮我们方便的生成随机的模拟数据，如果你使用了 Umi 的 Mock 功能，建议你搭配这个库来提升模拟数据的真实性： + +```ts +import mockjs from 'mockjs'; + +export default { + // 使用 mockjs 等三方库 + 'GET /api/tags': mockjs.mock({ + 'list|100': [{ name: '@city', 'value|1-100': 50, 'type|0-2': 1 }], + }), +}; +``` + +## License + +Licensed under the MIT License. diff --git a/examples/website2/docs/guide/new-page.md b/examples/website2/docs/guide/new-page.md new file mode 100644 index 000000000..e935f89a0 --- /dev/null +++ b/examples/website2/docs/guide/new-page.md @@ -0,0 +1,181 @@ +--- +nav: 教程 +order: 1 +group: + title: 页面开发 + order: 2 +--- + +# 新增页面 + +这里的『页面』指配置了路由，能够通过链接直接访问的模块，要新建一个页面，通常可以在脚手架的基础上进行简单的配置。 + +## 页面代码结构推荐 + +为了让项目代码组织更加规范，让开发能够更方便的定位到相关页面组件代码，我们定义了一套规范，该规范当前只作为推荐的指导，并非强制。 + +```bash +src +├── components +└── pages + ├── Welcome # 路由组件下不应该再包含其他路由组件，基于这个约定就能清楚的区分路由组件和非路由组件了 + | ├── components # 对于复杂的页面可以再自己做更深层次的组织，但建议不要超过三层 + | | ├── Form.tsx + | ├── index.tsx # 页面组件的代码 + | └── index.less # 页面样式 + ├── Order # 路由组件下不应该再包含其他路由组件，基于这个约定就能清楚的区分路由组件和非路由组件了 + | ├── index.tsx + | └── index.less + ├── User + | ├── components # group 下公用的组件集合 + | ├── Login # group 下的页面 Login + | ├── Register # group 下的页面 Register + | └── util.ts # 这里可以有一些共用方法之类，不做推荐和约束，看业务场景自行做组织 + └── * # 其它页面组件代码 +``` + +所有路由组件（会配置在路由配置中的组件）我们推荐以大驼峰命名打平到 pages 下面第一级（复杂的项目可以增加 group 层级，在 group 下放置 pages）。不建议在路由组件内部再嵌套路由组件 - 不方便分辨一个组件是否是路由组件，而且不方便快速从全局定位到路由组件。 + +我们推荐尽可能的拆分路由组件为更细粒度的组件，对于多个页面可能会用到的组件我们推荐放到 src/components 中，对于只是被单个页面依赖的（区块）组件，我们推荐就近维护到路由组件文件夹下即可。 + +## 手动创建 + +新增 tsx、less 文件 +在 src / pages 下创建新的 tsx，less 文件。 如果有多个相关页面，您可以创建一个新文件夹来放置相关文件。 + +```diff +config +src +models + pages ++ NewPage ++ index.less ++ index.tsx + ... +... +package.json +``` + +为了更好的演示，我们初始化 NewPage.tsx 的内容如下： + +```bash +export default () => { + returnx react-query
+ {isError &&请求 API 错误 ...
} + {isLoading &&Loading ...
} + {data &&现在有 {data.stargazers_count} 颗星！
} +