@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

package/docs/zh/apis/app/runtime/core/use-loader.mdx

@@ -1,89 +0,0 @@
----
-title: useLoader
----
-# useLoader
-
-一个同构的 API，通常会用来做异步请求。当 SSR 的时候，服务端使用 `useLoader` 预加载数据，同时浏览器端也会复用这部分数据。
-
-:::tip
-在使用 Rspack 作为打包工具时，暂不支持使用 useLoader API。
-:::
-
-## 使用姿势
-
-```ts
-import { useLoader } from '@modern-js/runtime';
-```
-
-## 函数签名
-
-```ts
-type LoaderFn = (context: runtimeContext) => Promise<unknow>;
-type Options = {
-  onSuccess: (data: Record<string, any>) => void;
-  onError: (error: Error) => void;
-  initialData: Record<string, any>;
-  skip: boolean;
-  params: Record<string, any>;
-  static: boolean;
-};
-type ReturnData = {
-  data: Record<string, any>;
-  loading: boolean;
-  error: Error;
-  reload: (params?: Record<string, any>) => Promise<any> | undefined;
-  reloading: boolean;
-};
-
-function useLoader(loaderFn: LoaderFn, options: Options): ReturnData;
-```
-
-:::info
-`runtimeContext` 类型可以参考 [useRuntimeContext](/apis/app/runtime/core/use-runtime-context)。
-
-:::
-
-### 参数
-
-- `loaderFn`：用于加载数据的函数，返回 Promise。
-- `options`：可选配置项。
-  - `onSuccess`：执行成功的回调。
-  - `onError`：执行失败的回调。
-  - `initialData`：首次执行前的初始数据，对应返回值中的 `data` 字段。
-  - `skip`：当值为 `true` 时，函数不执行。
-  - `params`：当 `params` 序列化结果发生改变时，函数会重新执行。同时，`params` 也会作为函数的第二个参数被传入。
-  - `static`：当值为 `true` 时，`useLoader` 用于 [SSG](/guides/basic-features/render/ssg) 编译阶段数据的获取。
-
-### 返回值
-
-- `data`：执行成功时的返回数据。
-- `loading`：表示函数是否处于执行过程中。
-- `error`：函数执行失败时的错误信息。
-- `reload`：调用后可以重新执行函数。
-  - `params`：当值为 `undefined` 时，函数执行时将复用上次的值；否则会使用新的值重新执行函数。
-- `reloading`：调用 `reload` 的执行过程中，`reloading` 值为 `true`。
-
-## 示例
-
-```ts
-function Container() {
-  const { data, error, loading } = useLoader(
-    async (context, params) => {
-      console.log(params) // nicole
-      return fetch(user);
-    },
-    {
-      onSuccess: data => {
-        console.log('I did success:(',  data);
-      },
-      onError: error => {
-        console.log('I met error:)',  error);
-      },
-      initialData: { name: 'nicole', gender: 'female' },
-      params: 'nicole'
-    }
-  );
-
-  return ...;
-}
-```

package/docs/zh/apis/app/runtime/core/use-module-apps.mdx

