@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

package/docs/zh/guides/topic-detail/micro-frontend/c03-main-app.mdx

@@ -1,296 +0,0 @@
----
-sidebar_position: 3
-title: 开发主应用
----
-
-# 开发主应用
-
-在上一章 [体验微前端](/guides/topic-detail/micro-frontend/c02-development) 通过一个示例演示了如何创建和配置微前端子应用，通过本章你可以进一步了解如何开发主应用，以及它的常见配置。
-
-在通过 `@modern-js/create` 命令创建 Modern.js 工程后，可以在项目中执行 `pnpm run new`（实际执行了 `modern new` 命令），在选择了「微前端」模式后，会安装微前端依赖依赖，只需手动注册插件即可。
-
-import EnableMicroFrontend from '@site-docs/components/enable-micro-frontend';
-
-<EnableMicroFrontend />
-
-## 注册子应用信息
-
-当在 `masterApp` 配置上提供了信息后，将会认为该应用为主应用，目前存在两种子应用信息的配置方式，这两种方式分别应用于不同的场景。
-
-### 直接注册子应用信息
-
-可以直接通过配置注册子应用信息：
-
-:::tip 提示
-可以通过 API [defineConfig](/apis/app/runtime/app/define-config) 在运行时进行配置。
-当参数为函数时无法被序列化到产物代码，所以在涉及到函数之类的配置时请通过 defineConfig 来进行配置
-
-:::
-
-import MicroRuntimeConfig from '@site-docs/components/micro-runtime-config';
-
-<MicroRuntimeConfig />
-
-### 自定义远程应用列表
-
-通过该函数可以拉取远程的子应用列表，并将其注册至运行时框架：
-
-```ts title="src/modern.runtime.ts"
-import { defineRuntimeConfig } from '@modern-js/runtime';
-
-export default defineRuntimeConfig({
-  masterApp: {
-    manifest: {
-      getAppList: async () => {
-        // 可以从其他远程接口获取
-        return [
-          {
-            name: 'Table',
-            entry: 'http://localhost:8081',
-            // activeWhen: '/table'
-          },
-          {
-            name: 'Dashboard',
-            entry: 'http://localhost:8082',
-            // activeWhen: '/dashboard'
-          },
-        ];
-      },
-    },
-  },
-});
-```
-
-## 渲染子应用
-
-在微前端中分为两种加载子应用的方式：
-
-1. **子应用组件** 获取到每个子应用的组件，之后就可以像使用普通的 `React` 组件一样渲染微前端的子应用。
-2. **集中式路由** 通过集中式的路由配置，自动根据当前页面 `pathname` 激活渲染对应的子应用。
-
-### 子应用组件
-
-开发者使用 `useModuleApps` 方法可以获取到各个子应用的组件。
-
-再通过 `router` 组件的结合运用，开发者可以自控式的根据不同的路由渲染不同的子应用。
-
-假设我们的子应用列表配置如下：
-
-<EnableMicroFrontend />
-
-编辑主应用 `App.tsx` 文件如下：
-
-```js title="App.tsx"
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-
-import {
-  RouterProvider,
-  Route,
-  createBrowserRouter,
-  createRoutesFromElements,
-  BrowserRouter,
-  Link,
-  Outlet,
-} from '@modern-js/runtime/router';
-
-const AppLayout = () => (
-  <>
-    <div>
-      <Link to={'/table'}>加载约定式路由子应用</Link>
-    </div>
-    <div>
-      <Link to={'/dashboard'}>加载自控式路由子应用</Link>
-    </div>
-    <div>
-      <Link to={'/'}>卸载子应用</Link>
-    </div>
-    <Outlet />
-  </>
-);
-
-export default () => {
-  const { apps, MApp } = useModuleApps();
-
-  // 使用的不是 MApp 组件，需要使用 createBrowserRouter 来创建路由
-  const router = createBrowserRouter(
-    createRoutesFromElements(
-      <Route path="/" element={<AppLayout />}>
-        {apps.map(app => {
-          const { Component } = app;
-          // 模糊匹配，path 需要写成类似 abc/* 的模式
-          return (
-            <Route
-              key={app.name}
-              path={`${app.name.toLowerCase()}/*`}
-              element={
-                <Component
-                  loadable={{
-                    loading: ({ pastDelay, error }: any) => {
-                      if (error) {
-                        return <div>error: {error?.message}</div>;
-                      } else if (pastDelay) {
-                        return <div>loading</div>;
-                      } else {
-                        return null;
-                      }
-                    },
-                  }}
-                />
-              }
-            />
-          );
-        })}
-      </Route>,
-    ),
-  );
-
-  return (
-    // 方法一：使用 MApp 自动根据配置的 activeWhen 参数加载子应用(本项目配置在 modern.config.ts 中)
-    // <BrowserRouter>
-    //   <MApp />
-    // </BrowserRouter>
-
-    // 方法二：手动写 Route 组件方式加载子应用，方便于需要鉴权等需要前置操作的场景
-    <>
-      <RouterProvider router={router} />
-    </>
-  );
-};
-```
-
-这里通过 `Route` 组件自定义了 **Table** 的激活路由为 **/table**， **Dashboard** 的激活路由为 **/dashboard**。
-
-### 集中式路由
-
-**集中式路由** 是将子应用的激活路由集中配置的方式。我们给子应用列表信息添加 `activeWhen` 字段来启用 **集中式路由**。
-
-<MicroRuntimeConfig />
-
-然后在主应用中使用 `useModuleApp` 方法获取 `MApp` 组件, 并在主应用渲染 `MApp`。
-
-```tsx title=主应用：App.tsx
-import { useModuleApp } from '@modern-js/plugin-garfish/runtime';
-
-function App() {
-  const { MApp } = useModuleApps();
-
-  return (
-    <div>
-      <MApp />
-    </div>
-  );
-}
-```
-
-这样启动应用后，访问 `/table` 路由，会渲染 `Table` 子应用，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用。
-
-### 两种模式混用
-
-当然 **子应用组件** 和 **集中式路由** 是可以混合使用的。
-
-- 一部分子应用作为 **子应用组件** 激活，另外一部分作为 **集中式路由** 激活。
-- 一部分子应用既可以作为 **集中式路由** 激活，也可以作为 **子应用组件** 激活。
-
-### 添加 loading
-
-通过配置 `loadable` 配置，可以为「集中式路由」、「子应用」添加 loading 组件，并可以考虑错误、超时、闪烁等情况的出现，从而为用户提供更好的用户体验。该功能的设计与实现参考至 [react-loadable](https://github.com/jamiebuilds/react-loadable)，基本功能较为相似。
-
-```tsx
-function Loading() {
-  return <div>Loading...</div>;
-}
-
-function App(){
-  return <>
-    <Table
-      loadable={{
-        loading: Loading,
-      }}
-    />
-  <>
-}
-```
-
-#### 增加错误状态
-
-当微前端子应用加载失败或渲染失败时，`loading component` 将会接收 `error` 参数（若没有错误时 error 是 null）
-
-```tsx
-function Loading({ error }) {
-  if (error) {
-    return <div>Error msg {error?.message}</div>;
-  } else {
-    return <div>Loading...</div>;
-  }
-}
-```
-
-#### 避免 loading 闪退
-
-有时 loading 组件的显示时间可能小于 200ms，这个时候会出现 loading 组件闪退的情况。许多用户研究证明，loading 闪退的情况会导致用户感知加载内容的耗时比实际耗时更长，在 loading 小于 200ms 时，不展示内容，用户会认为它更快。
-
-所以 loading 组件还提供了 `pastDelay` 参数，超过设置的延迟展示时才会为 true，可以通过 `delay` 参数设置延迟的时长
-
-```tsx
-function Loading({ error, pastDelay }) {
-  if (error) {
-    return <div>Error! {error?.message}</div>;
-  } else if (pastDelay) {
-    return <div>Loading...</div>;
-  } else {
-    return null;
-  }
-}
-```
-
-`delay` 的默认值为 `200ms`，可以通过 `loadable` 中的 `delay` 来设置延迟展示的时间
-
-```tsx
-
-function App(){
-  return <>
-    <Table
-      loadable={{
-        loading: Loading,
-        delay: 300 // 0.3 seconds
-      }}
-    />
-  <>
-}
-```
-
-#### 增加超时状态
-
-有时因为网络的原因，从而导致微前端子应用加载失败，从而导致一直展示 loading 的状态，这对于用户而言非常糟糕，因为他们不知道合适才会获得具体的响应，他们是否需要刷新页面，通过增加超时状态可以很好的解决该问题。
-
-loading 组件在超时时会获得 `timeOut` 参数，当微前端应用加载超时时将会获得 `timeOut` 属性值为 true
-
-```tsx
-function Loading({ error, timeOut, pastDelay }) {
-  if (error) {
-    return <div>Error! {error?.message}</div>;
-  } else if (timeOut) {
-    return <div>Loading timed out, please refresh the page... </div>;
-  } else if (pastDelay) {
-    return <div>Loading...</div>;
-  } else {
-    return null;
-  }
-}
-```
-
-超时状态是关闭的，可以通过在 `loadable` 中设置 `timeout` 参数开启
-
-```tsx
-
-function App(){
-  return <>
-    <Table
-      loadable={{
-        loading: Loading,
-        timeOut: 10000 // 10s
-      }}
-    />
-  <>
-}
-```

package/docs/zh/guides/topic-detail/micro-frontend/c04-communicate.mdx

@@ -1,58 +0,0 @@
----
-sidebar_position: 4
-title: 主子应用通信
----
-
-# 主子应用通信
-
-## props 通信
-
-Modern.js 中，会将子应用包裹成一个 React 组件，直接通过给 React 组件传递 `props` 即可实现主应用和子应用通信的目的。
-
-```tsx title=主应用：App.tsx
-function App() {
-  const { MApp } = useModuleApps();
-
-  return (
-    <div>
-      <MApp count={100} />
-    </div>
-  );
-}
-```
-
-```tsx title=子应用：App.tsx
-function App(props) {
-  console.log(props);
-  return ...
-}
-```
-
-子应用将会打印 `{count: 0}`，目前尚未支持子应用渲染响应式，及时在主应用上更改 `count` 的数据也不会触发视图更新
-
-## channel 通信
-
-[Garfish.channel](https://www.garfishjs.org/api/channel) 用于应用间的通信。它是 `EventEmitter2` 的实例
-
-```ts
-// 子应用监听登录事件
-const App = () => {
-  const handleLogin = userInfo => {
-    console.log(`${userInfo.name} has login`);
-  };
-
-  useEffect(() => {
-    window?.Garfish.channel.on('login', handleLogin);
-    return () => {
-      window?.Garfish.channel.removeListener('login', handleLogin);
-    };
-  });
-};
-
-// 主应用触发监听事件
-api.getLoginInfo.then(res => {
-  if (res.code === 0) {
-    window.Garfish.channel.emit('login', res.data);
-  }
-});
-```

package/docs/zh/guides/topic-detail/micro-frontend/c05-mixed-stack.mdx

@@ -1,27 +0,0 @@
----
-sidebar_position: 5
-title: 混合技术栈
----
-
-# 混合技术栈
-
-Modern.js 微前端方案是基于 [Garfish](https://garfishjs.org/) 封装的，提供了一些更开箱即用的使用方式。
-
-当你的主应用和子应用不全是 Modern.js 应用的时候，可以参考这篇文档。
-
-1. 子应用是 **Modern.js**，主应用使用的原生 Garfish 微前端。
-2. 主应用是 **Modern.js**，子应用有的是其它技术栈。
-
-## 子应用是 Modern.js
-
-**Modern.js** 子应用编译后会生成标准的 [Garfish 子应用导出](https://www.garfishjs.org/guide/start#2%E5%AF%BC%E5%87%BA-provider-%E5%87%BD%E6%95%B0)。
-所以可以直接接入标准的微前端主应用。
-
-:::info
-子应用是 **Modern.js**，主应用使用的原生 Garfish 微前端时，**子应用调试模式** 不可用。
-
-:::
-
-## 主应用是 Modern.js
-
-主应用是 **Modern.js**，子应用用的其它技术栈。子应用按照 [Garfish 子应用标准](https://www.garfishjs.org/guide/demo/react) 开发即可。

package/docs/zh/guides/topic-detail/model/_meta.json

@@ -1,14 +0,0 @@
-[
-  "quick-start",
-  "define-model",
-  "use-model",
-  "computed-state",
-  "manage-effects",
-  "auto-actions",
-  "model-communicate",
-  "performance",
-  "typescript-best-practice",
-  "redux-integration",
-  "use-out-of-modernjs",
-  "faq"
-]

package/docs/zh/guides/topic-detail/model/auto-actions.mdx

@@ -1,88 +0,0 @@
-# 自动生成 Actions
-
-在 [快速上手](/guides/topic-detail/model/quick-start) 中，我们实现最简单的计数器 Model 也需要 10 行代码。
-实际上，Modern.js 支持根据声明的 `state` 类型，自动生成常用的 Actions，从而简化模板代码量。当前支持的类型有：
-
-- 原始数据类型
-- 数组类型
-- 简单对象类型（Plain Object）
-
-## 原始数据类型
-
-```ts
-const countModel = model('count').define({ state: 1 });
-```
-
-如上我们仅用一行就完成了一个简单的 `countModel`。使用 Model 的示例代码如下：
-
-```tsx
-function Counter() {
-  const [state, actions] = useModel(countModel);
-
-  useEffect(() => {
-    // 增加 1
-    actions.setState(state + 1);
-  }, []);
-}
-```
-
-## 数组类型
-
-当 State 为数组类型时，自动生成 Actions 的示例代码如下：
-
-```ts
-const countModel = model('count').define({ state: [] });
-
-function Counter() {
-  const [state, actions] = useModel(countModel);
-
-  useEffect(() => {
-    actions.push(1);
-    actions.pop();
-    actions.shift();
-    actions.unshift(1);
-    actions.concat([1]);
-    actions.splice(0, 1, 2);
-    actions.filter(value => value > 1);
-  }, []);
-}
-```
-
-我们可以使用 JavaScript Array 对象的方法，修改 State。
-
-## 简单对象类型
-
-当 State 为简单对象类型时，自动生成 Actions 的示例代码如下：
-
-```ts
-const countModel = model('count').define({
-  state: {
-    a: 1,
-    b: [],
-    c: {},
-  },
-});
-
-function Counter() {
-  const [state, actions] = useModel(countModel);
-
-  useEffect(() => {
-    actions.setA(2);
-    actions.setB([1]);
-    actions.setC({ a: 1 });
-  }, []);
-}
-```
-
-根据 `a`、`b`、`c` 三个不同的字段分别生成 `setA`、`setB`、`setC` 三个 Actions。
-
-:::info
-当用户自定义的 Action 和 Modern.js 自动生成的 Action 名字一致时，用户自定义的 Action 优先级更高。例如，
-在 `countModel` 中已经自定义 `setA` 这个 Action，调用 `actions.setA()` 时，最终执行的是用户自定义的 `setA`。
-
-:::
-
-:::info 补充信息
-相关 API 的更多介绍，请参考[这里](/apis/app/runtime/model/auto-actions)。
-
-:::

package/docs/zh/guides/topic-detail/model/computed-state.mdx

@@ -1,147 +0,0 @@
-# 衍生状态
-
-一些场景中，组件需要对 Model 中的 State 进行进一步计算，才能在组件中使用，这部分逻辑可以直接写在组件内部，也可以通过 Model 的衍生状态实现。
-衍生状态定义在 Model 中的 `computed` 字段下。根据依赖的 Model 的不同、返回类型的不同，衍生状态的定义方法可以分为以下 3 种。
-
-## 只依赖自身的 State
-
-衍生状态只依赖当前 Model 的 State，State 会作为第一个参数，传入衍生状态的定义函数中。
-
-例如， todo 应用的 State 有 `items` 和 `filter`，`filter` 用于过滤当前页面显示的 todo 项，所以我们定义了一个 `visibleTodos` 的衍生状态可以直接在组件中使用。示例代码如下：
-
-```ts
-/**
- *  假设 todo item 结构如下：
-{
-    id: string;          // id
-    text: string;        // todo 事项
-    completed: boolean;  // 完成状态：0 代表未完成，1 代表完成
-}
-**/
-
-const todoModel = model('todo').define({
-  state: {
-    items: [],
-    filter: 'ALL', // ALL: 显示全部；COMPLETED：显示完成的事项；ACTIVE：显示未完成的事项
-  },
-  computed: {
-    visibleTodos: state => {
-      switch (state.filter) {
-        case 'ALL':
-          return state.items;
-        case 'COMPLETED':
-          return todos.filter(t => t.completed);
-        case 'ACTIVE':
-          return todos.filter(t => !t.completed);
-        default:
-          return [];
-      }
-    },
-  },
-});
-```
-
-衍生状态最终会和 Model 的 State 进行合并，因此，可以通过 Model 的 State 对象访问到衍生状态，例如，`visibleTodos` 在组件内的使用方式如下：
-
-```ts
-function Todo() {
-  const [state, actions] = useModel(todoModel);
-
-  return (
-    <div>
-      <div>
-        {state.visibleTodos.map(item => (
-          <div key={item.id}>{item.text}</div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-## 依赖其他 Model 的 State
-
-除了依赖当前 Model 的 State，衍生状态还依赖其他 Model 的 State，这时候衍生状态的定义格式为：
-
-```ts
-[stateKey]: [...depModels, (selfState, ...depModels) => computedState]
-```
-
-下面的示例，演示了 `barModel` 的衍生状态 `combinedValue` 是如何依赖 `fooModel` 的 State 的。
-
-```ts
-const fooModel = model('foo').define({
-  state: {
-    value: 'foo',
-  },
-});
-
-const barModel = model('bar').define({
-  state: {
-    value: 'foo',
-  },
-  computed: {
-    combinedValue: [
-      fooModel,
-      (state, fooState) => state.value + fooState.value,
-    ],
-  },
-});
-```
-
-## 函数类型的衍生状态
-
-衍生状态还可以返回一个函数。这时候衍生状态的定义格式为：
-
-```ts
-[stateKey]: (state) => (...args) => computedState    // 只依赖自身的 state
-[stateKey]: [...depModels, (selfState, ...depModels) => (...args) => computedState]  // 依赖其他 Model 的 state
-```
-
-假设，todo 应用的 state 不存储 `filter` 状态，而是直接在组件中使用，那么 `visibleTodos` 可以是一个函数类型的值，这个函数在组件中使用的时候，接收 `filter` 参数。如下所示：
-
-```ts
-const todoModel = model('todo').define({
-  state: {
-    items: [],
-  },
-  computed: {
-    visibleTodos: state => filter => {
-      switch (filter) {
-        case 'ALL':
-          return state.items;
-        case 'COMPLETED':
-          return todos.filter(t => t.completed);
-        case 'ACTIVE':
-          return todos.filter(t => !t.completed);
-        default:
-          return [];
-      }
-    },
-  },
-});
-
-function Todo(props) {
-  // filter 状态通过 props 传入
-  const { filter } = props;
-  const [state, actions] = useModel(todoModel);
-
-  // 计算得到最终要显示的 todos
-  const todos = state.visibleTodos(filter);
-
-  return (
-    <div>
-      <div>
-        {todos.map(item => (
-          <div key={item.id}>{item.text}</div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-:::info 更多参考
-[使用 Model](/guides/topic-detail/model/computed-state)
-
-:::

package/docs/zh/guides/topic-detail/model/define-model.mdx

@@ -1,63 +0,0 @@
-# 创建 Model
-
-上一节的计数器应用中，我们简单演示了如何创建一个 Model。本节我们将详细介绍 Model 的创建方法。
-
-通过 `model` API 创建 Model，例如，`model('foo')` 表示要创建一个名为 `foo` 的 Model，通过调用 `model('foo')` 返回的 `define` 函数，定义 Model 包含的 State、Actions 等：
-
-```js
-import { model, useModel } from '@modern-js/runtime/model';
-
-const fooModel = model('foo').define({
-  state: {
-    value: 'foo',
-  },
-  actions: {
-    setValue: (state, payload){
-      state.value = payload
-    }
-  }
-});
-```
-
-:::info
-
-- Model 中的 Action 中不能包含有副作用的逻辑，如请求 HTTP 接口，访问 localStorage 等。
-- `setValue` 内部直接修改了入参 State，看起来是违反了纯函数的定义，实际上 Reduck 内部使用 [immer](https://github.com/immerjs/immer) 来修改不可变对象，保证了这种写法不会影响对象的不可变性，所以 `setValue` 仍然是一个纯函数。当然，你也可以直接在 Action 中返回一个新对象，不过这样的写法会更加复杂一些。
-
-:::
-
-`define` 接收的参数，只是对 Model 原始结构的描述：内部定义的 State、Actions 等。`define` 返回值 `fooModel` 才是真正创建得到的 Model 对象。例如，虽然 `setValue`，有 2 个参数，但是当真正调用 `setValue` 这个 Action 时，我们只需要传入 `payload` 一个参数，因为我们调用的是 `fooModel` 上的 Action 方法，而不是 Model 原始结构上描述的 Action 方法。详细参考[使用 Model](/guides/topic-detail/model/use-model)。
-
-`define` 除了接收对象类型的参数，还可以接收函数类型的参数。例如：
-
-```js
-import { model, useModel } from '@modern-js/runtime/model';
-
-const fooModel = model('foo').define((context, utils) => {
-  return {
-    state: {
-      value: 'foo',
-    },
-    actions: {
-      setValue: (state, payload){
-        state.value = payload
-      }
-    }
-  }
-});
-```
-
-通过函数定义 Model 时，函数内部会自动传入 `context`、`utils` 2 个参数，`context` 是 Reduck 的上下文对象，可以获取到 `store` 对象，`utils` 提供了一组工具函数，方便实现 Model 通信等复杂功能需求。
-
-Model 支持复制。例如：
-
-```ts
-const barModel = fooModel('bar');
-```
-
-barModel 是基于 fooModel 创建出一个的新的 Model 对象，类比面向对象编程语言中的概念，barModel 和 fooModel 是基于同一个类（Class）创建出的 2 个实例对象。当两个模块的状态管理逻辑相同，例如一个页面中的两个 tab 模块，使用的数据的结构和逻辑相同，区别只是从不同的接口获取数据，那么可以通过 Model 复制的方式，创建 2 个不同的 Model 对象。
-
-:::info 补充信息
-本节涉及的 API 的详细定义，请参考[这里](/apis/app/runtime/model/model_)。
-
-:::