docs(html): add example for Scripts component (#4090)

web-infra-dev · Jun 29, 2023 · 6ff29ae · 6ff29ae
1 parent 273e3cd
commit 6ff29ae
Show file tree

Hide file tree

Showing 2 changed files with 99 additions and 62 deletions.
diff --git a/packages/document/main-doc/docs/en/guides/basic-features/html.mdx b/packages/document/main-doc/docs/en/guides/basic-features/html.mdx
@@ -2,6 +2,7 @@
 title: HTML Template
 sidebar_position: 9
 ---
+
 # HTML Template
 
 Modern.js provides **JSX syntax** and **HTML(EJS) syntax** to customize the HTML template.
@@ -44,7 +45,7 @@ import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
 
 - `Head`: provide the ability of native Head Element and automatically fills in `<meta>` and `<Scripts>` components.
 
-- `Scripts`: provide the ability to adjust the position of script tags injected into the HTML during the build process. By default, it is placed in the `<Head>` component.
+- `Scripts`: Used to control the placement of the `<script>` tags generated by the build. By default, they are placed within the `<Head>` component.
 
 - `Comment`: retain user-written comments like `<!-- gateway -->` and outputs them to the rendered HTML.
 
@@ -59,7 +60,7 @@ Modern.js also provides `DocumentContext` to provide some configuration and envi
 - `entryName`: the current entry name.
 - `templateParams`: parameters of HTML template (compatible with traditional templates, so it's not recommended for use).
 
-### Example
+### Basic Example
 
 ```tsx
 import React, { useContext } from 'react';
@@ -68,8 +69,8 @@ import {
   Root,
   Head,
   Body,
-  DocumentContext,
   Comment,
+  DocumentContext,
 } from '@modern-js/runtime/document';
 
 export default function Document(): React.ReactElement {
@@ -89,9 +90,9 @@ export default function Document(): React.ReactElement {
       <Body>
         <Root rootId="root">
           <h1 style={{ color: 'red' }}>Some Params: </h1>
-          <h2> entryName：{entryName}</h2>
-          <h2> title：{htmlConfig.title}</h2>
-          <h2> rootId: {templateParams.mountId}</h2>
+          <h2>entryName: {entryName}</h2>
+          <h2>title: {htmlConfig.title}</h2>
+          <h2>rootId: {templateParams.mountId}</h2>
         </Root>
         <h1>bottom</h1>
       </Body>
@@ -105,46 +106,62 @@ The above JSX components will generate the following HTML template:
 ```html
 <!DOCTYPE html>
 <html>
-
-<head>
-    <meta charset="utf-8">
-    <meta name="viewport"
-        content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
-    <meta http-equiv="x-ua-compatible" content="ie=edge">
-    <meta name="renderer" content="webkit">
-    <meta name="layoutmode" content="standard">
-    <meta name="imagemode" content="force">
-    <meta name="wap-font-scale" content="no">
-    <meta name="format-detection" content="telephone=no">
-    <link rel="icon" href="/a.icon">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <meta http-equiv="x-ua-compatible" content="ie=edge" />
+    <meta name="renderer" content="webkit" />
+    <meta name="layoutmode" content="standard" />
+    <meta name="imagemode" content="force" />
+    <meta name="wap-font-scale" content="no" />
+    <meta name="format-detection" content="telephone=no" />
+    <link rel="icon" href="/a.icon" />
     <script defer src="/static/js/builder-runtime.js"></script>
     <script defer src="/static/js/lib-react.js"></script>
     <script defer src="/static/js/lib-polyfill.js"></script>
     <script defer src="/static/js/lib-router.js"></script>
-
-    <script>
-      ...
-    </script>
-    <script defer src="/static/js/sub.js"></script>
+    <script defer src="/static/js/main.js"></script>
     <link href="https://modernjs.dev" />
     <!-- Need a Comment -->
-</head>
+  </head>
 
-<body>
+  <body>
     <div id="root">
-        <!--<?- html ?>-->
-        <h1 style="color:red">Some Params: </h1>
-        <h2> entryName：sub</h2>
-        <h2> title：</h2>
-        <h2> rootId: root</h2>
+      <!--<?- html ?>-->
+      <h1 style="color:red">Some Params:</h1>
+      <h2>entryName: main</h2>
+      <h2>title：</h2>
+      <h2>rootId: root</h2>
     </div>
     <h1>bottom</h1>
     <!--<?- chunksMap.js ?>-->
     <!--<?- SSRDataScript ?>-->
-</body>
-
+  </body>
 </html>
+```
+
+### Scripts Component Example
 
+You can use the `<Scripts>` component to insert the `<script>` tags generated by the build inside the `<body>` tag:
+
+```tsx
+import React from 'react';
+import { Html, Root, Head, Body, Scripts } from '@modern-js/runtime/document';
+
+export default function Document(): React.ReactElement {
+  return (
+    <Html>
+      <Head></Head>
+      <Body>
+        <Root rootId="root"></Root>
+        <Scripts />
+      </Body>
+    </Html>
+  );
+}
 ```
 
 ## HTML Syntax
@@ -164,7 +181,7 @@ Under the application root directory, create the `config/html/` directory, which
 
 **These fragments will be injected into the default HTML template according to their positions.**
 
-```html
+```xml
 <!DOCTYPE html>
 <html>
   <head>

diff --git a/packages/document/main-doc/docs/zh/guides/basic-features/html.mdx b/packages/document/main-doc/docs/zh/guides/basic-features/html.mdx
@@ -47,7 +47,7 @@ import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
 
 - `Head`：提供原生 Head Element 的能力，并会自动填充 `<meta>`，以及 `<Scripts>` 组件。
 
-- `Scripts`：构建产生的 script 内容，可用于调整构建产物的位置，默认放在 `<Head>` 组件中。
+- `Scripts`：用于控制构建生成的 `<script>` 标签的位置，默认放在 `<Head>` 组件中。
 
 - `Comment`：将用户编写的 `<!-- gateway -->` 这种注释，保留输出到最新渲染的 html 中。
 
@@ -62,7 +62,7 @@ Modern.js 也提供了 `DocumentContext` 来提供一些配置、环境参数，
 - `entryName`：当前的入口名。
 - `templateParams`：HTML 模板的参数（为了兼容传统模板，不推荐使用）。
 
-### 示例
+### 基础示例
 
 ```tsx
 import React, { useContext } from 'react';
@@ -71,8 +71,8 @@ import {
   Root,
   Head,
   Body,
-  DocumentContext,
   Comment,
+  DocumentContext,
 } from '@modern-js/runtime/document';
 
 export default function Document(): React.ReactElement {
@@ -92,9 +92,9 @@ export default function Document(): React.ReactElement {
       <Body>
         <Root rootId="root">
           <h1 style={{ color: 'red' }}>以下为构建时传过来的参数：</h1>
-          <h2> entryName：{entryName}</h2>
-          <h2> title：{htmlConfig.title}</h2>
-          <h2> rootId: {templateParams.mountId}</h2>
+          <h2>entryName: {entryName}</h2>
+          <h2>title: {htmlConfig.title}</h2>
+          <h2>rootId: {templateParams.mountId}</h2>
         </Root>
         <h1>bottom</h1>
       </Body>
@@ -108,45 +108,65 @@ export default function Document(): React.ReactElement {
 ```html
 <!DOCTYPE html>
 <html>
-
-<head>
-    <meta charset="utf-8">
-    <meta name="viewport"
-        content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
-    <meta http-equiv="x-ua-compatible" content="ie=edge">
-    <meta name="renderer" content="webkit">
-    <meta name="layoutmode" content="standard">
-    <meta name="imagemode" content="force">
-    <meta name="wap-font-scale" content="no">
-    <meta name="format-detection" content="telephone=no">
-    <link rel="icon" href="/a.icon">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <meta http-equiv="x-ua-compatible" content="ie=edge" />
+    <meta name="renderer" content="webkit" />
+    <meta name="layoutmode" content="standard" />
+    <meta name="imagemode" content="force" />
+    <meta name="wap-font-scale" content="no" />
+    <meta name="format-detection" content="telephone=no" />
+    <link rel="icon" href="/a.icon" />
     <script defer src="/static/js/builder-runtime.js"></script>
     <script defer src="/static/js/lib-react.js"></script>
     <script defer src="/static/js/lib-polyfill.js"></script>
     <script defer src="/static/js/lib-router.js"></script>
-    <script xxx>
     <script defer src="/static/js/sub.js"></script>
     <link href="https://modernjs.dev" />
     <!-- Need a Comment -->
-</head>
+  </head>
 
-<body>
+  <body>
     <div id="root">
-        <!--<?- html ?>-->
-        <h1 style="color:red">以下为构建时传过来的参数：</h1>
-        <h2> entryName：sub</h2>
-        <h2> title：</h2>
-        <h2> rootId: root</h2>
+      <!--<?- html ?>-->
+      <h1 style="color:red">以下为构建时传过来的参数：</h1>
+      <h2>entryName: sub</h2>
+      <h2>title: </h2>
+      <h2>rootId: root</h2>
     </div>
     <h1>bottom</h1>
     <!--<?- chunksMap.js ?>-->
     <!--<?- SSRDataScript ?>-->
-</body>
-
+  </body>
 </html>
+```
+
+### Scripts 组件示例
+
+你可以使用 `<Scripts>` 组件，将构建生成的 `<script>` 标签插入到 `<body>` 标签内：
+
+```tsx
+import React, { useContext } from 'react';
+import { Html, Root, Head, Body, Scripts } from '@modern-js/runtime/document';
 
+export default function Document(): React.ReactElement {
+  return (
+    <Html>
+      <Head></Head>
+      <Body>
+        <Root rootId="root"></Root>
+        <Scripts />
+      </Body>
+    </Html>
+  );
+}
 ```
 
+
 ## Html 语法
 
 Modern.js 也支持 HTML 语法。默认情况下，Modern.js 的应用工程中会内置一份 HTML 模板，用于生成 HTML 代码。
@@ -164,7 +184,7 @@ Modern.js 也支持 HTML 语法。默认情况下，Modern.js 的应用工程中
 
 **这些片段将按位置注入到默认的 HTML 模板中。**
 
-```html
+```xml
 <!DOCTYPE html>
 <html>
   <head>