@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/zh/apis/app/runtime/model/model_.mdx

@@ -0,0 +1,199 @@
+---
+sidebar_position: 1
+title: model
+---
+# model
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+:::tip 提示
+Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**model**](https://github.com/modern-js-dev/reduck/blob/main/packages/store/src/model/model.ts)。
+
+:::
+
+## model
+
+用于创建管理应用状态的 Model。
+
+`function model(name: string): { define: function }`
+
+- name：`string`，创建的 Model 的唯一标识。
+
+```ts title="示例"
+model('foo');
+```
+
+## define
+
+用于定义 Model 的详细结构，支持传入一个对象类型或函数类型的参数。
+
+### 对象类型
+
+`function define(modelDesc: ModelDesc): Model;`
+
+- modelDesc: `ModelDesc`，对 Model 结构的定义，包含 `state`、`computed`、`actions`、`effects` 等属性。
+
+```tsx title="示例"
+const fooModel = model('foo').define({
+  state: 'foo',
+  computed: {
+    cFoo: state => `c${state}`,
+  },
+  actions: {
+    setState: (state, value) => {
+      return value;
+    },
+  },
+  effects: {
+    loadState: async () => {
+      // 从服务端获取 state
+    },
+  },
+});
+```
+
+### 函数类型
+
+`function define((context: Context, utils: Utils) => ModelDesc): Model;`
+
+- context: Context，Reduck 上下文对象，可以获取底层的 `store` 对象。`store` 除支持 Redux Store 的所有 [API](https://redux.js.org/api/store) 以外，还挂载了用于消费 Model 的 `use` 的方法，和用于卸载 Model 的 `unmount` 方法。
+- utils: Utils，定义 Model 时，常用的工具函数：`use`、`onMount`。`use` 作用同 `store` 对象上的 `use`，`onMount` 是 Model 挂载后的钩子函数。
+
+{/* TODO: @anchao 调整类型  */}
+```ts
+interface Utils {
+  use: UseModel;
+  onMount: OnMountHook;
+}
+
+interface Context {
+  store: ReduxStore & {
+    use: UseModel;
+    unmount: (model: Model) => void;
+  };
+}
+```
+
+如通过 `use`，可以获取 Model 自身及其它 Model 的 `state`，`actions`。
+
+```tsx title="示例"
+const fooModel = model('foo').define(() => {
+  return {
+    state: 'foo',
+    actions: {
+      setState: (state, value) => {
+        return value;
+      },
+    },
+  };
+});
+
+const barModel = model('bar').define((_, { use }) => {
+  return {
+    state: 'bar',
+    effects: {
+      syncFoo() {
+        const [state, actions] = use(fooModel);
+        actions.setState(state);
+      },
+    },
+  };
+});
+```
+
+### 参数
+
+#### ModelDesc.state
+
+定义 Model 的状态。技术上，支持任意类型的 **State**，但是实践中建议使用可进行 JSON 序列化的类型。
+
+```ts
+interface ModelDesc {
+  state: any;
+}
+```
+
+#### ModelDesc.actions
+
+定义 Model 的 Actions。Actions 的函数类型为：
+
+```ts
+interface ModelDesc {
+  actions: {
+    [actionKey: string]: (state: State, payload: any) => State | void;
+  };
+}
+```
+
+Reduck 内部集成了 [immer](https://github.com/immerjs/immer)，可以直接原始的 `state`，当 Action 没有显式返回值时，Reduck 内部会返回修改过的新的 State 对象。
+
+#### ModelDesc.computed
+
+定义 Model 的衍生状态。衍生状态的定义支持两种类型：
+
+1. 只依赖 Model 自身的状态
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: (state: State) => any;
+  };
+}
+```
+
+2. 依赖其他 Model 的状态
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: [
+      ...models: Model[],
+      (state: State, ...args: ModelState[]) => any,
+    ];
+  };
+}
+```
+
+```ts title="示例"
+const fooModel = model('foo').define({
+  state: 'foo',
+});
+
+const barModel = model('bar').define({
+  state: 'bar',
+  computed: {
+    combineFoo: [fooModel, (state, fooState) => state + fooState],
+  },
+});
+```
+
+#### ModelDesc.effects
+
+定义 Model 的 Effects。Effects 中定义的函数类型为：
+
+```ts
+interface ModelDesc {
+  effects: {
+    [effectKey: string]: (...args: any[]) => any;
+  };
+}
+```
+
+```ts title="示例"
+const fooModel = model('foo').define((context, { use }) => ({
+  state: 'foo',
+  effects: {
+    persist() {
+      const [state] = use(fooModel);
+      localStorage.setItem('state', state);
+    },
+  },
+}));
+```
+
+:::info 更多参考
+[创建 Model](/guides/topic-detail/model/define-model)
+
+:::

package/zh/apis/app/runtime/model/use-local-model.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_position: 4
+title: useLocalModel
+---
+# useLocalModel
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+用于把 Model 中的 State 作为局部状态使用，效果类似 React 的 `useState`。`useLocalModel` API 形式上与 `useModel` 完全一致。具体使用请参考 [`useModel`](./use-model.md)。
+
+#### 示例
+
+```tsx
+function Container() {
+  const [state, actions] = useLocalModel(modelA);
+  const [state1, actions1] = useLocalModel(modelA);
+
+  // ...
+}
+```
+
+上面通过 `useLocalModel` 加载了两次 `modelA`，因为 `useLocalModel` 消费的是局部状态，所以 `state` 和 `state1` 也是完全隔离的。
+
+:::info 更多参考
+[使用 Model](/guides/topic-detail/model/use-model)
+
+:::

package/zh/apis/app/runtime/model/use-model.mdx

@@ -0,0 +1,89 @@
+---
+sidebar_position: 2
+title: useModel
+---
+# useModel
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+:::tip 提示
+Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [model](https://github.com/modern-js-dev/reduck/blob/main/packages/store/src/model/useModel.ts)。
+
+:::
+
+## 函数签名
+
+```ts
+function useModel(
+  models: Models[],
+  stateSelector?: StateSelector,
+  actionSelector?: ActionSelector,
+): [state, actions, subscribe];
+function useModel(
+  ...models: Models[],
+  stateSelector?: (...args: State[]) => any,
+  actionSelector?: (...args: Actions[]) => any,
+): [state, actions, subscribe];
+```
+
+### 参数
+
+- models：Model 对象数组，可以作为一个数组类型的参数传入，也可以所有 Model 逐个作为参数传入。
+- stateSelector：可选参数，用于筛选 State 计算。前 n 个参数为 n 个 Model 对应的 State，返回的数据作为 `useModel` 返回值数组的第一个元素。
+- actionSelector：可选参数，用于筛选 Actions 计算。前 n 个参数为 n 个 Model 对应的 Actions，返回的数据作为 `useModel` 返回值数组的第二个元素。
+
+### 返回值
+
+返回一个数组，每一项元素分别为：
+
+- state：`stateSelector` 的返回值。如果未传 `stateSelector`，会把传入的所有 Model 的 State (包含衍生状态)合并后返回。如果不同 Model 的 State 中存在同名属性，后面的 State 会覆盖前面的 State。当 `state` 发生变化时，调用 `useModel` 的组件会重新渲染。
+- actions：第二个元素为 `actionSelector` 的返回值。如果未传 `actionSelector`，会把传入的所有 Model 的 Actions (包含 Effects) 合并后返回。如果不同 Model 的 Actions 中存在同名属性，后面的 Actions 会覆盖前面的 Actions。
+- subscribe：订阅 State 变化的函数。当传入的任意 Model 的 State 发生改变时，该函数会被调用。
+
+## 示例
+
+### 基本用法
+
+```tsx
+import todoModel from 'models/todo';
+import filterModel from 'models/filter';
+
+function Test(props) {
+  const [state, actions] = useModel([todoModel, filterModel]);
+  actions.add(); // 调用 todoModel add action
+  actions.setVisibleStatus(); // 调用 filterModel filterModel action
+
+  state.items; // 获取 todoModel state items
+  state.visibleStatus; // 获取 filterModel state visibleStatus
+}
+```
+
+### selector 用法
+
+```js
+function Test(props) {
+  const [state, actions] = useModel(
+    [todoModel, filterModel],
+    (todoState, filterState) => ({
+      items: todoState.items,
+      visibleStatus: `${props.prefix}-${filterState.visibleStatus}`,
+    }),
+    (todoActions, filterActions) => ({
+      ...todoActions,
+      ...filterActions,
+    }),
+  );
+  actions.add(); // 调用 todoModel add action
+  actions.setVisibleStatus(); // 调用 filterModel filterModel action
+
+  state.items; // 获取 todoModel state items
+  state.visibleStatus; // 获取 filterModel state visibleStatus
+}
+```
+
+:::info 更多参考
+[使用 Model](/guides/topic-detail/model/use-model)
+
+:::

package/zh/apis/app/runtime/model/use-static-model.mdx

@@ -0,0 +1,49 @@
+---
+sidebar_position: 3
+title: useStaticModel
+---
+# useStaticModel
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+如果想在组件里以 React Hook 的形式消费某个 Model，并能随时获取到当前最新的状态，但又不希望 Model 状态更新的时候，引起组件的重新渲染，可以使用 `useStaticModel`。`useStaticModel` API 形式上与 `useModel` 完全一致。具体使用请参考 [`useModel`](./use-model.md)。
+
+为了保证总是能获取到最新状态，注意不要对返回的 `state` 解构。
+
+```tsx
+function App() {
+  // ❌ 不能解构 state，但可以解构 actions。
+  const [{ username }, { logout }] = useStaticModel(userModel);
+
+  // ✅ 这才是正确使用姿势。
+  const [state, { logout }] = useStaticModel(userModel);
+
+  useEffect(() => {
+    state.username;
+  }, []);
+}
+```
+
+#### 示例
+
+如下 `App` 组件消费了 `userModel` 的状态，但没有直接在 JSX 里使用。可以发现，`userModel` 状态的改变没有必要引起组件重新渲染，这种情况可以使用 `useStaticModel` 进行优化。
+
+```tsx
+function App() {
+  const [state] = useStaticModel(userModel);
+
+  useEffect(() => {
+    // 统计 UV 数据
+    send('pageview', { user: state.user });
+  }, [state]);
+
+  return <div>Hello</div>;
+}
+```
+
+:::info 更多参考
+[使用 Model](/guides/topic-detail/model/use-model)
+
+:::

package/zh/apis/app/runtime/model/use-store.mdx

@@ -0,0 +1,26 @@
+---
+sidebar_position: 9
+title: useStore
+---
+# useStore
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+`useStore` 用于获取当前组件树共享的 Store。常用于在组件外访问 Model 的场景。注意，`useStore` 是一个 React Hook，只能在组件内使用。
+
+## 函数签名
+
+```ts
+function useStore(): ReduckStore;
+```
+
+### 返回值
+
+- ReduckStore：Reduck Store，类型参考 [createStore](./create-store.md) 返回值。
+
+:::info 更多参考
+[使用 Model](/guides/topic-detail/model/use-model#在组件外使用)
+
+:::

package/zh/apis/app/runtime/router/router.mdx

@@ -0,0 +1,262 @@
+---
+title: router
+sidebar_position: 1
+---
+# router
+
+:::info 补充信息
+基于 [react-router](https://reactrouter.com/) 的路由解决方案。
+
+:::
+
+## hooks
+
+### useNavigate
+
+```ts
+declare function useNavigate(): NavigateFunction;
+
+interface NavigateFunction {
+  (
+    to: To,
+    options?: {
+      replace?: boolean;
+      state?: any;
+      relative?: RelativeRoutingType;
+    },
+  ): void;
+  (delta: number): void;
+}
+```
+
+`useNavigate` 返回一个可以用于执行导航操作的函数。
+
+```tsx
+import { useNavigate } from '@modern-js/runtime/router';
+
+export function HomeButton() {
+  let navigate = useNavigate();
+
+  function handleClick() {
+    navigate('/home');
+  }
+
+  return (
+    <button type="button" onClick={handleClick}>
+      Go home
+    </button>
+  );
+}
+```
+
+### useLocation
+
+```ts
+declare function useLocation(): Location;
+
+interface Location extends Path {
+  state: unknown;
+  key: Key;
+}
+```
+
+`useLocation` 返回当前 url 对应的 [location](https://reactrouter.com/web/api/location) 对象。每当路由更新的时候，都会拿到一个新的 `location` 对象。
+
+```ts
+import { useLocation } from "@modern-js/runtime/router";
+
+function usePageViews() {
+  let location = useLocation();
+  React.useEffect(() => {
+    ga.send(["pageview", location.pathname]);
+  }, [location]);
+}
+
+function App() {
+  usePageViews();
+  return (
+    //...
+  );
+}
+```
+
+### useParams
+
+```ts
+declare function useParams<K extends string = string>(): Readonly<Params<K>>;
+```
+
+`useParams` 返回一个 key/value 的键值对，表示当前匹配的路由 `<Route path>` 中的参数信息。
+
+```tsx
+import { Switch, Route, useParams } from '@modern-js/runtime/router';
+
+function BlogPost() {
+  const { slug } = useParams();
+  return <div>Now showing post {slug}</div>;
+}
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<div>home</div>} />
+      <Route path="/blog/:slug" element={<BlogPost />} />
+    </Routes>
+  );
+}
+```
+
+## 组件
+
+### Link
+
+```ts
+declare function Link(props: LinkProps): React.ReactElement;
+
+interface LinkProps
+  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+  replace?: boolean;
+  state?: any;
+  to: To;
+  reloadDocument?: boolean;
+}
+
+type To = string | Partial<Path>;
+```
+
+可以使用 `Link` 组件进行路由跳转。
+
+```ts
+<Link to="/about">About</Link>
+```
+
+### NavLink
+
+```ts
+declare function NavLink(props: NavLinkProps): React.ReactElement;
+
+interface NavLinkProps
+  extends Omit<LinkProps, 'className' | 'style' | 'children'> {
+  caseSensitive?: boolean;
+  children?:
+    | React.ReactNode
+    | ((props: { isActive: boolean }) => React.ReactNode);
+  className?: string | ((props: { isActive: boolean }) => string | undefined);
+  end?: boolean;
+  style?:
+    | React.CSSProperties
+    | ((props: { isActive: boolean }) => React.CSSProperties);
+}
+```
+
+`<NavLink>` 是一种特殊的 `<Link>`，当 `<NavLink>` 对应的链接和当前 URL 匹配时，会给 `<NavLink>` 所渲染的元素添加“激活”态样式。
+
+### Outlet
+
+```ts
+interface OutletProps {
+  context?: unknown;
+}
+declare function Outlet(props: OutletProps): React.ReactElement | null;
+```
+
+`<Outlet>` 用于嵌套路由场景。在父路由的元素中使用，代表待渲染的子路由的元素在父组件中的位置。
+
+```tsx
+function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      {/* This element will render either <DashboardMessages> when the URL is
+          "/messages", <DashboardTasks> at "/tasks", or null if it is "/"
+      */}
+      <Outlet />
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<Dashboard />}>
+        <Route path="messages" element={<DashboardMessages />} />
+        <Route path="tasks" element={<DashboardTasks />} />
+      </Route>
+    </Routes>
+  );
+}
+```
+
+### Route
+
+```ts
+interface RouteObject {
+  path?: string;
+  index?: boolean;
+  children?: React.ReactNode;
+  caseSensitive?: boolean;
+  id?: string;
+  loader?: LoaderFunction;
+  action?: ActionFunction;
+  element?: React.ReactNode | null;
+  errorElement?: React.ReactNode | null;
+  handle?: RouteObject['handle'];
+  shouldRevalidate?: ShouldRevalidateFunction;
+}
+```
+
+`Route` 用于定义路由。一个 `Route` 对象，将 URL 片段和组件、数据获取关联起来。
+
+`Route` 可以作为普通对象，传给创建 router 的函数的参数：
+
+```ts
+const router = createBrowserRouter([
+  {
+    // it renders this element
+    element: <Team />,
+
+    // when the URL matches this segment
+    path: 'teams/:teamId',
+
+    // with this data loaded before rendering
+    loader: async ({ request, params }) => {
+      return fetch(`/fake/api/teams/${params.teamId}.json`, {
+        signal: request.signal,
+      });
+    },
+
+    // performing this mutation when data is submitted to it
+    action: async ({ request }) => {
+      return updateFakeTeam(await request.formData());
+    },
+
+    // and renders this element in case something went wrong
+    errorElement: <ErrorBoundary />,
+  },
+]);
+```
+
+`Route` 还可以作为组件使用，通过 `createRoutesFromElements` 转换后，再传给创建 router 的函数的参数：
+
+```ts
+const router = createBrowserRouter(
+  createRoutesFromElements(
+    <Route
+      element={<Team />}
+      path="teams/:teamId"
+      loader={async ({ params }) => {
+        return fetch(`/fake/api/teams/${params.teamId}.json`);
+      }}
+      action={async ({ request }) => {
+        return updateFakeTeam(await request.formData());
+      }}
+      errorElement={<ErrorBoundary />}
+    />,
+  ),
+);
+```
+
+## 更多 API
+
+若想要了解完整的路由 API 信息，可至 [react-router 官网](https://reactrouter.com/web/guides/start) 查看。

package/zh/apis/app/runtime/ssr/no-ssr.mdx

@@ -0,0 +1,38 @@
+---
+title: NoSSR
+---
+# NoSSR
+
+被 NoSSR 包裹的内容在服务端不会进行渲染，在客户端 hydrate 阶段也不会渲染，等到整个 App 渲染完成后便会立即渲染。
+
+## 使用姿势
+
+```tsx
+import { NoSSR } from '@modern-js/runtime';
+
+export default () => <NoSSR>...</NoSSR>;
+```
+
+## 示例
+
+下列代码中，`Time` 组件用于展示当前的时间，由于服务端渲染和客户端 hydrate 时获取到的时间是不一致的，React 就会抛出异常。针对这种情况可以使用 `NoSSR` 进行优化：
+
+```tsx
+import { NoSSR } from '@modern-js/runtime';
+
+function Time() {
+  return (
+    <NoSSR>
+      <div>Time: {Date.now()}</div>
+    </NoSSR>
+  );
+}
+```
+
+## 使用场景
+
+在 CSR 中，常常需要根据当前浏览器 UA，或是当前页面 URL 的某个参数的不同，来渲染不同的内容。如果此时应用直接切换到 SSR，很有可能出现不符合预期的结果。
+
+Modern.js 在 SSR 上下文中提供了完整的浏览器端信息，可以利用上下文信息来决定组件在服务端的渲染结果。
+
+即便如此，如果应用里有太多的判断，开发者希望以后再使用上下文，或者不希望某些内容在服务端被渲染，可以使用 NoSSR 组件将这一部分剔除在服务端渲染外。