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

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

@@ -1,201 +0,0 @@
----
-sidebar_position: 1
-title: model
----
-
-# model
-
-import ReduckTip from '@site-docs/components/reduck-tip';
-
-<ReduckTip />
-
-:::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**model**](https://github.com/web-infra-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/docs/zh/apis/app/runtime/model/use-local-model.mdx

@@ -1,29 +0,0 @@
----
-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.mdx)。
-
-#### 示例
-
-```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/docs/zh/apis/app/runtime/model/use-model.mdx

@@ -1,89 +0,0 @@
----
-sidebar_position: 2
-title: useModel
----
-# useModel
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-:::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [model](https://github.com/web-infra-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/docs/zh/apis/app/runtime/model/use-static-model.mdx

@@ -1,49 +0,0 @@
----
-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.mdx)。
-
-为了保证总是能获取到最新状态，注意不要对返回的 `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/docs/zh/apis/app/runtime/model/use-store.mdx

@@ -1,26 +0,0 @@
----
-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.mdx) 返回值。
-
-:::info 更多参考
-[使用 Model](/guides/topic-detail/model/use-model#在组件外使用)
-
-:::

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

@@ -1,96 +0,0 @@
----
-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/docs/zh/apis/app/runtime/web-server/hook.mdx

@@ -1,136 +0,0 @@
----
-title: Hook
----
-
-# Hook
-
-:::warning
-
-Hook API 已废弃，请使用[新版自定义 Web Server](/guides/advanced-features/web-server) 来处理页面请求。
-
-:::
-
-用于拓展 Modern.js 内置的 Web Server，所有的页面请求都会经过 Hook。
-
-
-## 使用姿势
-
-```ts
-import { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatchHook = (context, next) => {};
-export const afterRender: AfterRenderHook = (context, next) => {};
-```
-
-:::info 自定义 Web Server
-使用该 API 前，请先执行 `pnpm run new` 新建「自定义 Web Serve」源码目录。
-
-```bash
-pnpm run new
-? 请选择你想要的操作 创建工程元素
-? 新建「自定义 Web Server」源码目录
-```
-
-:::
-
-## 函数签名
-
-```ts
-type HookContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    getStatus: () => number;
-    cookies: {
-      set: (key: string, value: string, options?: any) => void;
-      clear: () => void;
-    };
-    raw: (
-      body: string,
-      { status, headers }: { status: number; headers: Record<string, any> },
-    ) => void;
-  };
-  request: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-};
-
-function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
-```
-
-另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AfterMatch` 和 `AfterRender` 两个 Hook。
-
-```ts
-type AfterMatchContext = HookContext & {
-  router: {
-    redirect: (url: string, status: number) => void;
-    rewrite: (entry: string) => void;
-  };
-};
-
-type AfterRenderContext = {
-  template: {
-    get: () => string;
-    set: (html: string) => void;
-    prependHead: (fragment: string) => void;
-    appendHead: (fragment: string) => void;
-    prependBody: (fragment: string) => void;
-    appendBody: (fragment: string) => void;
-  };
-};
-```
-
-### 参数
-
-- `context`：提供当前 Hook 上下文。
-  - `response`：提供一系列处理响应的操作
-  - `request`：提供一系列获取请求信息的操作
-  - `router`：提供对响应路由的快捷操作
-  - `template`：提供对响应内容的快捷操作
-- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
-
-## 示例
-
-### Redirect
-
-将页面重定向到站点外的页面，例如跳转到统一登录页：
-
-```ts
-import type { AfterMatch } from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatch = async (ctx, next) => {
-  ctx.router.redirect('https://website.com/login', 302);
-};
-```
-
-### Rewrite
-
-将页面重写到当前站点的其他页面，例如同一个路由根据 UA 返回适配不同端的页面：
-
-```ts
-import type { AfterMatch } from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatch = async (ctx, next) => {
-  ctx.router.rewrite('mobile');
-};
-```
-
-### HTML 内容注入
-
-为页面注入某些与渲染主体无关的 HTML 内容，如脚本、页面骨架等：
-
-```ts
-import type { AfterRender } from '@modern-js/runtime/server';
-
-export const afterRender: AfterRenderHook = (context, next) => {
-  ctx.template.prependBody('<div>Footer</div>');
-};
-```