docs: add json docs (#20)

* fix: unify zh docs subtitle * docs: add json docs
varletjs · Nov 3, 2024 · a972e82 · a972e82
1 parent 7936fb5
commit a972e82
Show file tree

Hide file tree

Showing 25 changed files with 146 additions and 20 deletions.
diff --git a/docs/.vitepress/items/util.ts b/docs/.vitepress/items/util.ts
@@ -14,4 +14,6 @@ export const utilItems = [
   { text: 'getScrollLeft', link: '/util/get-scroll-left' },
   { text: 'getParentScroller', link: '/util/get-parent-scroller' },
   { text: 'getAllParentScroller', link: '/util/get-all-parent-scroller' },
+  { text: 'prettyJSONObject', link: '/util/pretty-JSON-object' },
+  { text: 'tryParseJSON', link: '/util/try-parse-JSON' },
 ]
diff --git a/docs/util/pretty-JSON-object.md b/docs/util/pretty-JSON-object.md
@@ -0,0 +1,33 @@
+# prettyJSONObject
+
+Formats a `JSON` object with indentation for easy readability.
+
+### Usage
+
+```ts
+import { prettyJSONObject } from 'rattail'
+
+const jsonObject = { key: 'value', nested: { key: 'nestedValue' } }
+const pretty = prettyJSONObject(jsonObject)
+console.log(pretty)
+/*
+{
+  "key": "value",
+  "nested": {
+    "key": "nestedValue"
+  }
+}
+*/
+```
+
+### Arguments
+
+| Arg          | Type     | Defaults |
+| ------------ | -------- | -------- |
+| `jsonObject` | `object` |          |
+
+### Return
+
+| Type     |
+| -------- |
+| `string` |
diff --git a/docs/util/try-parse-JSON.md b/docs/util/try-parse-JSON.md
@@ -0,0 +1,29 @@
+# tryParseJSON
+
+Attempts to parse a `JSON` string. If parsing fails, returns `undefined`.
+
+### Usage
+
+```ts
+import { tryParseJSON } from 'rattail'
+
+const jsonString = '{"key": "value"}'
+const parsed = tryParseJSON(jsonString)
+console.log(parsed) // { key: "value" }
+
+const invalidJsonString = '{"key": value}'
+const invalidParsed = tryParseJSON(invalidJsonString)
+console.log(invalidParsed) // undefined
+```
+
+### Arguments
+
+| Arg    | Type     | Defaults |
+| ------ | -------- | -------- |
+| `json` | `string` |          |
+
+### Return
+
+| Type                  |
+| --------------------- |
+| `object \| undefined` |
diff --git a/docs/zh/collection/merge-with.md b/docs/zh/collection/merge-with.md
@@ -2,7 +2,7 @@
 
 递归合并两个对象，可通过回调函数自定义合并逻辑。
 
-### 用法
+### 使用
 
 ```ts
 import { mergeWith } from 'rattail'

diff --git a/docs/zh/collection/merge.md b/docs/zh/collection/merge.md
@@ -2,7 +2,7 @@
 
 递归合并两个对象。
 
-### 用法
+### 使用
 
 ```ts
 import { merge } from 'rattail'

diff --git a/docs/zh/file/to-array-buffer.md b/docs/zh/file/to-array-buffer.md
@@ -2,7 +2,7 @@
 
 将 `File` 对象转换为 `ArrayBuffer`。
 
-### 用法
+### 使用
 
 ```ts
 import { toArrayBuffer } from 'rattail'

diff --git a/docs/zh/file/to-data-url.md b/docs/zh/file/to-data-url.md
@@ -2,7 +2,7 @@
 
 将 `File` 对象转换为 Data URL 字符串。
 
-### 用法
+### 使用
 
 ```ts
 import { toDataURL } from 'rattail'

diff --git a/docs/zh/file/to-text.md b/docs/zh/file/to-text.md
@@ -2,7 +2,7 @@
 
 将 `File` 对象转换为文本字符串。
 
-### 用法
+### 使用
 
 ```ts
 import { toText } from 'rattail'

diff --git a/docs/zh/util/cancel-animation-frame.md b/docs/zh/util/cancel-animation-frame.md
@@ -2,7 +2,7 @@
 
 使用给定的句柄取消 `requestAnimationFrame` 请求，并使用 `clearTimeout` 作为回退选项。
 
-### 用法
+### 使用
 
 ```ts
 import { cancelAnimationFrame } from 'rattail'

diff --git a/docs/zh/util/classes.md b/docs/zh/util/classes.md
@@ -2,7 +2,7 @@
 
 根据给定条件生成类名列表，或直接返回类名。
 
-### 用法
+### 使用
 
 ```ts
 import { classes } from 'rattail'

diff --git a/docs/zh/util/create-namespace-fn.md b/docs/zh/util/create-namespace-fn.md
@@ -2,7 +2,7 @@
 
 创建一个命名空间函数，用于生成 BEM 样式的组件和类名。
 
-### 用法
+### 使用
 
 ```ts
 import { createNamespaceFn } from 'rattail'

diff --git a/docs/zh/util/double-raf.md b/docs/zh/util/double-raf.md
@@ -2,7 +2,7 @@
 
 创建一个基于 `Promise` 的双重 `requestAnimationFrame`，在两帧之后 `resolved`。
 
-### 用法
+### 使用
 
 ```ts
 import { doubleRaf } from 'rattail'

diff --git a/docs/zh/util/get-all-parent-scroller.md b/docs/zh/util/get-all-parent-scroller.md
@@ -2,7 +2,7 @@
 
 获取元素的所有可滚动父级元素，包含 `window` 作为最后一项。
 
-### 用法
+### 使用
 
 ```ts
 import { getAllParentScroller } from 'rattail'

diff --git a/docs/zh/util/get-parent-scroller.md b/docs/zh/util/get-parent-scroller.md
@@ -2,7 +2,7 @@
 
 查找元素的最近可滚动父级元素。如果没有找到滚动父级，则返回 `window`。
 
-### 用法
+### 使用
 
 ```ts
 import { getParentScroller } from 'rattail'

diff --git a/docs/zh/util/get-rect.md b/docs/zh/util/get-rect.md
@@ -2,7 +2,7 @@
 
 获取元素或窗口的尺寸和位置，返回一个 `DOMRect` 对象。
 
-### 用法
+### 使用
 
 ```ts
 import { getRect } from 'rattail'

diff --git a/docs/zh/util/get-scroll-left.md b/docs/zh/util/get-scroll-left.md
@@ -2,7 +2,7 @@
 
 获取元素或窗口的水平滚动位置。
 
-### 用法
+### 使用
 
 ```ts
 import { getScrollLeft } from 'rattail'

diff --git a/docs/zh/util/get-scroll-top.md b/docs/zh/util/get-scroll-top.md
@@ -2,7 +2,7 @@
 
 获取元素或窗口的垂直滚动位置。
 
-### 用法
+### 使用
 
 ```ts
 import { getScrollTop } from 'rattail'

diff --git a/docs/zh/util/get-style.md b/docs/zh/util/get-style.md
@@ -2,7 +2,7 @@
 
 获取给定 DOM 元素的计算 CSS 样式。
 
-### 用法
+### 使用
 
 ```ts
 import { getStyle } from 'rattail'

diff --git a/docs/zh/util/in-viewport.md b/docs/zh/util/in-viewport.md
@@ -2,7 +2,7 @@
 
 判断元素是否在视口内可见。
 
-### 用法
+### 使用
 
 ```ts
 import { inViewport } from 'rattail'

diff --git a/docs/zh/util/mitt.md b/docs/zh/util/mitt.md
@@ -2,7 +2,7 @@
 
 事件调度器，集成了 [mitt](https://github.com/developit/mitt)。
 
-### 用法
+### 使用
 
 ```ts
 import { mitt } from 'rattail'

diff --git a/docs/zh/util/pretty-JSON-object.md b/docs/zh/util/pretty-JSON-object.md
@@ -0,0 +1,33 @@
+# prettyJSONObject
+
+格式化 `JSON` 对象，增加缩进以便于阅读。
+
+### 使用
+
+```ts
+import { prettyJSONObject } from 'rattail'
+
+const jsonObject = { key: 'value', nested: { key: 'nestedValue' } }
+const pretty = prettyJSONObject(jsonObject)
+console.log(pretty)
+/*
+{
+  "key": "value",
+  "nested": {
+    "key": "nestedValue"
+  }
+}
+*/
+```
+
+### 参数
+
+| 参数         | 类型     | 默认值 |
+| ------------ | -------- | ------ |
+| `jsonObject` | `object` |        |
+
+### 返回值
+
+| 类型     |
+| -------- |
+| `string` |
diff --git a/docs/zh/util/prevent-default.md b/docs/zh/util/prevent-default.md
@@ -2,7 +2,7 @@
 
 阻止事件的默认行为（如果该事件可取消）。
 
-### 用法
+### 使用
 
 ```ts
 import { preventDefault } from 'rattail'

diff --git a/docs/zh/util/raf.md b/docs/zh/util/raf.md
@@ -2,7 +2,7 @@
 
 创建一个基于 `Promise` 的 `requestAnimationFrame`，在下一帧时 `resolved`。
 
-### 用法
+### 使用
 
 ```ts
 import { raf } from 'rattail'

diff --git a/docs/zh/util/request-animation-frame.md b/docs/zh/util/request-animation-frame.md
@@ -2,7 +2,7 @@
 
 提供跨浏览器兼容的 `requestAnimationFrame` 函数，并使用 `setTimeout` 作为回退选项。
 
-### 用法
+### 使用
 
 ```ts
 import { requestAnimationFrame } from 'rattail'

diff --git a/docs/zh/util/try-parse-JSON.md b/docs/zh/util/try-parse-JSON.md
@@ -0,0 +1,29 @@
+# tryParseJSON
+
+尝试解析 `JSON` 字符串。如果解析失败，返回 `undefined`。
+
+### 使用
+
+```ts
+import { tryParseJSON } from 'rattail'
+
+const jsonString = '{"key": "value"}'
+const parsed = tryParseJSON(jsonString)
+console.log(parsed) // { key: "value" }
+
+const invalidJsonString = '{"key": value}'
+const invalidParsed = tryParseJSON(invalidJsonString)
+console.log(invalidParsed) // undefined
+```
+
+### 参数
+
+| 参数   | 类型     | 默认值 |
+| ------ | -------- | ------ |
+| `json` | `string` |        |
+
+### 返回值
+
+| 类型                  |
+| --------------------- |
+| `object \| undefined` |