@@ -1,179 +0,0 @@
----
-title: useModuleApps
----
-# useModuleApps
-
-返回所有微前端子应用的 React 组件，用于可自由控制路由。
-
-## 使用姿势
-
-```tsx
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-```
-
-## 函数签名
-
-`function useModuleApps(): Record<string, React.FC<any>>`
-
-分别返回包裹每个子应用后的 React 组件。
-
-## 示例
-
-需要先配置微前端子应用信息。
-
-import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
-
-<EnableMicroFrontend />
-
-这里演示主应用为自控式路由的场景，全部场景参考 [体验微前端](/guides/topic-detail/micro-frontend/c02-development.html)
-```tsx title=App.tsx
-function App() {
-  const { apps, MApp, Table, Dashboard } = useModuleApps();
-
-  // 使用的不是 MApp 组件，需要使用 createBrowserRouter 来创建路由
-  const router = createBrowserRouter(
-    createRoutesFromElements(
-      <Route path="/" element={<AppLayout />}>
-        <Route key={'table'} path={'table/*'} element={<Table />} />
-        <Route key={'dashboard'} path={'dashboard/*'} element={<Dashboard />} />
-      </Route>
-    )
-  );
-
-  return (
-    // 方法一：使用 MApp 自动根据配置的 activeWhen 参数加载子应用(本项目配置在 modern.config.ts 中)
-    // <BrowserRouter>
-    //   <MApp />
-    // </BrowserRouter>
-
-    // 方法二：手动写 Route 组件方式加载子应用，方便于需要鉴权等需要前置操作的场景
-    <>
-      <RouterProvider router={router} />
-    </>
-  );
-}
-
-defineConfig(App, {
-  masterApp: {
-    apps: [
-      {
-        // name 区分大小写，name 提供的是什么 useModuleApps 返回的就是什么
-        name: 'Table',
-        entry: 'http://127.0.0.1:8081/',
-      },
-      {
-        name: 'Dashboard',
-        entry: 'http://localhost:8082',
-      },
-    ],
-  },
-});
-```
-
-通过 `useModuleApps()` 获取到 `Table` 和 `Dashboard` 子应用组件（名称和配置里的 `name` 字段对应），之后就可以像使用普通的 React 组件一样去加载子应用。
-
-### 集中式路由
-
-**集中式路由** 是将子应用的激活路由集中配置的方式。我们给子应用列表信息添加 `activeWhen` 字段来启用 **集中式路由**。
-
-import MicroRuntimeConfig from "@site-docs/components/micro-runtime-config";
-
-<MicroRuntimeConfig />
-
-然后在主应用中使用 `useModuleApp` 方法获取 `MApp` 组件, 并在主应用渲染 `MApp`。
-
-```tsx title=主应用：App.tsx
-import { useModuleApp } from '@modern-js/plugin-runtime';
-
-function App() {
-  const { MApp } = useModuleApps();
-
-  return (
-    <div>
-      <MApp />
-    </div>
-  );
-}
-
-defineConfig(App, {
-  masterApp: {
-    apps: [
-      {
-        // name 区分大小写，name 提供的是什么 useModuleApps 返回的就是什么
-        name: 'Table',
-        activeWhen: '/table',
-        entry: 'http://127.0.0.1:8081/',
-      },
-      {
-        name: 'Dashboard',
-        activeWhen: '/dashboard',
-        entry: 'http://localhost:8082',
-      },
-    ],
-  },
-});
-```
-
-这样启动应用后，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用，访问 `/table` 路由，会渲染 `Table` 子应用。
-
-## 加载动画
-
-可以通过以下方式，自定义组件加载过程的过渡动画。
-
-```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 } = 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 (
-    <>
-      <RouterProvider router={router} />
-    </>
-  );
-};
-```

package/docs/zh/apis/app/runtime/core/use-runtime-context.mdx

