diff --git a/docs/docs/docs/max/data-flow.en-US.md b/docs/docs/docs/max/data-flow.en-US.md index a7a6e73f9b9a..48ad620e9d07 100644 --- a/docs/docs/docs/max/data-flow.en-US.md +++ b/docs/docs/docs/max/data-flow.en-US.md @@ -1,31 +1,30 @@ --- order: 5 toc: content -translated_at: '2024-03-17T09:24:49.645Z' +translated_at: '2024-03-18T00:49:20.502Z' --- -```markdown # Data Stream -`@umi/max` has a built-in **data stream management** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/model.ts), which is a lightweight data management solution based on the `hooks` paradigm. It allows managing global shared data in Umi projects. +`@umi/max` has a built-in **data flow management** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/model.ts), which is a lightweight data management solution based on the `hooks` paradigm. It can be used to manage global shared data in Umi projects. ## Getting Started ### Creating a Model -The data stream management plugin adopts a conventional directory structure. We agree that you can include Model files in the `src/models`, `src/pages/xxxx/models/` directory, and `src/pages/xxxx/model.{js,jsx,ts,tsx}` files. -Model files can use `.(tsx|ts|jsx|js)` four suffix formats, the **namespace** generation rule is as follows. +The data flow management plugin adopts a conventional directory structure. We agree that Model files can be introduced in the `src/models`, `src/pages/xxxx/models/` directories, and in `src/pages/xxxx/model.{js,jsx,ts,tsx}` files. +Model files can have one of four suffix formats: `.(tsx|ts|jsx|js)`. The **namespace** generation rule is as follows. -| Path | Namespace | Explanation | +| Path | Namespace | Description | | :--- |:--- | :--- | -| `src/models/count.ts` | `count` | `src/models` directory does not support nested directory definition model | +| `src/models/count.ts` | `count` | Defining model in `src/models` directory does not support directory nesting | | `src/pages/pageA/model.ts` | `pageA.model` | | | `src/pages/pageB/models/product.ts` | `pageB.product` | | -| `src/pages/pageB/models/fruit/apple.ts` | `pageB.fruit.apple` | `pages/xxx/models` under model definition supports nested definition | +| `src/pages/pageB/models/fruit/apple.ts` | `pageB.fruit.apple` | Definition in `pages/xxx/models` supports nested models | -A Model is essentially a custom `hooks` that doesn't involve any "black magic" that users need to worry about. +A Model is essentially a custom `hook` with no "black magic" for the user to worry about. -When you need to get the global data in the Model, you can call its namespace. For example, for the Model file `userModel.ts`, its namespace is `userModel`. +When we need to access the global data in the Model, we can call the namespace directly. For example, for a Model file `userModel.ts`, its namespace is `userModel`. Write a function with a default export: @@ -40,13 +39,13 @@ export default function Page() { }; ``` -This is a Model. The plugin's job is to turn the state or data within it into **global data**, so when different components use this Model, they get the same set of state or data. +This is a Model. What the plugin does is turn the state or data in it into **global data**, providing the same state or data to different components using that Model. :::info{title=💡} -The Model file needs to default export a function, which defines a `hook`. Files that do not comply with this specification will be filtered out and cannot be called by namespace. +The Model file needs to export a function by default, which defines a `hook`. Files that do not conform to this standard will be filtered out and cannot be called by namespace. ::: -The Model can use other `hooks`, taking a counter as an example: +It's allowed to use other `hooks` in a Model. Take a counter as an example: ```ts // src/models/counterModel.ts @@ -62,7 +61,7 @@ export default function Page() { }; ``` -In project practice, we usually need to request backend interfaces to obtain the required data. Now let's extend the previous example of getting user information: +In real-world projects, we usually need to request backend interfaces to obtain the data we need. Now let's expand the previous example of fetching user information: ```ts // src/models/userModel.ts @@ -110,9 +109,9 @@ export default function Page() { }; ``` -### Using Model +### Using a Model -Now, if you want to use a global Model in a specific component. Taking user information as an example, just call the `useModel` hook function: +Now, you want to use a global Model in a certain component. Taking the user information as an example, you only need to call the `useModel` hook function: ```tsx // src/components/Username/index.tsx @@ -127,17 +126,17 @@ export default function Page() { } ``` -In this case, the `useModel()` method's parameter is the Model's **namespace**. +The `useModel()` method's argument is the Model's **namespace**. :::info{title=💡} -If you use VSCode as the IDE for developing Umi projects, it is recommended to use in conjunction with the [@umijs/plugin-model](https://marketplace.visualstudio.com/items?itemName=litiany4.umijs-plugin-model) plugin. It allows you to quickly jump to the file that defines the Model: +If you use VSCode as the IDE for developing Umi projects, it's recommended to use it in conjunction with the [@umijs/plugin-model](https://marketplace.visualstudio.com/items?itemName=litiany4.umijs-plugin-model) plugin. It allows you to quickly jump to the file that defines the Model: -![vscode - @umijs/plugin-model plugin demonstration](https://gw.alipayobjects.com/zos/antfincdn/WcVbbF6KG2/1577073518336-afe6f03d-f817-491a-848a-5feeb4ecd72b.gif) +![vscode - @umijs/plugin-model plugin demo](https://gw.alipayobjects.com/zos/antfincdn/WcVbbF6KG2/1577073518336-afe6f03d-f817-491a-848a-5feeb4ecd72b.gif) ::: ## Performance Optimization -The `useModel()` method can accept an optional second parameter. When the component only needs to use part of the Model's parameters and is not interested in the changes of other parameters, a function can be passed in for filtering. Taking the operation buttons of the counter as an example: +The `useModel()` method can accept an optional second parameter. When a component only needs to use part of the Model and is not interested in changes to other parameters, you can pass in a function to filter. Take the operation button for the counter as an example: ```tsx // src/components/CounterActions/index.tsx @@ -158,17 +157,17 @@ export default function Page() { }; ``` -The above component is not concerned with the `counter` value in the counter Model, only needing to use the `increment()` and `decrement()` methods provided by the Model. Thus, we passed in a function as the second parameter of the `useModel()` method, whose return value will serve as the `useModel()` method's return value. +The above component is not interested in the `counter` value in the counter Model, and only needs to use the `increment()` and `decrement()` methods provided by the Model. Therefore, we passed in a function as the second argument for the `useModel()` method, and its return value will be used as the return value of the `useModel()` method. -This way, we filter out the frequently changing `counter` value, avoiding performance loss caused by repeated rendering of the component. +This way, we have filtered out the frequently changing `counter` value, avoiding the performance loss caused by the component's repetitive rendering. ## Global Initial State -`@umi/max` has a built-in **global initial state management** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts), allowing you to quickly build and obtain the global initial state of Umi projects within components. +`@umi/max` has a built-in **global initial state management** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts), which allows you to quickly build and access the global initial state of Umi projects within components. The global initial state is a special Model. -The global initial state is created at the very beginning of the entire Umi project. Write the `getInitialState()` export method in `src/app.ts`, whose return value will become the global initial state. For example: +The global initial state is created at the very beginning of the entire Umi project. Write the export method `getInitialState()` in `src/app.ts`, and its return value will become the global initial state. For example: ```ts // src/app.ts @@ -180,7 +179,7 @@ export async function getInitialState() { } ``` -Now, various plugins and components you define can directly obtain this global initial state through `useModel('@@initialState')`, as shown below: +Now, various plugins and your defined components can directly access this global initial state through `useModel('@@initialState')` as shown below: ```tsx import { useModel } from 'umi'; @@ -192,30 +191,30 @@ export default function Page() { }; ``` -| Object Property | Type | Introduction | +| Object Property | Type | Description | | --- | --- | --- | | `initialState` | `any` | The return value of the exported `getInitialState()` method | -| `loading` | `boolean` | Whether the `getInitialState()` or `refresh()` method is in progress. Before the initial state is first obtained, the rendering of other parts of the page will be **blocked** | -| `error` | `Error` | If the exported `getInitialState()` method throws an error, the error message | +| `loading` | `boolean` | Whether the `getInitialState()` or `refresh()` method is in progress. Before the initial state is obtained for the first time, the rendering of other parts of the page will be **blocked** | +| `error` | `Error` | If an error occurs while running the exported `getInitialState()` method, the error message | | `refresh` | `() => void` | Re-execute the `getInitialState` method and obtain a new global initial state | -| `setInitialState` | `(state: any) => void` | Manually set the value of `initialState`, after manual setting, `loading` will be set to `false` | +| `setInitialState` | `(state: any) => void` | Manually set the value of `initialState`, after manually setting it, `loading` will be set to `false` | -## Qiankun Parent-Child Application Communication +## Qiankun Parent-Child Communication -`@umi/max` has a built-in **Qiankun Microfrontend** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts), when using the data stream plugin, it allows micro-applications to obtain the parent application's data Model passed to the child application through the `useModel('@@qiankunStateFromMaster')` method, thereby achieving communication between parent and child applications. +`@umi/max` has a built-in **Qiankun Micro-Frontend** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts), which allows micro-applications to obtain the data Model passed from the parent application through the `useModel('@@qiankunStateFromMaster')` method, thereby achieving communication between parent and child applications. -For specific usage methods, please refer to the section on parent-child application communication in microfrontend. +For specific usage, please refer to the [micro-frontend's parent-child communication chapter](./micro-frontend#parent-child-communication). ## API ### `useModel` -`useModel()` is a hook function that provides the capability to use Model. It accepts two parameters: +`useModel()` is a hook function that provides the ability to use a Model. It accepts two parameters: -| Parameter | Type | Introduction | +| Parameter | Type | Description | | --- | --- | --- | | `namespace` | `String` | The namespace of the Model file | -| `updater` | `(model: any) => any` | An optional parameter. Pass in a function, whose return value is the Model state or data currently needed in the component, and serves as the return value of the `useModel()` method. It is of significant importance for optimizing component performance. | +| `updater` | `(model: any) => any` | Optional parameter. Passing in a function, the return value of which is the Model state or data currently needed by the component, and it serves as the return value of the `useModel()` method. It plays a significant role in optimizing component performance. | ```tsx // src/components/AdminInfo/index.tsx