From 1b82b874ba1d03ac4f7610837969937f14a37b63 Mon Sep 17 00:00:00 2001 From: Aybrea Date: Thu, 31 Oct 2024 21:46:24 +0800 Subject: [PATCH 1/2] docs: add element docs --- docs/.vitepress/config.ts | 19 +++++++++++++++- docs/.vitepress/items/element.ts | 16 ++++++++++++++ docs/.vitepress/items/index.ts | 1 + docs/element/cancel-animation-frame.md | 24 +++++++++++++++++++++ docs/element/classes.md | 23 ++++++++++++++++++++ docs/element/create-namespace-fn.md | 25 ++++++++++++++++++++++ docs/element/double-raf.md | 19 ++++++++++++++++ docs/element/get-all-parent-scroller.md | 23 ++++++++++++++++++++ docs/element/get-parent-scroller.md | 23 ++++++++++++++++++++ docs/element/get-rect.md | 23 ++++++++++++++++++++ docs/element/get-scroll-left.md | 23 ++++++++++++++++++++ docs/element/get-scroll-top.md | 23 ++++++++++++++++++++ docs/element/get-style.md | 23 ++++++++++++++++++++ docs/element/in-viewport.md | 23 ++++++++++++++++++++ docs/element/prevent-default.md | 23 ++++++++++++++++++++ docs/element/raf.md | 19 ++++++++++++++++ docs/element/request-animation-frame.md | 25 ++++++++++++++++++++++ docs/zh/element/cancel-animation-frame.md | 24 +++++++++++++++++++++ docs/zh/element/classes.md | 23 ++++++++++++++++++++ docs/zh/element/create-namespace-fn.md | 25 ++++++++++++++++++++++ docs/zh/element/double-raf.md | 19 ++++++++++++++++ docs/zh/element/get-all-parent-scroller.md | 23 ++++++++++++++++++++ docs/zh/element/get-parent-scroller.md | 23 ++++++++++++++++++++ docs/zh/element/get-rect.md | 23 ++++++++++++++++++++ docs/zh/element/get-scroll-left.md | 23 ++++++++++++++++++++ docs/zh/element/get-scroll-top.md | 23 ++++++++++++++++++++ docs/zh/element/get-style.md | 23 ++++++++++++++++++++ docs/zh/element/in-viewport.md | 23 ++++++++++++++++++++ docs/zh/element/prevent-default.md | 23 ++++++++++++++++++++ docs/zh/element/raf.md | 19 ++++++++++++++++ docs/zh/element/request-animation-frame.md | 25 ++++++++++++++++++++++ 31 files changed, 673 insertions(+), 1 deletion(-) create mode 100644 docs/.vitepress/items/element.ts create mode 100644 docs/element/cancel-animation-frame.md create mode 100644 docs/element/classes.md create mode 100644 docs/element/create-namespace-fn.md create mode 100644 docs/element/double-raf.md create mode 100644 docs/element/get-all-parent-scroller.md create mode 100644 docs/element/get-parent-scroller.md create mode 100644 docs/element/get-rect.md create mode 100644 docs/element/get-scroll-left.md create mode 100644 docs/element/get-scroll-top.md create mode 100644 docs/element/get-style.md create mode 100644 docs/element/in-viewport.md create mode 100644 docs/element/prevent-default.md create mode 100644 docs/element/raf.md create mode 100644 docs/element/request-animation-frame.md create mode 100644 docs/zh/element/cancel-animation-frame.md create mode 100644 docs/zh/element/classes.md create mode 100644 docs/zh/element/create-namespace-fn.md create mode 100644 docs/zh/element/double-raf.md create mode 100644 docs/zh/element/get-all-parent-scroller.md create mode 100644 docs/zh/element/get-parent-scroller.md create mode 100644 docs/zh/element/get-rect.md create mode 100644 docs/zh/element/get-scroll-left.md create mode 100644 docs/zh/element/get-scroll-top.md create mode 100644 docs/zh/element/get-style.md create mode 100644 docs/zh/element/in-viewport.md create mode 100644 docs/zh/element/prevent-default.md create mode 100644 docs/zh/element/raf.md create mode 100644 docs/zh/element/request-animation-frame.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index ec9d781..e86b4ab 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,5 +1,14 @@ import { defineConfig } from 'vitepress' -import { generalItems, numberItems, stringItems, arrayItems, functionItems, collectionItems, mathItems } from './items' +import { + generalItems, + numberItems, + stringItems, + arrayItems, + functionItems, + collectionItems, + mathItems, + elementItems, +} from './items' function withI18n(items: { link: string; text: string }[], locale: 'zh') { return items.map((item) => { @@ -59,6 +68,10 @@ export default defineConfig({ text: '函数', items: withI18n(functionItems, 'zh'), }, + { + text: '元素', + items: withI18n(elementItems, 'zh'), + }, ], docFooter: { @@ -113,6 +126,10 @@ export default defineConfig({ text: 'Function', items: functionItems, }, + { + text: 'Element', + items: elementItems, + }, ], socialLinks: [{ icon: 'github', link: 'https://github.com/varletjs/rattail' }], diff --git a/docs/.vitepress/items/element.ts b/docs/.vitepress/items/element.ts new file mode 100644 index 0000000..cfc6bb5 --- /dev/null +++ b/docs/.vitepress/items/element.ts @@ -0,0 +1,16 @@ +export const elementItems = [ + { text: 'requestAnimationFrame', link: '/element/request-animation-frame' }, + { text: 'cancelAnimationFrame', link: '/element/cancel-animation-frame' }, + { text: 'raf', link: '/element/raf' }, + { text: 'doubleRaf', link: '/element/double-raf' }, + { text: 'getStyle', link: '/element/get-style' }, + { text: 'getRect', link: '/element/get-rect' }, + { text: 'inViewport', link: '/element/in-viewport' }, + { text: 'getParentScroller', link: '/element/get-parent-scroller' }, + { text: 'getAllParentScroller', link: '/element/get-all-parent-scroller' }, + { text: 'preventDefault', link: '/element/prevent-default' }, + { text: 'getScrollTop', link: '/element/get-scroll-top' }, + { text: 'getScrollLeft', link: '/element/get-scroll-left' }, + { text: 'classes', link: '/element/classes' }, + { text: 'createNamespaceFn', link: '/element/create-namespace-fn' }, +] diff --git a/docs/.vitepress/items/index.ts b/docs/.vitepress/items/index.ts index 6dfbdf8..702ac4c 100644 --- a/docs/.vitepress/items/index.ts +++ b/docs/.vitepress/items/index.ts @@ -5,3 +5,4 @@ export * from './array' export * from './collection' export * from './function' export * from './math' +export * from './element' diff --git a/docs/element/cancel-animation-frame.md b/docs/element/cancel-animation-frame.md new file mode 100644 index 0000000..10fd178 --- /dev/null +++ b/docs/element/cancel-animation-frame.md @@ -0,0 +1,24 @@ +# cancelAnimationFrame + +Cancels a `requestAnimationFrame` request using the provided handle, with a fallback to `clearTimeout`. + +### Usage + +```ts +import { cancelAnimationFrame } from 'rattail' + +const handle = requestAnimationFrame(() => {}) +cancelAnimationFrame(handle) +``` + +### Arguments + +| Arg | Type | Defaults | +| -------- | -------- | -------- | +| `handle` | `number` | | + +### Return + +| Type | +| ------ | +| `void` | diff --git a/docs/element/classes.md b/docs/element/classes.md new file mode 100644 index 0000000..af23701 --- /dev/null +++ b/docs/element/classes.md @@ -0,0 +1,23 @@ +# classes + +Generates a list of class names based on a given condition or directly returns class names. + +### Usage + +```ts +import { classes } from 'rattail' + +const classList = classes('active', [true, 'visible', 'hidden']) +``` + +### Arguments + +| Arg | Type | Defaults | +| --------- | --------- | -------- | +| `classes` | `Classes` | | + +### Return + +| Type | +| ------- | +| `any[]` | diff --git a/docs/element/create-namespace-fn.md b/docs/element/create-namespace-fn.md new file mode 100644 index 0000000..83e6c40 --- /dev/null +++ b/docs/element/create-namespace-fn.md @@ -0,0 +1,25 @@ +# createNamespaceFn + +Creates a namespace function that allows BEM-style naming of components and classes. + +### Usage + +```ts +import { createNamespaceFn } from 'rattail' + +const ns = createNamespaceFn('my-app') +const bem = ns('button') +console.log(bem.n('--active')) +``` + +### Arguments + +| Arg | Type | Defaults | +| ----------- | -------- | -------- | +| `namespace` | `string` | | + +### Return + +| Type | +| -------------------------------------------------- | +| `{ name: string; n: Function; classes: Function }` | diff --git a/docs/element/double-raf.md b/docs/element/double-raf.md new file mode 100644 index 0000000..4efe73a --- /dev/null +++ b/docs/element/double-raf.md @@ -0,0 +1,19 @@ +# doubleRaf + +Creates a Promise-based double `requestAnimationFrame` that resolves after two frames. + +### Usage + +```ts +import { doubleRaf } from 'rattail' + +doubleRaf().then(() => { + console.log('Two frames later') +}) +``` + +### Return + +| Type | +| --------------- | +| `Promise` | diff --git a/docs/element/get-all-parent-scroller.md b/docs/element/get-all-parent-scroller.md new file mode 100644 index 0000000..fb3da90 --- /dev/null +++ b/docs/element/get-all-parent-scroller.md @@ -0,0 +1,23 @@ +# getAllParentScroller + +Retrieves all scrollable ancestor elements of an element in an array, including the `window` as the last item. + +### Usage + +```ts +import { getAllParentScroller } from 'rattail' + +const scrollers = getAllParentScroller(document.querySelector('div')) +``` + +### Arguments + +| Arg | Type | Defaults | +| ---- | ------------- | -------- | +| `el` | `HTMLElement` | | + +### Return + +| Type | +| ------------------------------ | +| `Array` | diff --git a/docs/element/get-parent-scroller.md b/docs/element/get-parent-scroller.md new file mode 100644 index 0000000..80665fa --- /dev/null +++ b/docs/element/get-parent-scroller.md @@ -0,0 +1,23 @@ +# getParentScroller + +Finds the closest scrollable ancestor of an element. If no scrollable ancestor is found, returns the `window`. + +### Usage + +```ts +import { getParentScroller } from 'rattail' + +const scroller = getParentScroller(document.querySelector('div')) +``` + +### Arguments + +| Arg | Type | Defaults | +| ---- | ------------- | -------- | +| `el` | `HTMLElement` | | + +### Return + +| Type | +| ----------------------- | +| `HTMLElement \| Window` | diff --git a/docs/element/get-rect.md b/docs/element/get-rect.md new file mode 100644 index 0000000..37a6bb3 --- /dev/null +++ b/docs/element/get-rect.md @@ -0,0 +1,23 @@ +# getRect + +Gets the dimensions and position of an element or window as a `DOMRect` object. + +### Usage + +```ts +import { getRect } from 'rattail' + +const rect = getRect(document.querySelector('div')) +``` + +### Arguments + +| Arg | Type | Defaults | +| --------- | --------- | -------- | +| `element` | `Element` | `Window` | + +### Return + +| Type | +| --------- | +| `DOMRect` | diff --git a/docs/element/get-scroll-left.md b/docs/element/get-scroll-left.md new file mode 100644 index 0000000..7c12be9 --- /dev/null +++ b/docs/element/get-scroll-left.md @@ -0,0 +1,23 @@ +# getScrollLeft + +Gets the horizontal scroll position of an element or window. + +### Usage + +```ts +import { getScrollLeft } from 'rattail' + +const scrollLeft = getScrollLeft(window) +``` + +### Arguments + +| Arg | Type | Defaults | +| --------- | ------------------- | -------- | +| `element` | `Element \| Window` | | + +### Return + +| Type | +| -------- | +| `number` | diff --git a/docs/element/get-scroll-top.md b/docs/element/get-scroll-top.md new file mode 100644 index 0000000..2f93e75 --- /dev/null +++ b/docs/element/get-scroll-top.md @@ -0,0 +1,23 @@ +# getScrollTop + +Gets the vertical scroll position of an element or window. + +### Usage + +```ts +import { getScrollTop } from 'rattail' + +const scrollTop = getScrollTop(window) +``` + +### Arguments + +| Arg | Type | Defaults | +| --------- | ------------------- | -------- | +| `element` | `Element \| Window` | | + +### Return + +| Type | +| -------- | +| `number` | diff --git a/docs/element/get-style.md b/docs/element/get-style.md new file mode 100644 index 0000000..3d90bd5 --- /dev/null +++ b/docs/element/get-style.md @@ -0,0 +1,23 @@ +# getStyle + +Retrieves computed CSS styles for a given DOM element. + +### Usage + +```ts +import { getStyle } from 'rattail' + +const elementStyle = getStyle(document.querySelector('div')) +``` + +### Arguments + +| Arg | Type | Defaults | +| --------- | --------- | -------- | +| `element` | `Element` | | + +### Return + +| Type | +| --------------------- | +| `CSSStyleDeclaration` | diff --git a/docs/element/in-viewport.md b/docs/element/in-viewport.md new file mode 100644 index 0000000..9add446 --- /dev/null +++ b/docs/element/in-viewport.md @@ -0,0 +1,23 @@ +# inViewport + +Determines if an element is visible within the viewport. + +### Usage + +```ts +import { inViewport } from 'rattail' + +const isVisible = inViewport(document.querySelector('div')) +``` + +### Arguments + +| Arg | Type | Defaults | +| --------- | ------------- | -------- | +| `element` | `HTMLElement` | | + +### Return + +| Type | +| --------- | +| `boolean` | diff --git a/docs/element/prevent-default.md b/docs/element/prevent-default.md new file mode 100644 index 0000000..586692c --- /dev/null +++ b/docs/element/prevent-default.md @@ -0,0 +1,23 @@ +# preventDefault + +Prevents the default action of an event if it is cancelable. + +### Usage + +```ts +import { preventDefault } from 'rattail' + +document.addEventListener('click', preventDefault) +``` + +### Arguments + +| Arg | Type | Defaults | +| ------- | ------- | -------- | +| `event` | `Event` | | + +### Return + +| Type | +| ------ | +| `void` | diff --git a/docs/element/raf.md b/docs/element/raf.md new file mode 100644 index 0000000..e65f012 --- /dev/null +++ b/docs/element/raf.md @@ -0,0 +1,19 @@ +# raf + +Creates a Promise-based `requestAnimationFrame` that resolves on the next frame. + +### Usage + +```ts +import { raf } from 'rattail' + +raf().then(() => { + console.log('Next animation frame') +}) +``` + +### Return + +| Type | +| --------------- | +| `Promise` | diff --git a/docs/element/request-animation-frame.md b/docs/element/request-animation-frame.md new file mode 100644 index 0000000..835f761 --- /dev/null +++ b/docs/element/request-animation-frame.md @@ -0,0 +1,25 @@ +# requestAnimationFrame + +Provides a cross-browser compatible `requestAnimationFrame` function, with a fallback to `setTimeout`. + +### Usage + +```ts +import { requestAnimationFrame } from 'rattail' + +requestAnimationFrame(() => { + console.log('Frame requested') +}) +``` + +### Arguments + +| Arg | Type | Defaults | +| ---- | ---------------------- | -------- | +| `fn` | `FrameRequestCallback` | | + +### Return + +| Type | +| -------- | +| `number` | diff --git a/docs/zh/element/cancel-animation-frame.md b/docs/zh/element/cancel-animation-frame.md new file mode 100644 index 0000000..51c860b --- /dev/null +++ b/docs/zh/element/cancel-animation-frame.md @@ -0,0 +1,24 @@ +# cancelAnimationFrame + +使用给定的句柄取消 `requestAnimationFrame` 请求，并使用 `clearTimeout` 作为回退选项。 + +### 用法 + +```ts +import { cancelAnimationFrame } from 'rattail' + +const handle = requestAnimationFrame(() => {}) +cancelAnimationFrame(handle) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| -------- | -------- | ------ | +| `handle` | `number` | | + +### 返回值 + +| 类型 | +| ------ | +| `void` | diff --git a/docs/zh/element/classes.md b/docs/zh/element/classes.md new file mode 100644 index 0000000..14a6e66 --- /dev/null +++ b/docs/zh/element/classes.md @@ -0,0 +1,23 @@ +# classes + +根据给定条件生成类名列表，或直接返回类名。 + +### 用法 + +```ts +import { classes } from 'rattail' + +const classList = classes('active', [true, 'visible', 'hidden']) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| --------- | --------- | ------ | +| `classes` | `Classes` | | + +### 返回值 + +| 类型 | +| ------- | +| `any[]` | diff --git a/docs/zh/element/create-namespace-fn.md b/docs/zh/element/create-namespace-fn.md new file mode 100644 index 0000000..5750ee0 --- /dev/null +++ b/docs/zh/element/create-namespace-fn.md @@ -0,0 +1,25 @@ +# createNamespaceFn + +创建一个命名空间函数，用于生成 BEM 样式的组件和类名。 + +### 用法 + +```ts +import { createNamespaceFn } from 'rattail' + +const ns = createNamespaceFn('my-app') +const bem = ns('button') +console.log(bem.n('--active')) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| ----------- | -------- | ------ | +| `namespace` | `string` | | + +### 返回值 + +| 类型 | +| -------------------------------------------------- | +| `{ name: string; n: Function; classes: Function }` | diff --git a/docs/zh/element/double-raf.md b/docs/zh/element/double-raf.md new file mode 100644 index 0000000..4c93216 --- /dev/null +++ b/docs/zh/element/double-raf.md @@ -0,0 +1,19 @@ +# doubleRaf + +创建一个基于 `Promise` 的双重 `requestAnimationFrame`，在两帧之后解析。 + +### 用法 + +```ts +import { doubleRaf } from 'rattail' + +doubleRaf().then(() => { + console.log('两帧后') +}) +``` + +### 返回值 + +| 类型 | +| --------------- | +| `Promise` | diff --git a/docs/zh/element/get-all-parent-scroller.md b/docs/zh/element/get-all-parent-scroller.md new file mode 100644 index 0000000..1a4bf7b --- /dev/null +++ b/docs/zh/element/get-all-parent-scroller.md @@ -0,0 +1,23 @@ +# getAllParentScroller + +获取元素的所有可滚动父级元素，包含 `window` 作为最后一项。 + +### 用法 + +```ts +import { getAllParentScroller } from 'rattail' + +const scrollers = getAllParentScroller(document.querySelector('div')) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| ---- | ------------- | ------ | +| `el` | `HTMLElement` | | + +### 返回值 + +| 类型 | +| ------------------------------ | +| `Array` | diff --git a/docs/zh/element/get-parent-scroller.md b/docs/zh/element/get-parent-scroller.md new file mode 100644 index 0000000..59d50c3 --- /dev/null +++ b/docs/zh/element/get-parent-scroller.md @@ -0,0 +1,23 @@ +# getParentScroller + +查找元素的最近可滚动父级元素。如果没有找到滚动父级，则返回 `window`。 + +### 用法 + +```ts +import { getParentScroller } from 'rattail' + +const scroller = getParentScroller(document.querySelector('div')) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| ---- | ------------- | ------ | +| `el` | `HTMLElement` | | + +### 返回值 + +| 类型 | +| ----------------------- | +| `HTMLElement \| Window` | diff --git a/docs/zh/element/get-rect.md b/docs/zh/element/get-rect.md new file mode 100644 index 0000000..2a2669c --- /dev/null +++ b/docs/zh/element/get-rect.md @@ -0,0 +1,23 @@ +# getRect + +获取元素或窗口的尺寸和位置，返回一个 `DOMRect` 对象。 + +### 用法 + +```ts +import { getRect } from 'rattail' + +const rect = getRect(document.querySelector('div')) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| --------- | --------- | -------- | +| `element` | `Element` | `Window` | + +### 返回值 + +| 类型 | +| --------- | +| `DOMRect` | diff --git a/docs/zh/element/get-scroll-left.md b/docs/zh/element/get-scroll-left.md new file mode 100644 index 0000000..e97a30a --- /dev/null +++ b/docs/zh/element/get-scroll-left.md @@ -0,0 +1,23 @@ +# getScrollLeft + +获取元素或窗口的水平滚动位置。 + +### 用法 + +```ts +import { getScrollLeft } from 'rattail' + +const scrollLeft = getScrollLeft(window) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| --------- | ------------------- | ------ | +| `element` | `Element \| Window` | | + +### 返回值 + +| 类型 | +| -------- | +| `number` | diff --git a/docs/zh/element/get-scroll-top.md b/docs/zh/element/get-scroll-top.md new file mode 100644 index 0000000..6ee3e52 --- /dev/null +++ b/docs/zh/element/get-scroll-top.md @@ -0,0 +1,23 @@ +# getScrollTop + +获取元素或窗口的垂直滚动位置。 + +### 用法 + +```ts +import { getScrollTop } from 'rattail' + +const scrollTop = getScrollTop(window) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| --------- | ------------------- | ------ | +| `element` | `Element \| Window` | | + +### 返回值 + +| 类型 | +| -------- | +| `number` | diff --git a/docs/zh/element/get-style.md b/docs/zh/element/get-style.md new file mode 100644 index 0000000..3d04f47 --- /dev/null +++ b/docs/zh/element/get-style.md @@ -0,0 +1,23 @@ +# getStyle + +获取给定 DOM 元素的计算 CSS 样式。 + +### 用法 + +```ts +import { getStyle } from 'rattail' + +const elementStyle = getStyle(document.querySelector('div')) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| --------- | --------- | ------ | +| `element` | `Element` | | + +### 返回值 + +| 类型 | +| --------------------- | +| `CSSStyleDeclaration` | diff --git a/docs/zh/element/in-viewport.md b/docs/zh/element/in-viewport.md new file mode 100644 index 0000000..75cf5e1 --- /dev/null +++ b/docs/zh/element/in-viewport.md @@ -0,0 +1,23 @@ +# inViewport + +判断元素是否在视口内可见。 + +### 用法 + +```ts +import { inViewport } from 'rattail' + +const isVisible = inViewport(document.querySelector('div')) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| --------- | ------------- | ------ | +| `element` | `HTMLElement` | | + +### 返回值 + +| 类型 | +| --------- | +| `boolean` | diff --git a/docs/zh/element/prevent-default.md b/docs/zh/element/prevent-default.md new file mode 100644 index 0000000..0541517 --- /dev/null +++ b/docs/zh/element/prevent-default.md @@ -0,0 +1,23 @@ +# preventDefault + +阻止事件的默认行为（如果该事件可取消）。 + +### 用法 + +```ts +import { preventDefault } from 'rattail' + +document.addEventListener('click', preventDefault) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| ------- | ------- | ------ | +| `event` | `Event` | | + +### 返回值 + +| 类型 | +| ------ | +| `void` | diff --git a/docs/zh/element/raf.md b/docs/zh/element/raf.md new file mode 100644 index 0000000..a7016eb --- /dev/null +++ b/docs/zh/element/raf.md @@ -0,0 +1,19 @@ +# raf + +创建一个基于 `Promise` 的 `requestAnimationFrame`，在下一帧时解析。 + +### 用法 + +```ts +import { raf } from 'rattail' + +raf().then(() => { + console.log('下一帧动画') +}) +``` + +### 返回值 + +| 类型 | +| --------------- | +| `Promise` | diff --git a/docs/zh/element/request-animation-frame.md b/docs/zh/element/request-animation-frame.md new file mode 100644 index 0000000..c551e6f --- /dev/null +++ b/docs/zh/element/request-animation-frame.md @@ -0,0 +1,25 @@ +# requestAnimationFrame + +提供跨浏览器兼容的 `requestAnimationFrame` 函数，并使用 `setTimeout` 作为回退选项。 + +### 用法 + +```ts +import { requestAnimationFrame } from 'rattail' + +requestAnimationFrame(() => { + console.log('请求了一帧') +}) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| ---- | ------------- | ------ | +| `el` | `HTMLElement` | | + +### 返回值 + +| 类型 | +| ------------------------------ | +| `Array` | From 4e654dc640eb0192a80645811d7cf40ecfe65362 Mon Sep 17 00:00:00 2001 From: Aybrea Date: Fri, 1 Nov 2024 21:00:19 +0800 Subject: [PATCH 2/2] docs: add file docs --- docs/.vitepress/config.ts | 9 +++++++++ docs/.vitepress/items/file.ts | 5 +++++ docs/.vitepress/items/index.ts | 1 + docs/file/to-array-buffer.md | 26 ++++++++++++++++++++++++++ docs/file/to-data-url.md | 26 ++++++++++++++++++++++++++ docs/file/to-text.md | 26 ++++++++++++++++++++++++++ docs/zh/file/to-array-buffer.md | 26 ++++++++++++++++++++++++++ docs/zh/file/to-data-url.md | 26 ++++++++++++++++++++++++++ docs/zh/file/to-text.md | 26 ++++++++++++++++++++++++++ 9 files changed, 171 insertions(+) create mode 100644 docs/.vitepress/items/file.ts create mode 100644 docs/file/to-array-buffer.md create mode 100644 docs/file/to-data-url.md create mode 100644 docs/file/to-text.md create mode 100644 docs/zh/file/to-array-buffer.md create mode 100644 docs/zh/file/to-data-url.md create mode 100644 docs/zh/file/to-text.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index e86b4ab..dff0a85 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -8,6 +8,7 @@ import { collectionItems, mathItems, elementItems, + fileItems, } from './items' function withI18n(items: { link: string; text: string }[], locale: 'zh') { @@ -72,6 +73,10 @@ export default defineConfig({ text: '元素', items: withI18n(elementItems, 'zh'), }, + { + text: '文件', + items: withI18n(fileItems, 'zh'), + }, ], docFooter: { @@ -130,6 +135,10 @@ export default defineConfig({ text: 'Element', items: elementItems, }, + { + text: 'File', + items: fileItems, + }, ], socialLinks: [{ icon: 'github', link: 'https://github.com/varletjs/rattail' }], diff --git a/docs/.vitepress/items/file.ts b/docs/.vitepress/items/file.ts new file mode 100644 index 0000000..e0f043d --- /dev/null +++ b/docs/.vitepress/items/file.ts @@ -0,0 +1,5 @@ +export const fileItems = [ + { text: 'toDataURL', link: '/file/to-data-url' }, + { text: 'toText', link: '/file/to-text' }, + { text: 'toArrayBuffer', link: '/file/to-array-buffer' }, +] diff --git a/docs/.vitepress/items/index.ts b/docs/.vitepress/items/index.ts index 702ac4c..02268e5 100644 --- a/docs/.vitepress/items/index.ts +++ b/docs/.vitepress/items/index.ts @@ -6,3 +6,4 @@ export * from './collection' export * from './function' export * from './math' export * from './element' +export * from './file' diff --git a/docs/file/to-array-buffer.md b/docs/file/to-array-buffer.md new file mode 100644 index 0000000..5dc723c --- /dev/null +++ b/docs/file/to-array-buffer.md @@ -0,0 +1,26 @@ +# toArrayBuffer + +Converts a `File` object to an `ArrayBuffer`. + +### Usage + +```ts +import { toArrayBuffer } from 'rattail' + +const file = new File(['Hello, world!'], 'hello.txt', { type: 'text/plain' }) +toArrayBuffer(file).then((arrayBuffer) => { + console.log(arrayBuffer) +}) +``` + +### Arguments + +| Arg | Type | Defaults | +| ------ | ------ | -------- | +| `file` | `File` | | + +### Return + +| Type | +| ---------------------- | +| `Promise` | diff --git a/docs/file/to-data-url.md b/docs/file/to-data-url.md new file mode 100644 index 0000000..04219f6 --- /dev/null +++ b/docs/file/to-data-url.md @@ -0,0 +1,26 @@ +# toDataURL + +Converts a `File` object to a Data URL string. + +### Usage + +```ts +import { toDataURL } from 'rattail' + +const file = new File(['Hello, world!'], 'hello.txt', { type: 'text/plain' }) +toDataURL(file).then((dataUrl) => { + console.log(dataUrl) +}) +``` + +### Arguments + +| Arg | Type | Defaults | +| ------ | ------ | -------- | +| `file` | `File` | | + +### Return + +| Type | +| ----------------- | +| `Promise` | diff --git a/docs/file/to-text.md b/docs/file/to-text.md new file mode 100644 index 0000000..3ea7943 --- /dev/null +++ b/docs/file/to-text.md @@ -0,0 +1,26 @@ +# toText + +Converts a `File` object to a text string. + +### Usage + +```ts +import { toText } from 'rattail' + +const file = new File(['Hello, world!'], 'hello.txt', { type: 'text/plain' }) +toText(file).then((text) => { + console.log(text) +}) +``` + +### Arguments + +| Arg | Type | Defaults | +| ------ | ------ | -------- | +| `file` | `File` | | + +### Return + +| Type | +| ----------------- | +| `Promise` | diff --git a/docs/zh/file/to-array-buffer.md b/docs/zh/file/to-array-buffer.md new file mode 100644 index 0000000..849edad --- /dev/null +++ b/docs/zh/file/to-array-buffer.md @@ -0,0 +1,26 @@ +# toArrayBuffer + +将 `File` 对象转换为 `ArrayBuffer`。 + +### 用法 + +```ts +import { toArrayBuffer } from 'rattail' + +const file = new File(['Hello, world!'], 'hello.txt', { type: 'text/plain' }) +toArrayBuffer(file).then((arrayBuffer) => { + console.log(arrayBuffer) +}) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| ------ | ------ | ------ | +| `file` | `File` | | + +### 返回值 + +| 类型 | +| ---------------------- | +| `Promise` | diff --git a/docs/zh/file/to-data-url.md b/docs/zh/file/to-data-url.md new file mode 100644 index 0000000..c9ac4b9 --- /dev/null +++ b/docs/zh/file/to-data-url.md @@ -0,0 +1,26 @@ +# toDataURL + +将 `File` 对象转换为 Data URL 字符串。 + +### 用法 + +```ts +import { toDataURL } from 'rattail' + +const file = new File(['Hello, world!'], 'hello.txt', { type: 'text/plain' }) +toDataURL(file).then((dataUrl) => { + console.log(dataUrl) +}) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| ------ | ------ | ------ | +| `file` | `File` | | + +### 返回值 + +| 类型 | +| ----------------- | +| `Promise` | diff --git a/docs/zh/file/to-text.md b/docs/zh/file/to-text.md new file mode 100644 index 0000000..18db8eb --- /dev/null +++ b/docs/zh/file/to-text.md @@ -0,0 +1,26 @@ +# toText + +将 `File` 对象转换为文本字符串。 + +### 用法 + +```ts +import { toText } from 'rattail' + +const file = new File(['Hello, world!'], 'hello.txt', { type: 'text/plain' }) +toText(file).then((text) => { + console.log(text) +}) +``` + +### 参数 + +| 参数 | 类型 | 默认值 | +| ------ | ------ | ------ | +| `file` | `File` | | + +### 返回值 + +| 类型 | +| ----------------- | +| `Promise` |