@@ -1,116 +0,0 @@
-# useRuntimeContext
-
-该函数主要用于获取 Runtime 上下文，只能在函数组件中使用。
-
-## 使用姿势
-
-```tsx
-import { useRuntimeContext } from '@modern-js/runtime';
-
-export function App() {
-  const runtimeContext = useRuntimeContext();
-  return <div>Hello World</div>
-}
-```
-
-## 函数签名
-
-```ts
-type RuntimeContext = {
-  context: RequestContext;
-};
-```
-
-### context
-
-用于获取[请求上下文](#请求上下文)。
-
-## 使用示例
-
-### 区分运行环境
-
-```ts
-function App() {
-  const { context } = useRuntimeContext();
-
-  if (context.isBrowser === true) {
-    // 浏览器端执行逻辑
-    console.log('browser render')
-  } else {
-    // 服务器端执行逻辑 logger 功能需开启
-    context.logger.info('server render')
-  }
-}
-```
-
-### 请求上下文
-
-开启 SSR 时，在 Node 环境和浏览器端环境可以获取到同构的请求上下文。
-
-稍有不同的是 Node 环境还支持设置响应头、响应码，并提供了 Logger 日志与 Metrics 打点。
-
-:::tip
-当 SSR 未开启时，仅包含可在浏览器端获取的部分信息。
-
-:::
-
-import { Tabs, Tab as TabItem } from "@theme";
-
-<Tabs
-  defaultValue="RequestContext"
-  values={[
-    { label: 'RequestContext', value: 'RequestContext', },
-    { label: 'ServerContext', value: 'ServerContext', },
-    { label: 'ClientContext', value: 'ClientContext', },
-  ]
-}>
-<TabItem value="RequestContext">
-
-```ts
-type RequestContext = ServerContext | ClientContext;
-```
-
-</TabItem>
-<TabItem value="ServerContext">
-
-```ts
-interface ServerContext {
-  isBrowser: false;
-  request: {
-    userAgent: string;
-    cookie: string;
-    cookieMap: Record<string, any>;
-    query: Record<string, any>;
-    url: string;
-    host: string;
-    headers?: IncomingHttpHeaders;
-  };
-  response: {
-    setHeader: (key: string, value: string) => void;
-    status: (code: number) => void;
-  };
-  logger: Logger;
-  metrics: Metrics;
-}
-```
-
-</TabItem>
-<TabItem value="ClientContext">
-
-```ts
-interface ClientContext {
-  isBrowser: true;
-  request: {
-    userAgent: string;
-    cookie: string;
-    cookieMap: Record<string, any>;
-    query: Record<string, any>;
-    url: string;
-    host: string;
-    headers?: IncomingHttpHeaders;
-  };
-}
-```
-
-</TabItem>
-</Tabs>

package/docs/zh/apis/app/runtime/model/Provider.mdx

@@ -1,36 +0,0 @@
----
-sidebar_position: 8
-title: Provider
----
-# Provider
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-`Provider` 是一个组件，它将 Reduck 的 Store 注入到应用的组件树中，使组件树内部的组件可以访问 Model。一般情况下，`Provider` 会定义在组件树的最顶层。
-
-## 函数签名
-
-```ts
-interface ProviderProps {
-  store?: ReduckStore;
-  config?: AppConfig;
-}
-```
-
-### 参数
-
-- store：[`createStore`](./create-store.mdx) 创建的 Store 对象。
-- config：创建 Reduck Store 的配置，同 [`createApp`](./create-app.mdx) 的 `config` 参数。
-
-## 示例
-
-```tsx title="应用入口文件"
-ReactDOM.render(
-  <Provider>
-    <App />
-  </Provider>,
-  document.getElementById('root'),
-);
-```

package/docs/zh/apis/app/runtime/model/auto-actions.mdx

@@ -1,122 +0,0 @@
----
-sidebar_position: 6
-title: Auto actions
----
-# Auto actions
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-Reduck 可以根据 State 的类型，自动生成相应的 Actions，为修改 State 提供便利。
-
-:::tip 提示
-可通过 [`runtime.state.autoActions`](/configure/app/runtime/state#autoactions) 关闭 auto actions 功能。
-
-:::
-
-## 示例
-
-### 基础数据类型
-
-State 类型为 `string`、`number`、`boolean`、`null` 时，生成 `setState` Action。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: 1,
-});
-
-function App() {
-  const [state, actions] = useModel(fooModel);
-
-  return (
-    <div>
-      <div>State: {state}</div>
-      <button
-        type="button"
-        onClick={() => {
-          // 调用自动生成的 setState Action
-          actions.setState(state + 1);
-        }}
-      >
-        add
-      </button>
-    </div>
-  );
-}
-```
-
-### 数组 Array
-
-State 类型为 Array 时，生成下列 Actions：
-
-- `push`：将一个或多个元素添加到数组的末尾。
-- `pop`：从数组中删除最后一个元素。
-- `shift`：从数组中删除第一个元素。
-- `unshift`：将一个或多个元素添加到数组的开头。
-  - 语法：`arr.unshift(element1, ..., elementN)`
-  - `elementN`：要添加到数组开头的元素或多个元素。
-- `filter`：过滤元素。
-{/* 语义与原生方法不同，待修改 API  */}
-- `concat`：拼接数组。
-{/* 语义与原生方法不同，待修改 API  */}
-- `splice`：通过删除或替换现有元素或者原地添加新的元素来修改数组，并以数组形式返回修改后的数组（注意和原生 `splice` 返回值不同）。
-  - 语法：`splice(start[, deleteCount[, item1[, item2[, ...]]]])`
-  - `start`：指定修改的开始位置（从 0 计数）。
-  - `deleteCount`：可选，整数，表示要移除的数组元素的个数。
-  - `item, item2, ...`：可选，要添加进数组的元素，从 start 位置开始。如果不指定，则 `splice` 将只删除数组元素。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: [1, 2, 3],
-});
-
-function App() {
-  const [state, actions] = useModel(fooModel);
-
-  useEffect(() => {
-    actions.push(4);
-    actions.pop();
-    actions.shift(0);
-    actions.unshift();
-    actions.filter(val => val <= 2);
-    actions.splice(0, 1, 1, 2);
-  }, []);
-
-  return (
-    <div>
-      <div>State: {state}</div>
-    </div>
-  );
-}
-```
-
-### 简单对象 PlainObject
-
-State 类型为 PlainObject 时，根据 State 包含的属性名，生成 `set${key}`（小驼峰命名）Actions。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: {
-    a: 1,
-    b: { value: 1 },
-    c: 'c',
-  },
-});
-
-function App() {
-  const [state, actions] = useModel(fooModel);
-
-  useEffect(() => {
-    actions.setA(2);
-    actions.setB({ value: 2 });
-    actions.setC('d');
-  }, []);
-
-  return (
-    <div>
-      <div>State: {state}</div>
-    </div>
-  );
-}
-```

package/docs/zh/apis/app/runtime/model/connect.mdx

@@ -1,143 +0,0 @@
----
-sidebar_position: 5
-title: connect
----
-# connect
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-:::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**connect**](https://github.com/web-infra-dev/reduck/blob/main/packages/react/src/connect.ts)。
-
-:::
-
-`connect` 功能上同 `useModel` 一致，是对应的 HOC 风格的 API。建议优先使用 Hook 风格的 `useModel`。
-
-## 类型
-
-```ts
-type SelectStateToProps = (
-  ...modelStates: State[],
-  ownProps?: any,
-) => PlainObject;
-type SelectActionsToProps = (
-  ...modelActions: Actions[],
-  ownProps?: any,
-) => PlainObject;
-
-function connect(models: Model, options?: ConnectOptions);
-function connect(
-  models: [...Model[], SelectStateToProps?, SelectActionsToProps?],
-  options?: ConnectOptions,
-);
-```
-
-## 参数
-
-- `models`：传入的 1 个或多个 Model，当 `models` 为数组类型参数时，最后两项元素可以是用于筛选 State 的函数（ `SelectStateToProps` 类型）和用于筛选 Actions 的函数（ `SelectActionsToProps` 类型）。
-  - `SelectStateToProps`： `modelStates` 是传入的 Model 对象的 State 组成的数组，`ownProps` 是当前组件接收外部传递的 `props`，`SelectStateToProps` 返回的数据会传递到组件的 `props` 上。当 `models` 中没有传入 `SelectStateToProps` 参数时，所有 Model 的 State 进行合并后传递到组件的 `props` 上。
-  - `SelectActionsToProps`： `modelActions` 是传入的 Model 对象的 Actions 组成的数组，`ownProps` 是当前组件接收外部传递的 `props`，`SelectActionsToProps` 返回的数据也会传递到组件的 `props` 上。当 `models` 中没有传入 `SelectActionsToProps` 参数时，所有 Model 的 Actions 进行合并后传递到组件的 `props` 上。
-
-- `options`：可选参数，用于辅助配置。目前支持设置 `forwardRef`，用于控制是否转发组件的 `ref`，默认值为 `false`，表示不转发 `ref`。设置为 `{forwardRef: true}`，表示转发 `ref`。
-
-## 返回值
-
-返回一个高阶组件：接收一个传入的组件，返回一个在 `props` 上注入了额外 State 和 Actions 的组件。
-
-## 示例
-
-### 简单用法
-
-```ts
-const modelA = model('modelA').define({
-  state: {
-    a: 1,
-  },
-  actions: {
-    incA(state) {
-      return {
-        ...state,
-        a: state.a + 1,
-      };
-    },
-  },
-});
-
-const modelB = model('modelB').define({
-  state: {
-    b: 10,
-  },
-  actions: {
-    incB(state) {
-      return {
-        ...state,
-        b: state.b + 1,
-      };
-    },
-  },
-});
-
-function Test(props) {
-  props.incA(); // 调用 modelA 的 action
-  props.incB(); // 调用 modelB 的 action
-
-  props.a; // 获取 modelA 的 state: a
-  props.b; // 获取 modelB 的 state: b
-}
-
-export default connect([modelA, modelB])(Test);
-```
-
-### 筛选 State 和 Actions
-
-```ts
-function Test(props) {
-  props.incAll();
-  props.c;
-}
-
-const stateSelector = (stateA, stateB) => ({
-  ...stateA,
-  ...stateB,
-  c: stateA.a + stateA.b,
-});
-const actionsSelector = (actionsA, actionsB) => ({
-  ...actionsA,
-  ...actionsB,
-  incAll: () => {
-    actionsA.incA();
-    actionsB.incB();
-  },
-});
-
-export default connect([modelA, modelB, stateSelector, actionsSelector])(Test);
-```
-
-### 转发组件的 ref
-
-```ts
-import { useRef, forwardRef } from 'react';
-
-function Test(props, ref) {
-  const { a, b } = props;
-
-  return (
-    <div ref={ref}>
-      <span>{a}</span>
-      <span>{b}</span>
-    </div>
-  );
-}
-
-const TestWrapper = connect([modelA, modelB], { forwardRef: true })(
-  forwardRef(Test),
-);
-
-function App() {
-  const testRef = useRef();
-
-  return <TestWrapper ref={testRef} />;
-}
-```