Merge branch 'main' into docs

src/App.tsx

@@ -1,4 +1,4 @@
-import { Calendar, ConfigProvider, DatePicker } from 'antd';
+import { ConfigProvider } from 'antd';
 import React, { useEffect } from 'react';
 import { HashRouter } from 'react-router-dom';
 import RouteConfig from './routes/config';

src/main.tsx

@@ -5,6 +5,17 @@ import '@/assets/style/initial.less';
 import '@/assets/locales/index';
 import './init';
 
-const root = ReactDOM.createRoot(document.querySelector('#root')!);
+function main() {
+  const { href } = window.location;
+  const decoded = decodeURIComponent(href);
+  if (href !== decoded) {
+    window.location.href = decoded;
+    return;
+  }
 
-root.render(<App />);
+  const root = ReactDOM.createRoot(document.querySelector('#root')!);
+
+  root.render(<App />);
+}
+
+main();

src/pages/Docs/components/DocContent/index.less

@@ -62,7 +62,7 @@
   li {
     > p {
       margin-bottom: @paragraph-space;
-      &:last-child {
+      &:only-child {
         margin-bottom: 0;
       }
     }
@@ -95,7 +95,7 @@
   ul,
   ol {
     padding-left: 20px;
-    margin-block: 4px;
+    margin-bottom: 12px;
   }
   iframe {
     display: block;

src/pages/Docs/components/DocContent/index.tsx

@@ -149,20 +149,31 @@ export const DocContent = () => {
   const { hash, pathname } = useLocation();
   const scrollIntoAnchor = useCallback(() => {
     if (!hash) return;
-    rootRef.current?.querySelector(decodeURIComponent(hash))?.scrollIntoView({
-      block: 'center',
-    });
+
+    const container = rootRef.current;
+    const node = container?.querySelector(hash) as HTMLElement;
+    if (!container || !node) return;
+
+    setTimeout(() => {
+      const top = node.offsetTop - 100;
+      container.scrollTo({
+        top,
+      });
+    }, 100);
   }, [hash]);
   useEventListener(LOAD_DOC_EVENT, (e) => {
     const { detail } = e as CustomEvent;
     if (detail.loading === false) {
       scrollIntoAnchor();
     }
   });
+
+  // 切换文档，回到顶部
   useEffect(() => {
     if (hash) return;
     rootRef.current?.scrollTo(0, 0);
   }, [hash, pathname]);
+
   // 点击锚点
   useEffect(scrollIntoAnchor, [scrollIntoAnchor]);
 

src/pages/Docs/components/DocMenus/index.tsx

@@ -85,6 +85,10 @@ export const DOC_MENUS = [
       ko: '에 관하여',
     },
     children: [
+      {
+        label: 'API',
+        doc: 'api',
+      },
       {
         label: {
           zh: '离线日志回放',

src/pages/Docs/md/api.en.mdx

@@ -0,0 +1,27 @@
+### PageSpy#pagespy
+
+> The instance variable is named `$pageSpy = new PageSpy(...)`；
+
+- [constructor()](./pagespy#constructor)
+- [$pageSpy.updateRoomInfo()](./pagespy#updateRoomInfo)
+- [$pageSpy.abort()](./pagespy#abort)
+- [PageSpy.registerPlugin()](./pagespy#registerPlugin)
+- [PageSpy.pluginsWithOrder](./pagespy#pluginsWithOrder)
+- [$pageSpy.version](./pagespy#version)
+- [$pageSpy.config](./pagespy#config)
+- [$pageSpy.socketStore](./pagespy#socketStore)
+
+### Plugins#plugins
+
+#### DataHarborPlugin#harbor
+
+> The instance variable is named `$harbor = new DataHarborPlugin(...)`；
+
+- [constructor()](./data-harbor#constructor)
+- [$harbor.onOfflineLog()](./data-harbor#onOfflineLog)
+
+#### RRWebPlugin#rrweb
+
+> The instance variable is named `$rrweb = new RRWebPlugin(...)`；
+
+- [constructor()](./rrweb#constructor)

src/pages/Docs/md/api.zh.mdx

@@ -0,0 +1,27 @@
+### PageSpy#pagespy
+
+> 约定实例变量名称为 `$pageSpy = new PageSpy(...)`；
+
+- [constructor()](./pagespy#constructor)
+- [$pageSpy.updateRoomInfo()](./pagespy#updateRoomInfo)
+- [$pageSpy.abort()](./pagespy#abort)
+- [PageSpy.registerPlugin()](./pagespy#registerPlugin)
+- [PageSpy.pluginsWithOrder](./pagespy#pluginsWithOrder)
+- [$pageSpy.version](./pagespy#version)
+- [$pageSpy.config](./pagespy#config)
+- [$pageSpy.socketStore](./pagespy#socketStore)
+
+### 插件#plugins
+
+#### DataHarborPlugin#harbor
+
+> 约定实例变量名称为 `$harbor = new DataHarborPlugin(...)`；
+
+- [constructor()](./data-harbor#constructor)
+- [$harbor.onOfflineLog()](./data-harbor#onOfflineLog)
+
+#### RRWebPlugin#rrweb
+
+> 约定实例变量名称为 `$rrweb = new RRWebPlugin(...)`；
+
+- [constructor()](./rrweb#constructor)

src/pages/Docs/md/changelog.en.mdx

@@ -11,6 +11,7 @@
     serializeData: true
   })
   ```
+
 - 🆕 Optimized information display in the Network panel. For more details, see: https://github.com/HuolalaTech/page-spy-web/pull/239;
 - 🆕 The replay panel now supports canvas content. For more details, see: https://github.com/HuolalaTech/page-spy-web/pull/238;
 - 🆕 The left-side player during playback now shows "click" actions. The progress bar now only shows clicks and errors, with other data activities notified through the Tab. For more details, see: https://github.com/HuolalaTech/page-spy-web/pull/247;

src/pages/Docs/md/changelog.zh.mdx

@@ -1,16 +1,17 @@
 ## v1.9.1
 
 - 🆕 实例化参数新增 `serializeData: boolean` 选项，用于指定是否允许 SDK 在收集离线日志时，序列化非基本类型的数据，默认值 `false`。查看详情：https://github.com/HuolalaTech/page-spy-web/pull/241 / https://github.com/HuolalaTech/page-spy/pull/103 ；
-
+  
   开启后，console 打印的数据在日志回放面板上支持展开查看，使用方式：
-
+  
   ```ts
   window.$pageSpy = new PageSpy({
     ...
     // 注意，序列化过程可能会产生副作用，为了安全起见，默认 false 不序列化；
     serializeData: true
   })
   ```
+
 - 🆕 优化 Network 展示的信息，查看详情：https://github.com/HuolalaTech/page-spy-web/pull/239 ；
 - 🆕 回放面板支持回放 canvas 内容，查看详情：https://github.com/HuolalaTech/page-spy-web/pull/238 ；
 - 🆕 回放时左侧的操作轨迹展示点击动作；进度条上现在只展示点击、报错，其他数据活动通过 Tab 通知。查看详情：https://github.com/HuolalaTech/page-spy-web/pull/244 / https://github.com/HuolalaTech/page-spy-web/pull/247

src/pages/Docs/md/data-harbor.en.mdx

@@ -0,0 +1,59 @@
+
+## DataHarborPlugin API#api
+
+#### constructor()#constructor
+
+- Type
+
+  ```ts
+  interface DataHarborConfig {
+    // Specify the maximum bytes of offline log in memory.
+    // Default 10MB.
+    maximum?: number;
+
+    // Specit which types of data to cache
+    caredData?: Record<DataType, boolean>;
+
+    // Specify the offline log filename, with the default being named according to the current time
+    filename?: () => string;
+
+    // Custom the behavior of download
+    onDownload?: (data: CacheMessageItem[]) => void;
+  }
+
+  delcare class DataHarborPlugin implements PageSpyPlugin {
+    constructor(config?: DataHarborConfig);
+  }
+  ```
+
+#### onOfflineLog()#onOfflineLog
+
+Upload / download log manaually.
+
+- Type
+
+  ```ts
+  declare class DataHarborPlugin {
+    onOfflineLog(type: 'download' | 'upload'): Promise<string | null | undefined>;
+  }
+  ```
+
+- Details
+
+  If you hide the automatically rendered floating or want to automatically trigger offline log operations at certain times, you can achieve through this method.
+
+  Each invocation logs the entire current session. Once the upload is complete, a replay URL will be returned.
+
+- Example
+
+  ```ts
+  window.$harbor = new DataHarborPlugin();
+
+  // upload
+  const url = await window.$harbor.onOfflineLog('upload');
+
+  // download
+  window.$harbor.onOfflineLog('download');
+  ```
+
+

src/pages/Docs/md/data-harbor.zh.mdx

@@ -0,0 +1,61 @@
+
+## DataHarborPlugin API#api
+
+#### constructor()#constructor
+
+- 类型
+
+  ```ts
+  interface DataHarborConfig {
+    // 离线日志数据会优先记录在内存中，当体积达到多大时写入临时文件
+    // 默认 10M (10 * 1024 * 1024)
+    maximum?: number;
+
+    // 指定缓存哪些类型的数据
+    caredData?: Record<DataType, boolean>;
+
+    // 指定离线日志文件名，默认是根据当前时间命名
+    filename?: () => string;
+
+    // 自定义下载逻辑
+    onDownload?: (data: CacheMessageItem[]) => void;
+  }
+
+  delcare class DataHarborPlugin implements PageSpyPlugin {
+    constructor(config?: DataHarborConfig);
+  }
+  ```
+
+
+
+#### onOfflineLog()#onOfflineLog
+
+手动操作离线日志的下载、上传。
+
+- 类型
+
+  ```ts
+  declare class DataHarborPlugin {
+    onOfflineLog(type: 'download' | 'upload'): Promise<string | null | undefined>;
+  }
+  ```
+
+- 详细信息
+
+  如果隐藏了自动渲染的 UI 控件，或者希望在某些时候自动触发队离线日志的操作，可以通过该方法实现。
+
+  每次调用都是当前会话的完整日志。上传完成后会返回回放的 URL，并打印到控制台。
+
+- 示例
+
+  ```ts
+  window.$harbor = new DataHarborPlugin();
+
+  // 上传
+  const url = await window.$harbor.onOfflineLog('upload');
+
+  // 下载
+  window.$harbor.onOfflineLog('download');
+  ```
+
+

src/pages/Docs/md/faq.en.mdx

@@ -26,67 +26,7 @@ window.$pageSpy = new PageSpy({
 
 ### Instantiation Parameters and Their Purposes?#init-params
 
-> All parameters are optional. Below are explanations and default values for each parameter:
-
-```js
-window.$pageSpy = new PageSpy({
-  // SDK will automatically determine server address (api) and client origin (clientOrigin) from the imported path
-  // For example, if you import SDK via <script src="https://example.com/page-spy/index.min.js">,
-  // SDK will internally set:
-  //   - api: "example.com"
-  //   - clientOrigin: "https://example.com"
-  // If your service is deployed elsewhere, you need to manually specify it here to override.
-  api: "",
-  clientOrigin: "", // Only applicable for browser environment
-
-  // Project serves as an aggregation of information, searchable in the room list
-  project: "default",
-
-  // Title allows users to provide custom parameters for distinguishing the current client
-  // Corresponding information appears below the "device id" in each connection panel
-  title: "--",
-
-  // Indicates whether SDK initializes and automatically renders "circular white logo on a white background" control in the lower left corner of the client
-  // If set to false, you can call window.$pageSpy.render() to render manually
-  autoRender: true,  // Only applicable for browser environment
-
-  // Manually specify PageSpy service scheme.
-  // This can be used if SDK cannot correctly analyze the scheme, such as PageSpy's browser plugin
-  // is imported via chrome-extension://xxx/sdk/index.min.js, which SDK interprets as invalid "chrome-extension://" and falls back to ["http://", "ws://"].
-  //   - (Default) Pass undefined or null: SDK will analyze automatically;
-  //   - Pass boolean value:
-  //     - true: SDK will access PageSpy service via ["https://", "wss://"]
-  //     - false: SDK will access PageSpy service via ["http://", "ws://"]
-  enableSSL: null,
-
-  // After PageSpy@1.7.4 supports offline playback function, SDK integrated into the client can collect data, export offline logs, and become a new usage mode.
-  // Default value is false. When set to other values, it enters "offline mode", where PageSpy does not create rooms or establish WebSocket connections.
-  offline: false, // Only applicable for browser environment
-
-  // Custom control rendering logo
-  logo: '', // Only applicable for browser environment
-
-  // Set logo style
-  logoStyle: {}, // Only applicable for browser environment
-
-  // All internal plugins are carried with PageSpy by default out of the box. You can disable some plugins as needed.
-  disabledPlugins: [],
-
-  // Specify whether the SDK is allowed to serialize non-primitive data types when collecting offline data
-  serializeData: false,
-
-  // Indicate whether authorization is required. If enabled, PageSpy generates a 6-digit random number (below "secret") as a password for the debug room,
-  // which is required for developers to access the debug room
-  useSecret: false,
-
-  // Specify how many messages to cache.
-  // The data is primarily used to configure the maximum number of historical data the SDK can send after the debugging terminal goes online.
-  messageCapacity: 1000,
-
-  // Disable on production environment
-  disabledOnProd: true, // Only applicable for miniprogram
-})
-```
+See [PageSpy API](./pagespy#constructor).
 
 ### How to Update Initialization Parameters? #update-info