Skip to content

Commit

Permalink
docs: fix format in max/data-flow.en-US.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@sorrycc
sorrycc committed Mar 18, 2024
1 parent 4957ad2 commit 849caed
Showing 1 changed file with 34 additions and 35 deletions.
69 changes: 34 additions & 35 deletions docs/docs/docs/max/data-flow.en-US.md
View file
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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';
Expand All @@ -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
Expand Down

0 comments on commit 849caed

Please sign in to comment.