docs: modify use runtimeRuntimeContext api docs (#6507)

web-infra-dev · Nov 6, 2024 · 15553ca · 15553ca
1 parent a7ff13f
commit 15553ca
Show file tree

Hide file tree

Showing 2 changed files with 172 additions and 66 deletions.
diff --git a/packages/document/main-doc/docs/en/apis/app/runtime/core/use-runtime-context.mdx b/packages/document/main-doc/docs/en/apis/app/runtime/core/use-runtime-context.mdx
@@ -1,9 +1,6 @@
----
-title: useRuntimeContext
----
 # useRuntimeContext
 
-Used to get the runtime context and can only be used in function components.
+This function is primarily used to obtain the runtime context and can only be used in the function component.
 
 ## Usage
 
@@ -12,52 +9,108 @@ import { useRuntimeContext } from '@modern-js/runtime';
 
 export function App() {
   const runtimeContext = useRuntimeContext();
-  return <div>Hello World</div>;
+  return <div>Hello World</div>
 }
 ```
 
 ## Function Signature
 
 ```ts
 type RuntimeContext = {
-  request: {
-    params: Record<string, string>;
-    pathname: string;
-    query: Record<string, string>;
-    headers: IncomingHttpHeaders;
-    cookie: string;
-  };
-  store: ReduckStore;
-  router: RemixRouter;
+  context: RequestContext;
 };
-
-function useRuntimeContext(): RuntimeContext;
 ```
 
-### Return Value
+### context
 
-- `request`: additional information in the request context.
-  - `params`: dynamic parameters in the request path.
-  - `pathname`: the pathname of the request.
-  - `query`: the query of the request.
-  - `headers`: the header info of the request.
-  - `cookie`: the cookie of the request.
-- `store`: when the `runtime.state` is enabled, this value is the Reduck global `store`.
-- `router`: When the `runtime.router` is enabled, this value exists.
-  - `location`: The current location reflected by the router. The same as [`useLocation`] the return value of (/apis/app/runtime/router/router.html#uselocation).
-  - `navigate`: Navigate to the given path. The same as the return value of [`useNavigate`](/apis/app/runtime/router/router.html#usenavigate).
+Used to get [Request Context](#request-context).
 
 ## Example
 
-```tsx
-import { useRuntimeContext } from '@modern-js/runtime';
-import { fooModel } from '@/common/models';
+### Distinguish the runtime environment
 
+```ts
 function App() {
-  const { store } = useRuntimeContext();
+  const { context } = useRuntimeContext();
 
-  const [state, actions] = store.use(fooModel);
+  if (context.isBrowser === true) {
+    // browser-side execution logic
+    console.log('browser render')
+  } else {
+    // The server-side executes logic, which can access the unique 'logger' attribute
+    context.logger.info('server render')
+  }
+}
+```
 
-  return <div>state: {state}</div>;
+### Request context
+
+When SSR is enabled, uniform request contexts can be obtained in both the node environment and the browser-side environment.
+
+The slightly different is that the node environment also supports setting response headers, response codes, and provides Logger logs and Metrics management.
+
+:::tip
+when ssr is disabled, only the part of information that can be obtained in the browser environment is included.
+
+:::
+
+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>
diff --git a/packages/document/main-doc/docs/zh/apis/app/runtime/core/use-runtime-context.mdx b/packages/document/main-doc/docs/zh/apis/app/runtime/core/use-runtime-context.mdx
@@ -1,6 +1,3 @@
----
-title: useRuntimeContext
----
 # useRuntimeContext
 
 该函数主要用于获取 Runtime 上下文，只能在函数组件中使用。
@@ -12,52 +9,108 @@ import { useRuntimeContext } from '@modern-js/runtime';
 
 export function App() {
   const runtimeContext = useRuntimeContext();
-  return <div>Hello World</div>;
+  return <div>Hello World</div>
 }
 ```
 
 ## 函数签名
 
 ```ts
 type RuntimeContext = {
-  request: {
-    params: Record<string, string>;
-    pathname: string;
-    query: Record<string, string>;
-    headers: IncomingHttpHeaders;
-    cookie: string;
-  };
-  store: ReduckStore;
-  router: RemixRouter;
+  context: RequestContext;
 };
-
-function useRuntimeContext(): RuntimeContext;
 ```
 
-### 返回值
+### context
 
-- `request`：请求上下文中的附加信息。
-  - `params`：请求路径中的动态参数。
-  - `pathname`：请求的 pathname。
-  - `query`：请求的查询字符串对象。
-  - `headers`：请求头信息。
-  - `cookie`：请求的 cookie 信息。
-- `store`：在开启了 state 插件的时候，该值为 Reduck 全局 `store`。
-- `router`：在开启 router 插件的时候存在。
-  - `location`：当前路由对应的位置信息。同 [`useLocation`](/apis/app/runtime/router/router.html#uselocation) 返回值。
-  - `navigate`：导航到给定路径。同 [`useNavigate`](/apis/app/runtime/router/router.html#usenavigate) 返回值。
+用于获取[请求上下文](#请求上下文)。
 
-## 示例
+## 使用示例
 
-```tsx
-import { useRuntimeContext } from '@modern-js/runtime';
-import { fooModel } from '@/common/models';
+### 区分运行环境
 
+```ts
 function App() {
-  const { store } = useRuntimeContext();
+  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">
 
-  const [state, actions] = store.use(fooModel);
+```ts
+type RequestContext = ServerContext | ClientContext;
+```
+
+</TabItem>
+<TabItem value="ServerContext">
 
-  return <div>state: {state}</div>;
+```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>