@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/apis/app/runtime/container/router.md

@@ -0,0 +1,492 @@
+---
+title: router
+sidebar_position: 1
+---
+
+:::info 补充信息
+基于 [react-router](https://reactrouter.com/web/guides/start) 的路由解决方案。
+:::
+
+:::caution 注意
+使用该 API 前，请确认没有禁用 [router 插件](#)。
+:::
+
+## hooks
+
+### useHistory
+
+```ts
+function useHistory<HistoryLocationState = H.LocationState>(): H.History<HistoryLocationState>;
+```
+
+用于获取 `history` 实例。
+
+```tsx
+import { useHistory } from "@modern-js/runtime/router";
+
+export function HomeButton() {
+  let history = useHistory();
+
+  function handleClick() {
+    history.push("/home");
+  }
+
+  return (
+    <button type="button" onClick={handleClick}>
+      Go home
+    </button>
+  );
+}
+```
+
+### useLocation
+
+```ts
+function useLocation<S = H.LocationState>(): H.Location<S>;
+```
+
+`useLocation` 返回当前 url 对应的 [location](https://reactrouter.com/web/api/location) 对象。每当路由更新的时候，都会拿到一个新的 `location` 对象。
+
+```ts
+import React from "react";
+import { bootstrap, createApp } from '@modern-js/runtime';
+import { router } from '@modern-js/runtime/plugins';
+import {
+  BrowserRouter as Router,
+  Switch,
+  useLocation
+} from "@modern-js/runtime/router";
+
+function usePageViews() {
+  let location = useLocation();
+  React.useEffect(() => {
+    ga.send(["pageview", location.pathname]);
+  }, [location]);
+}
+
+function App() {
+  usePageViews();
+  return <Switch>...</Switch>;
+}
+```
+
+### useParams
+
+```ts
+function useParams<
+  Params extends {
+    [K in keyof Params]?: string
+  } = {}
+>(): Params;
+```
+
+`useParams` 返回一个 key/value 的键值对表示路由中的参数信息。它等同于 `<Route >` 组件中的 `match.params` 值。
+
+```tsx
+import React from "react";
+import {
+  Switch,
+  Route,
+  useParams
+} from "@modern-js/runtime/router";
+
+function BlogPost() {
+  const { slug } = useParams();
+  return <div>Now showing post {slug}</div>;
+}
+
+function App() {
+  return <Switch>
+    <Route exact path="/">
+      <div>home</div>
+    </Route>
+    <Route path="/blog/:slug">
+      <BlogPost />
+    </Route>
+  </Switch>
+}
+```
+
+### useRouteMatch
+
+```ts
+function useRouteMatch<
+  Params extends { [K in keyof Params]?: string } = {}
+>(): match<Params>;
+
+function useRouteMatch<
+  Params extends { [K in keyof Params]?: string } = {}
+>(
+  path: string | string[] | RouteProps,
+): match<Params> | null;
+```
+
+`useRouteMatch` 和 `<Route />` 一样是对路由进行匹配，但无须去渲染 `<Route />` 组件，便能获取到当前匹配结果。
+
+## 组件
+
+
+
+### Link
+
+```ts
+interface Link<S = H.LocationState>
+  extends React.ForwardRefExoticComponent<
+    React.PropsWithoutRef<LinkProps<S>> & React.RefAttributes<HTMLAnchorElement>
+> {}
+```
+
+可以使用 `Link` 组件进行路由跳转。
+
+```ts
+<Link to="/about">About</Link>
+```
+
+#### LinkProps
+
+**to**
+
+类型：`string | object | function`
+
+`string`
+
+```ts
+<Link to="/courses?sort=name" />
+```
+
+`object`
+
+```tsx
+<Link
+  to={{
+    pathname: "/courses",
+    search: "?sort=name",
+    hash: "#the-hash",
+    state: { fromDashboard: true }
+  }}
+/>
+```
+
+`function`
+
+```tsx
+<Link to={location => ({ ...location, pathname: "/courses" })} />
+
+<Link to={location => `${location.pathname}?sort=name`} />
+```
+
+**replace**
+
+类型：`boolean`
+
+当设置为 `true` 时，在跳转的时候替换掉 history 栈中的栈顶路由，而不是添加一个新路由。
+
+**component**
+
+类型：`Component`
+
+如果你想自定义你自己的路由跳转的组件，可以通过传入 `component` 来实现。
+
+```tsx
+ simply do so by passing it through the component prop.const FancyLink = React.forwardRef((props, ref) => (
+  <a ref={ref} {...props}>💅 {props.children}</a>
+))
+
+<Link to="/" component={FancyLink} />
+```
+
+### NavLink
+
+```ts
+interface NavLink<S = H.LocationState>
+  extends React.ForwardRefExoticComponent<
+    React.PropsWithoutRef<NavLinkProps<S>> & React.RefAttributes<HTMLAnchorElement>
+> {}
+```
+
+`NavLink` 是一种特殊的 [Link](#link) 组件，当 `NavLink` 对应路由匹配到当前 `url`, 会给 `NavLink` 所渲染的元素添加一些额外的样式。
+
+
+#### NavLinkProps
+
+**activeClassName**
+
+类型：`string`
+
+设置路由匹配时额外 class。
+
+```tsx
+<NavLink to="/faq" activeClassName="selected">
+  FAQs
+</NavLink>
+```
+
+**activeStyle**
+
+类型：`object`
+
+设置路由匹配时额外的样式。
+
+```tsx
+<NavLink
+  to="/faq"
+  activeStyle={{
+    fontWeight: "bold",
+    color: "red"
+  }}
+>
+  FAQs
+</NavLink>
+```
+
+**exact**
+
+类型：`boolean`
+
+
+**strict**
+
+类型：`boolean`
+
+**isActive**
+
+类型：`function`
+
+如果你想自定义当前 Link 是否激活的逻辑，可以使用 `isActive`。
+
+```tsx
+<NavLink
+  to="/events/123"
+  isActive={(match, location) => {
+    if (!match) {
+      return false;
+    }
+
+    // only consider an event active if its event id is an odd number
+    const eventID = parseInt(match.params.eventID);
+    return !isNaN(eventID) && eventID % 2 === 1;
+  }}
+>
+  Event 123
+</NavLink>
+```
+
+**location**
+
+类型：`object`
+
+`NavLink` 默认会和当前的 `history.location` 进行匹配，判断是否处于激活状态。如果你想指定要匹配的 `location` 对象，可以使用该参数。
+
+**area-current**
+
+类型：`string`
+
+参考 [aria-current](https://www.w3.org/TR/wai-aria-1.1/#aria-current)
+
+
+
+### Prompt
+
+```ts
+interface PromptProps {
+    message: string | ((location: H.Location, action: H.Action) => string | boolean);
+    when?: boolean;
+}
+
+class Prompt extends React.Component<PromptProps, any> {}
+```
+
+`Prompt` 组件可用于在页面跳转前，进行二次确认是否跳转。
+
+```tsx
+<Prompt
+  when={formIsHalfFilledOut}
+  message="Are you sure you want to leave?"
+/>
+```
+
+#### PromptProps
+
+**message**
+
+类型：`string` | `function`
+
+在页面跳转前的二次确认提示信息，支持传入函数形式。
+
+```tsx
+<Prompt
+  message={(location, action) => {
+    if (action === 'POP') {
+      console.log("Backing up...")
+    }
+
+    return location.pathname.startsWith("/app")
+      ? true
+      : `Are you sure you want to go to ${location.pathname}?`
+  }}
+/>
+```
+
+**when**
+
+类型：`boolean`
+
+当 `when` 为 `true` 时，才会在页面跳转前展示二次确认提示。
+
+
+### Route
+
+```ts
+interface RouteProps<
+  Path extends string = string,
+  Params extends { [K: string]: string | undefined } = ExtractRouteParams<Path, string>
+> {
+  location?: H.Location;
+  component?: React.ComponentType<RouteComponentProps<any>> | React.ComponentType<any>;
+  render?: (props: RouteComponentProps<Params>) => React.ReactNode;
+  children?: ((props: RouteChildrenProps<Params>) => React.ReactNode) | React.ReactNode;
+  path?: Path | Path[];
+  exact?: boolean;
+  sensitive?: boolean;
+  strict?: boolean;
+}
+
+class Route<T extends {} = {}, Path extends string = string> extends React.Component<
+  RouteProps<Path> & OmitNative<T, keyof RouteProps>,
+  any
+> {}
+```
+
+`Route` 组件用于定义路由。
+
+#### component
+
+类型：`React.ComponentType`
+
+当路由匹配成功，会渲染传入 `component` 的组件。
+
+```tsx
+import React from "react";
+import { Route } from "@modern-js/runtime/router";
+
+// All route props (match, location and history) are available to User
+function User(props) {
+  return <h1>Hello {props.match.params.username}!</h1>;
+}
+
+function App() {
+  return <Route path="/user/:username" component={User} />;
+}
+```
+
+:::tip 提示
+如果 component 是一个 inline function，如 `<Route path="/user/:username" component={() => 'hello'} />`，因为每次 rerender 的时候，component 都会是一个新的 `type`，所以 component 组件会先 unmount，再 mount。我们需要避免这种写法，或者使用 render 代替 component。
+:::
+
+#### render
+
+类型：`(props: RouteComponentProps<Params>) => React.ReactNode`
+
+允许使用 `inline function` 进行渲染，同时不会有 `component` remounting 的问题。
+
+```tsx
+import React from "react";
+import { Route } from "@modern-js/runtime/router";
+
+function App() {
+  <Route path="/home" render={() => <div>Home</div>} />
+}
+```
+
+:::info 注
+component 的优先级高于 render。
+:::
+
+#### children
+
+类型：`((props: RouteChildrenProps<Params>) => React.ReactNode) | React.ReactNode`
+
+如果在路由匹配或不匹配的情况下，都需要渲染一些内容，那么可以使用 `children` 参数。
+
+```tsx
+function ListItemLink({ to, ...rest }) {
+  return (
+    <Route
+      path={to}
+      children={({ match }) => (
+        <li className={match ? "active" : ""}>
+          <Link to={to} {...rest} />
+        </li>
+      )}
+    />
+  );
+}
+
+function App() {
+  return <ul>
+    <ListItemLink to="/somewhere" />
+    <ListItemLink to="/somewhere-else" />
+  </ul>;
+}
+```
+
+#### path
+
+类型：`string | string[]`
+
+符合 [path-to-regexp@^1.7.0](https://github.com/pillarjs/path-to-regexp/tree/v1.7.0) 匹配规则的 url 字符串或数组。
+
+```tsx
+<Route path="/users/:id">
+  <User />
+</Route>
+
+<Route path={["/users/:id", "/profile/:id"]}>
+  <User />
+</Route>
+```
+
+#### exact
+
+类型：`boolean`
+
+默认值：`false`
+
+当 `exact` 值为 `true` 时，会进行准确匹配。
+
+|  path   | location.pathname | exact | matches? |
+|  -  | -  | - | - |
+| /one  | /one/two	 | true  | no  |
+| /one  | /one/two	 | false | yes |
+
+
+#### strict
+
+类型：`boolean`
+
+默认值：`false`
+
+当 `strict` 值为 `true` 时，会进行严格匹配。若 `path` 以 '/' 结尾，那么 `location.pathname` 也需要以 '/' 结尾，才能匹配。
+
+|  path   | location.pathname | matches? |
+|  -  | - | - |
+| /one/  | /one  | no  |
+| /one/  | /one/ | yes |
+| /one/| /one/two | yes |
+
+#### sensitive
+
+类型：`boolean`
+
+默认值：`false`
+
+当 `sensitive` 设置为 `true`，则 path 大小写不敏感。
+
+#### location
+
+类型：`object`
+
+## 更多底层 API
+
+若想要了解更多的底层 API 信息，可至 [react-router 官网](https://reactrouter.com/web/guides/start) 查看。
+

package/zh/apis/app/runtime/container/use-loader.md

@@ -0,0 +1,64 @@
+---
+title: useLoader
+sidebar_position: 2
+---
+
+:::info 补充信息
+一个同构的 API，通常会用来做异步请求。当 SSR 的时候，服务端使用 `useLoader` 预加载数据，同时浏览器端也会复用这部分数据。
+
+```ts
+import { useLoader } from "@modern-js/runtime";
+```
+
+:::
+
+## API
+
+`useLoader(loaderFn,[options]) => object`
+
+### 参数
+
+- loaderFn: `(context: any, params: Record<string, any>) => Promise`，用于加载数据的函数，返回 Promise。
+- [options]: `object` ，可选配置项。
+  - [onSuccess]: `(data: Record<string, any>) => void`，`loaderFn` 执行成功的回调。
+  - [onError]: `(error: Error) => void`，`loaderFn` 执行失败的回调。
+  - [initialData]: `Record<string, any>`， `loaderFn` 首次执行前的初始数据，对应返回值中的 `data` 字段。
+  - [skip]: `boolean`，当值为 `true` 时， `loaderFn` 不执行。
+  - [params]: `Record<string, any>`， 当 `params` 序列化结果发生改变时，`loaderFn` 会重新执行。同时，`params` 也会作为 `loaderFn` 的第二个参数被传入。
+  - [static]: `boolean`，当值为 `true` 时，`useLoader` 用于 [SSG](/docs/guides/advanced-features/ssg) 编译阶段数据的获取。
+
+### 返回值
+
+- data: `Record<string, any>`， `loaderFn` 函数执行成功时的返回数据。
+- loading: `boolean`，表示 `loaderFn` 是否处于执行过程中。
+- error: `Error`，`loaderFn` 函数执行失败时的错误信息。
+- reload: `(params?: Params) => Promise<any> | undefined`，调用该函数可以重新执行 `loaderFn`。
+  - params?: `Record<string, any> | undefined`，当 `params` 为 `undefined`，`loaderFn` 执行时将复用上次的 `params` 参数；当 `params` 有值时，则会使用新的 `params` 参数重新执行 `loaderFn`。
+- reloading: `boolean`，调用 `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/zh/apis/app/runtime/default-alias.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+---
+# 默认别名
+
+
+:::tip 提示
+- 除了以下默认别名，开发者可以在 `modern.config.js` 中自定义别名，详见[如何配置别名](/docs/configure/app/source/alias)。
+:::
+
+
+Modern.js 推荐通过别名的方式引用源码，其中包含 3 种默认别名:
+- `@/`：等价于引用项目根目录 `src/*` 下的文件。
+- `@api/`：等价于引用项目根目录下 `api/*` 下的文件（需要先开启 BFF 功能）。
+- `@shared/`：等价于引用项目根目录下 `shared/*` 下的文件。
+
+
+## 示例
+下面的例子展示了如何通过默认别名引用函数。
+```tsx
+import { hello } from '@/common/utils';
+
+hello();
+
+```
+引用 `@/common/utils` 相当于引用 `src/common/utils`。

package/zh/apis/app/runtime/env.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 1
+title: 环境变量
+---
+
+
+Modern.js 默认提供了下列环境变量：
+
+- `NODE_ENV`：表示当前的执行环境。
+- `PORT`：表示应用运行的端口。
+
+## NODE_ENV
+
+表示当前的执行环境，是**只读的**的环境变量，其值在不同的执行命令下具有不同的值：
+
+- `production`：执行 `modern build` 命令时的默认值。
+- `test`：执行 `modern test` 命令时的默认值。
+- `development`：执行 `modern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
+
+## 自定义环境变量
+
+除了上述默认提供的环境变量，还可以通过 `shell` 或 `.env` 文件自定义环境变量。
+
+### 通过 `shell` 指定
+
+在命令前添加自定义环境变量：
+
+```shell
+FOO=123 BAR=456 pnpm run dev
+```
+
+### 通过 `.env` 文件指定
+
+在项目根目录创建 `.env` 文件，其中添加自定义环境变量：
+
+```env
+FOO=123
+BAR=456
+```
+
+更多文件格式：
+
+- `.env`：默认文件。
+- `.env.development`：当 `NODE_ENV` 值为 `development` 时，读取该文件。
+- `.env.production`：当 `NODE_ENV` 值为 `production` 时，读取该文件。
+- `.env.test`：当 `NODE_ENV` 值为 `test` 时，读取该文件。
+
+### 优先级
+
+- 当 `.env.*` 与 `.env` 同时存在，`.env.*` 会和 `.env` 进行合并，相同名称的环境变量以 `.env.*` 为准。
+- 通过 `.env` 设置的环境变量，优先级高于 `shell` 指定的环境变量。
+
+## 使用环境变量
+
+### JS/TS 代码内使用
+
+通过 `process.env.*` 直接获取环境变量。
+
+```js
+console.log(process.env.NODE_ENV);
+// "development"
+```
+
+### HTML 代码片段使用
+
+```html title="config/html/head.ejs"
+<meta name="env" content="<%=process.env.NODE_ENV %>" />
+```

package/zh/apis/app/runtime/index.md

@@ -0,0 +1,12 @@
+---
+type: ref
+---
+
+# 运行时
+
+本节涵盖了使用 `@modern-js/runtime` 的所有 API。
+
+
+
+
+

package/zh/apis/app/runtime/model/Provider.md

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

package/zh/apis/app/runtime/model/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Model API",
+  "position": 4
+}