@modern-js/main-doc 2.1.0 → 2.2.0

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 组件将这一部分剔除在服务端渲染外。

package/zh/apis/app/runtime/ssr/pre-render.mdx

@@ -0,0 +1,96 @@
+---
+title: PreRender
+---
+# PreRender
+
+无展示内容的高阶组件，通过类似 Helmet 的方式实现 SPA 路由级的缓存，无需额外配置。
+
+## 使用姿势
+
+```tsx
+import { PreRender } from '@modern-js/runtime/ssr';
+
+export default () => (
+  <>
+    <PreRender interval={5} />
+  </>
+);
+```
+
+## 函数签名
+
+`PreRender` 组件提供了一套常用的配置参数，用于控制缓存的规则、过期时间、缓存算法等。
+
+```tsx
+type Props {
+  interval: number;
+  staleLimit: number;
+  level: number;
+  include: { header?: string[], query?: string[] };
+  matches: { header?: Record<string, any>, query?: Record<string, any> }
+}
+
+function PreRender(props: Props): React.Component
+```
+
+### 参数
+
+- `interval`：设置缓存保持新鲜的时间，单位秒。在该时间内，将直接使用缓存，并且不做异步渲染。
+- `staleLimit`：设置缓存完全过期的时间，单位秒。在该时间内，缓存可以被返回，并且会做一步渲染，否则必须使用重新渲染的结果。
+- `level`：设置缓存标识的计算规则等级，通常配合 `includes` 与 `matches` 使用。默认值为 `0`。
+
+```bash
+0：路由路径
+1：路由路径 + 查询字符串
+2：路由路径 + 请求头
+3：路由路径 + 查询字符串 + 请求头
+```
+
+- `includes`：设置需要被纳入缓存标识的内容，在 level 非 0 时使用。默认值为 `null`。
+- `matches`：设置 query 或 header 的值在缓存标识计算中的重写规则，通常用在缓存分类时，支持正则表达式。默认值为 `null`。
+
+## 示例
+
+```tsx
+import { PreRender } from '@modern-js/runtime/ssr';
+
+export default function App() {
+  return (
+    <>
+      <PreRender interval={10} />
+      <div>Hello Modern</div>
+    </>
+  );
+}
+```
+
+下面例子展示了如何将 query、header 中指定的参数纳入缓存计算中：
+
+```tsx
+/* 使用 query 中的 channel 和 header 中的 language 计算缓存标识 */
+<PreRender
+  interval={10}
+  level={2}
+  includes={{
+    query: ['channel'],
+    header: ['language'],
+  }}
+/>
+```
+
+下面例子展示了如何不让测试频道影响线上缓存：
+
+```tsx
+/* 将 query 中 channel 值为 test_ 开头的重写为 testChannel，否则重写为 otherChannel */
+<PreRender interval={10} level={2} includes={{
+  query: ["channel"],
+  header: ["language"]
+}} matches={{
+  query: {
+    channel: {
+      "testChannel", "^test_",
+      "otherChannel", ".*"
+    }
+  }
+}} />
+```

package/zh/apis/app/runtime/testing/act.mdx

@@ -0,0 +1,35 @@
+---
+title: act
+---
+# act
+
+用于确保渲染、事件、数据获取等行为已经应用在 DOM 上。
+
+## 使用姿势
+
+```ts
+import { act } from '@modern-js/runtime/testing';
+```
+
+## 函数签名
+
+`act` 和 [react-dom/test-utils act 函数](https://reactjs.org/docs/testing-recipes.html#act) 是一致的。
+
+## 示例
+
+```tsx
+import ReactDOM from 'react-dom';
+import { act } from '@modern-js/runtime/testing';
+import { Foo } from '@/components/Foo';
+
+describe('test act', () => {
+  it('it should be foo', () => {
+    const el = document.createElement('div');
+    act(() => {
+      ReactDOM.render(<Foo />, el);
+    });
+
+    expect(el.innerHTML).toBe('<div>Foo</div>');
+  });
+});
+```

package/zh/apis/app/runtime/testing/cleanup.mdx

@@ -0,0 +1,40 @@
+---
+title: cleanup
+sidebar_position: 3
+---
+# cleanup
+
+用于卸载掉当前已渲染的所有组件。
+
+## 使用姿势
+
+```ts
+import { cleanup } from '@modenr-js/runtime/testing';
+```
+
+## 函数签名
+
+`function cleanup(): void`
+
+## 示例
+
+:::info 注
+请注意，如果你使用的测试框架支持 afterEach，并且它被注入到你的测试环境中（如 mocha、Jest 和 Jasmine），**会默认在 afterEach 钩子里执行 `cleanup`**。否则，你将需要在每次测试后进行手动清理。
+
+:::
+
+例如，如果你使用[ava](https://github.com/avajs/ava)测试框架，那么你需要像这样使用 test.afterEach 钩子。
+
+```tsx
+import { cleanup, render } from '@modern-js/runtime/testing';
+import test from 'ava';
+
+test.afterEach(cleanup);
+
+test('renders into document', () => {
+  render(<div />);
+  // ...
+});
+
+// ... more tests ...
+```