## 1. Project Overview & Quickstart (pure-admin/vue-pure-admin)

## File: src/utils/README.md

### 注意

- `vue-pure-admin` 从 `3.3.0` 版本之后（不包括 `3.3.0` 版本），大部分工具和 `hooks` 都集成到了 [@pureadmin/utils](https://pure-admin-utils.netlify.app/)
- [npm](https://www.npmjs.com/package/@pureadmin/utils)
- [文档代码地址](https://github.com/pure-admin/pure-admin-utils-docs)

---

## File: src/views/system/menu/README.md

## 字段含义

| 字段              | 说明                                                         |
| :---------------- | :----------------------------------------------------------- |
| `menuType`        | 菜单类型（`0`代表菜单、`1`代表`iframe`、`2`代表外链、`3`代表按钮） |
| `parentId`        |                                                              |
| `title`           | 菜单名称（兼容国际化、非国际化，如果用国际化的写法就必须在根目录的`locales`文件夹下对应添加） |
| `name`            | 路由名称（必须唯一并且和当前路由`component`字段对应的页面里用`defineOptions`包起来的`name`保持一致） |
| `path`            | 路由路径                                                     |
| `component`       | 组件路径（传`component`组件路径，那么`path`可以随便写，如果不传，`component`组件路径会跟`path`保持一致） |
| `rank`            | 菜单排序（平台规定只有`home`路由的`rank`才能为`0`，所以后端在返回`rank`的时候需要从非`0`开始 [点击查看更多](https://pure-admin.cn/pages/routerMenu/#%E8%8F%9C%E5%8D%95%E6%8E%92%E5%BA%8F-rank)） |
| `redirect`        | 路由重定向                                                   |
| `icon`            | 菜单图标                                                     |
| `extraIcon`       | 右侧图标                                                     |
| `enterTransition` | 进场动画（页面加载动画）                                     |
| `leaveTransition` | 离场动画（页面加载动画）                                     |
| `activePath`      | 菜单激活（将某个菜单激活，主要用于通过`query`或`params`传参的路由，当它们通过配置`showLink: false`后不在菜单中显示，就不会有任何菜单高亮，而通过设置`activePath`指定激活菜单即可获得高亮，`activePath`为指定激活菜单的`path`） |
| `auths`           | 权限标识（按钮级别权限设置）                                 |
| `frameSrc`        | 链接地址（需要内嵌的`iframe`链接地址）                       |
| `frameLoading`    | 加载动画（内嵌的`iframe`页面是否开启首次加载动画）           |
| `keepAlive`       | 缓存页面（是否缓存该路由页面，开启后会保存该页面的整体状态，刷新后会清空状态） |
| `hiddenTag`       | 标签页（当前菜单名称或自定义信息禁止添加到标签页）           |
| `fixedTag`        | 固定标签页（当前菜单名称是否固定显示在标签页且不可关闭）           |
| `showLink`        | 菜单（是否显示该菜单）                                       |
| `showParent`      | 父级菜单（是否显示父级菜单 [点击查看更多](https://pure-admin.cn/pages/routerMenu/#%E7%AC%AC%E4%B8%80%E7%A7%8D-%E8%AF%A5%E6%A8%A1%E5%BC%8F%E9%92%88%E5%AF%B9%E7%88%B6%E7%BA%A7%E8%8F%9C%E5%8D%95%E4%B8%8B%E5%8F%AA%E6%9C%89%E4%B8%80%E4%B8%AA%E5%AD%90%E8%8F%9C%E5%8D%95%E7%9A%84%E6%83%85%E5%86%B5-%E5%9C%A8%E5%AD%90%E8%8F%9C%E5%8D%95%E7%9A%84-meta-%E5%B1%9E%E6%80%A7%E4%B8%AD%E5%8A%A0%E4%B8%8A-showparent-true-%E5%8D%B3%E5%8F%AF)） |

---

## File: README.en-US.md

<h1>vue-pure-admin</h1>





**English** | [中文](./README.md)

## Introduction

`vue-pure-admin` is an open source, free and out-of-the-box middle and backend management system template. Completely adopts `ECMAScript` module (`ESM`) specifications to write and organize code, using the latest `Vue3`, `Vite`, `Element-Plus`, `TypeScript`, `Pinia`, `Tailwindcss` and other mainstream technologies develop

## R&D philosophy

Seek innovation in stability and see the future in technology

## Thin version (offering non-internationalized and internationalized versions)

The simplified version is based on the shelf extracted from [vue-pure-admin](https://github.com/pure-admin/vue-pure-admin), which contains main functions and is more suitable for actual project development. The packaged size is introduced globally [element-plus](https://element-plus.org) is still below `2.3MB`, and the full version of the code will be permanently synchronized. After enabling `brotli` compression and `cdn` to replace the local library mode, the package size is less than `350kb`

[Click to view the non-internationalized version](https://github.com/pure-admin/pure-admin-thin)  
[Click to view Internationalization version](https://github.com/pure-admin/pure-admin-thin/tree/i18n)

## Supporting video

[Click me to view UI design](https://www.bilibili.com/video/BV17g411T7rq)  
[Click me to view the rapid development tutorial](https://www.bilibili.com/video/BV1kg411v7QT)

## Nanny-level documents

[Click me to view vue-pure-admin documentation](https://pure-admin.cn/)  
[Click me to view @pureadmin/utils documentation](https://pure-admin-utils.netlify.app)

## Premium service

[Click me for details](https://pure-admin.cn/pages/service/)

## Tauri

[Click Watch Tauri](https://github.com/pure-admin/tauri-pure-admin)

## Electron

[Click Watch Electron](https://github.com/pure-admin/electron-pure-admin)

## Preview

[preview station](https://pure-admin.github.io/vue-pure-admin)

`PC`



`DarkMode`



`Mobile`



### Use Gitpod

Open the project in Gitpod (free online dev environment for GitHub) and start coding immediately.

[](https://gitpod.io/#https://github.com/pure-admin/vue-pure-admin)

## Install And Use

### Pull code

#### It is recommended to use `@pureadmin/cli` scaffolding




1. Global installation

```bash
npm install -g @pureadmin/cli
```

2. Interactively select templates and create projects

```bash
pure create
```

[Click to view the detailed usage of @pureadmin/cli scaffolding](https://github.com/pure-admin/pure-admin-cli#pureadmincli)

#### Pull from `GitHub`

```bash
git clone https://github.com/pure-admin/vue-pure-admin.git
```

#### Pulled from `Gitee`

```bash
git clone https://gitee.com/yiming_chang/vue-pure-admin.git
```

### Install dependencies

```bash
cd vue-pure-admin

pnpm install
```

### Run platform

```bash
pnpm dev
```

### Project packaging

```bash
pnpm build
```

## Docker support

1. Customize the image named `vue-pure-admin` (please note that there is a dot `.` at the end of the command below, indicating that the `Dockerfile` file in the current path is used, and the path can be specified according to the actual situation)

```bash
docker build -t vue-pure-admin .
```

2. Port mapping and start the `docker` container (`8080:80`: indicates that the `80` port is used in the container, and the port is forwarded to the `8080` port of the host; `pure-admin`: indicates a custom container name; `vue-pure-admin`: indicates the custom image name)

```bash
docker run -dp 8080:80  --name pure-admin vue-pure-admin
```

After operating the above two commands, open `http://localhost:8080` in the browser to preview

Of course, you can also operate the `docker` project through the [Docker Desktop](https://www.docker.com/products/docker-desktop/) visual interface, as shown below



## Change Log

[CHANGELOG](./CHANGELOG.en_US.md)

## How to contribute

You are very welcome to join！[Raise an issue](https://github.com/pure-admin/vue-pure-admin/issues/new/choose) Or submit a Pull Request

**Pull Request:**

1. Fork code!
2. Create your own branch: `git checkout -b feat/xxxx`
3. Submit your changes: `git commit -am 'feat(function): add xxxxx'`
4. Push your branch: `git push origin feat/xxxx`
5. submit`pull request`

## Special code contributions

Thank you very much for your in-depth understanding of the source code and your outstanding contributions to the `pure-admin` organization ❤️

|                 **Contributor**                 |                                 **SpecificCode**                                 |
| :---------------------------------------------: | :------------------------------------------------------------------------------: |
|       [hb0730](https://github.com/hb0730)       |    [code](https://github.com/pure-admin/vue-pure-admin/commits?author=hb0730)    |
|         [o-cc](https://github.com/o-cc)         |     [code](https://github.com/pure-admin/vue-pure-admin/commits?author=o-cc)     |
| [yj-liuzepeng](https://github.com/yj-liuzepeng) | [code](https://github.com/pure-admin/vue-pure-admin/commits?author=yj-liuzepeng) |
|   [skyline523](https://github.com/skyline523)   |  [code](https://github.com/pure-admin/vue-pure-admin/commits?author=skyline523)  |
| [shark-lajiao](https://github.com/shark-lajiao) | [code](https://github.com/pure-admin/vue-pure-admin/commits?author=shark-lajiao) |
|      [WitMiao](https://github.com/WitMiao)      |   [code](https://github.com/pure-admin/vue-pure-admin/commits?author=WitMiao)    |
|     [QFifteen](https://github.com/QFifteen)     |   [code](https://github.com/pure-admin/vue-pure-admin/commits?author=QFifteen)   |
|      [edgexie](https://github.com/edgexie)      |   [code](https://github.com/pure-admin/vue-pure-admin/commits?author=edgexie)    |
|       [way-jm](https://github.com/way-jm)       |    [code](https://github.com/pure-admin/vue-pure-admin/commits?author=way-jm)    |
|   [simple-hui](https://github.com/simple-hui)   |  [code](https://github.com/pure-admin/vue-pure-admin/commits?author=simple-hui)  |
|   [tinysimple](https://github.com/tinysimple)   |  [code](https://github.com/pure-admin/vue-pure-admin/commits?author=tinysimple)  |

## Git Contribution submission specification

reference [vue](https://github.com/vuejs/vue/blob/dev/.github/COMMIT_CONVENTION.md) specification ([Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular))

- `feat` Add new features
- `fix` Fix the problem/BUG
- `style` The code style is related and does not affect the running result
- `perf` Optimization/performance improvement
- `refactor` Refactor
- `revert` Undo edit
- `test` Test related
- `docs` Documentation/notes
- `chore` Dependency update/scaffolding configuration modification etc.
- `workflow` Workflow improvements
- `ci` Continuous integration
- `types` Type definition file changes
- `wip` In development

## Browser support

It is recommended to use `Chrome`, `Edge`, and `Firefox` browsers for local development. The author commonly uses the latest version of `Chrome` browser.  
In actual use, I feel that `Firefox` is smoother in animation than other browsers, but the author is used to using `Chrome`. It depends on personal preference.  
For more detailed browser compatibility support, please see [Which browsers does Vue support? ](https://vuejs.org/about/faq.html#what-browsers-does-vue-support) and [Vite browser compatibility](https://vitejs.dev/guide/build.html#browser-compatibility)

| [](http://godban.github.io/browsers-support-badges/)IE | [](http://godban.github.io/browsers-support-badges/)Edge | [](http://godban.github.io/browsers-support-badges/)Firefox | [](http://godban.github.io/browsers-support-badges/)Chrome | [](http://godban.github.io/browsers-support-badges/)Safari |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                                                             not support                                                                                              |                                                                                            last 2 versions                                                                                             |                                                                                                  last 2 versions                                                                                                  |                                                                                                last 2 versions                                                                                                |                                                                                                last 2 versions                                                                                                |

## Maintainer

[xiaoxian521](https://github.com/xiaoxian521)、[Ten-K](https://github.com/Ten-K)

## License

Completely free and open source

[MIT © 2020-present, pure-admin](./LICENSE)

## `Star`

Many thanks to the kind individuals who leave a star. Your support is much appreciated :heart:

[](https://github.com/pure-admin/vue-pure-admin/stargazers)

## `Fork`

It's so cool that you study hard :heart:

[](https://github.com/pure-admin/vue-pure-admin/network/members)

## 2. Official Technical Reference & Guides (pure-admin/pure-admin-utils-docs)

## File: docs/guide/guide.md

### 📦 安装

::: code-group

```bash [pnpm]
pnpm add @pureadmin/utils
```

```bash [yarn]
yarn add @pureadmin/utils
```

```bash [npm]
npm install @pureadmin/utils
```

:::

### 📡 `CDN`

::: code-group

```html [jsdelivr]
<!-- 提供包含所有方法的全局变量 PureUtils -->
<script src="//cdn.jsdelivr.net/npm/@pureadmin/utils"></script>
```

```html [unpkg]
<!-- 提供包含所有方法的全局变量 PureUtils -->
<script src="//unpkg.com/@pureadmin/utils"></script>
```

:::

### 📚 示例

集成 `vue-vite`、`vue-cli`、`preact`、`react`、`solid`、`svelte`、`nuxt3`、`next`、`node`、`html` 使用示例

[查看示例代码](https://github.com/pure-admin/pure-admin-utils-docs/tree/master/playgrounds)

我们为`nuxt3`提供了所有`hooks`示例  
[代码仓库](https://github.com/pure-admin/pure-admin-utils-nuxt3) [在线预览](https://pure-admin.github.io/pure-admin-utils-nuxt3/)

### 🤔 常见问题、反馈

问题：如果自己项目中的函数与 `@pureadmin/utils` 内部的函数名称冲突怎么办？  
答：这种问题很常见，可以使用 `ES6` 提供的 `as` 关键字来为导入的函数重命名，如下：

```ts
import { cloneDeep as _cloneDeep } from "@pureadmin/utils";
_cloneDeep();
```

[反馈问题、新增需求](https://github.com/pure-admin/pure-admin-utils-docs/issues/new)

### 🔔 温馨提示

本站大部分图片使用`Github`静态资源。如遇加载空白或加载图片失败时，刷新几次即可

---

## File: docs/hooks/useWatermark/useWatermark.md

<script setup>
import { 
  Wwhole, 
  Wpart,
  Wwrap,
  Wimage,
  Wforever
} from './demo/index.ts'
</script>

# useWatermark

::: tip 适用于 `Vue3`、`Nuxt3`、`HTML`
给元素加水印，自适应容器
:::

### 示例

#### 整页水印

<Wwhole />



查看代码

<<< @/hooks/useWatermark/demo/whole.vue



#### 局部水印

不论整页水印还是局部水印，它们都拥有上面类型声明中的 [attr](useWatermark#类型声明) 水印样式属性。

<Wpart />



查看代码

<<< @/hooks/useWatermark/demo/part.vue



#### 多行水印

某程序员：好家伙，当水印中包含额外的信息，如版权声明、公司名称、日期、时间戳或其他标识时，这不就信手拈来了嘛 🤏  
多行水印：虽然我提供额外的信息和保护，但注意不要过度使用哦，以免干扰到主要内容，降低了可读性，影响到用户体验 🥺

<Wwrap />



查看代码

<<< @/hooks/useWatermark/demo/wrap.vue



#### 图片水印

图片水印：文字水印还是太单一了，瞧我不轻松拿捏你 😝  
文字水印：啊，对对对。尽管你花里胡哨，加载失败时，不还是得靠我 😎

<Wimage />



查看代码

<<< @/hooks/useWatermark/demo/image.vue



#### 永久水印

通过浏览器提供的 [MutationObserver](https://developer.mozilla.org/zh-CN/docs/Web/API/MutationObserver) 实现无法删除的永久水印。当然也不是绝对无法删除，但是能很大程度防止删除。如果想要删除，只能通过特殊的禁用`JavaScript`等方法来实现。

<Wforever />



查看代码

<<< @/hooks/useWatermark/demo/forever.vue



### 最简代码

添加水印

```vue
<script setup lang="ts">
import { useWatermark } from "@pureadmin/utils";
const { setWatermark } = useWatermark();
setWatermark("我是水印");
</script>
```

### API

#### 参数

```ts
//  在此处配置参数
const {} = useWatermark(appendEl, resizeReDraw);
```



| **参数属性**   | 必传 | **说明**                                                                   | **类型**           |
| -------------- | ---- | -------------------------------------------------------------------------- | ------------------ |
| `appendEl`     | 否   | 要添加水印的主体，默认`body`                                               | `Ref<HTMLElement>` |
| `resizeReDraw` | 否   | 当浏览器窗口的尺寸发生改变时，是否重新绘制水印，默认 `false`（不重新绘制） | `boolean`          |



#### 返回值、方法



| **返回值、方法** | **说明**                                                                     | **类型**                                           |
| ---------------- | ---------------------------------------------------------------------------- | -------------------------------------------------- |
| `setWatermark`   | 根据自定义配置项添加水印，具体看下面的 [详解](useWatermark#setwatermark详解) | `(str: string, attr?: attr ｜ undefined) => void ` |
| `clear`          | 销毁水印                                                                     | `() => void`                                       |

##### `setWatermark`详解

它接收两个参数，如下

| **参数** | **说明**                                                     | **类型** |
| -------- | ------------------------------------------------------------ | -------- |
| `str`    | 水印值                                                       | `string` |
| `attr`   | 水印样式属性，具体看下面的 [类型声明](useWatermark#类型声明) | `attr`   |



#### 类型声明

<<< @/hooks/useWatermark/types/useWatermark.ts

<style scoped>
.pure-no-border > table > thead > tr > th:nth-child(2) {
  min-width: 60px;
}
</style>

---

## File: docs/hooks/useScrollTo/useScrollTo.md

<script setup>
import verticalScrollTo from './verticalScrollTo.vue'
import horizontalScrollTo from './horizontalScrollTo.vue'
</script>

# useScrollTo

::: tip 适用于 `Vue3`、`Nuxt3`、`HTML`
使元素可自定义缓动
:::

### 示例

#### 纵向缓动

<verticalScrollTo />



查看代码

<<< @/hooks/useScrollTo/verticalScrollTo.vue



#### 横向缓动

<horizontalScrollTo />



查看代码

<<< @/hooks/useScrollTo/horizontalScrollTo.vue



### 最简代码

整页滚动到顶部

```vue
<script setup lang="ts">
import { useScrollTo } from "@pureadmin/utils";

const onPageTop = () => {
  useScrollTo({
    el: document.documentElement,
    to: 0,
    directions: "scrollTop"
  }).start();
};
</script>

<template>
  <button @click="onPageTop">整页滚动到顶部</button>
</template>
```

### API

#### 参数

```ts
//  在此处配置参数
const {} = useScrollTo(options);
```



| **参数属性** | 必传 | **说明**                                                                                                                        | **类型**                     |
| ------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `el`         | 是   | 滚动对象的实例                                                                                                                  | `Ref<Element>`/`HTMLElement` |
| `to`         | 是   | 滚动到某个位置                                                                                                                  | `number`                     |
| `directions` | 是   | 滚动方向                                                                                                                        | `scrollTop`/`scrollLeft`     |
| `duration`   | 否   | 滚动时长，单位毫秒。默认`0`，没有缓动效果                                                                                       | `number`                     |
| `callback`   | 否   | 滚动完毕的回调，返回一个参数`msg`。`msg`等于`滚动完毕`，代表滚动完成；`msg`等于`无需滚动`，代表当前已处于滚动目标位置，无需滚动 | `(msg?:string) => void`      |



#### 返回值、方法



| **返回值、方法** | **说明** | **类型**     |
| ---------------- | -------- | ------------ |
| `start`          | 开始滚动 | `() => void` |
| `stop`           | 暂停滚动 | `() => void` |



<style scoped>
.pure-no-border > table > thead > tr > th:nth-child(2) {
  min-width: 60px;
}
</style>

---

## File: docs/hooks/useResizeObserver/useResizeObserver.md

<script setup>
import demo1 from "./demo1.vue"
import demo2 from "./demo2.vue"
</script>

# useResizeObserver

::: tip 适用于 `Vue3`、`Nuxt3`、`HTML`
监听元素尺寸的变化，内置自定义防抖时长，支持`ID`和类选择器
:::

### 示例

#### 固定宽高

拖拽下面`textarea`的右下角，观察容器变化

<demo1 />



查看代码

<<< @/hooks/useResizeObserver/demo1.vue



#### 非固定宽高

拖拽整个页面直到容器尺寸变化

<demo2 />



查看代码

<<< @/hooks/useResizeObserver/demo2.vue



### 最简代码

监听容器尺寸变化

```vue
<script setup lang="ts">
import { useResizeObserver } from "@pureadmin/utils";
useResizeObserver(".content", () => {
  // 容器尺寸变化回调
});
</script>

<template>
  <div class="content" />
</template>
```

### API

#### 参数

```ts
//  在此处配置参数
const {} = useResizeObserver(target, callback, options);
```



拥有三个参数，详情如下：

| **属性**   | 必传 | **说明**                                                                                                                                            | **类型**                                                                           |
| ---------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `target`   | 是   | 监听哪个容器元素，可以是类名（`'.class'`）、`ID`（`'.id'`），也可以是 [ref](https://cn.vuejs.org/guide/essentials/template-refs.html#template-refs) | `string`、`ElementRef<HTMLDivElement>`、`string[]`、`ElementRef<HTMLDivElement>[]` |
| `callback` | 是   | 容器尺寸变化后的回调函数，返回一个`entries`数组对象，对象为监听容器元素的宽高等属性值                                                               | `ResizeObserverCallback`                                                           |
| `options`  | 否   | 额外参数对象，具体看下面的 [`options`详情](useResizeObserver#options详情)                                                                           | `UseResizeObserverOptions`                                                         |

##### `options`详情

| **属性**    | **说明**                                                                                                                                                                                                                | **类型**  | 默认值        |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------- |
| `time`      | 防抖延迟时间，单位：毫秒                                                                                                                                                                                                | `number`  | `40`          |
| `immediate` | 初始化时是否立刻触发回调                                                                                                                                                                                                | `boolean` | `true`        |
| `box`       | 拥有三个可选项。`content-box`（默认）指的是元素的内容区域尺寸，不包括边框和内边距；`border-box`指的是元素的边框盒尺寸，包括内容、内边距和边框，但不包括外边距；`device-pixel-content-box`指的是设备像素级别观察尺寸变化 | `string`  | `content-box` |



#### 返回值、方法



| **返回值、方法** | **说明**                                   | **类型**     |
| ---------------- | ------------------------------------------ | ------------ |
| `stop`           | 停止监听                                   | `() => void` |
| `restart`        | 重新启用监听，常用于停止监听后重新启用监听 | `() => void` |



#### 类型声明

<<< @/hooks/useResizeObserver/types/useResizeObserver.ts

<style scoped>
#VPContent > div > div > div.content > div > main > div > div > div:nth-child(18) > table:nth-child(2) > thead > tr > th:nth-child(2) {
  min-width: 60px;
}
#VPContent > div > div > div.content > div > main > div > div > div:nth-child(18) > table:nth-child(4) > thead > tr > th:nth-child(4) {
  min-width: 130px;
}
</style>

---

## File: docs/hooks/useLoader/useLoader.md

# useLoader

::: tip 适用于 `Vue3`、`Nuxt3`、`HTML`
动态地将静态资源（`CSS`样式表或`JavaScript`脚本）加载到网页中
:::

### 示例

```vue
<script setup lang="ts">
import { onMounted } from "vue";
import { useLoader } from "@pureadmin/utils";

const { loadCss, loadScript } = useLoader();

/** --------------- loadCss --------------- */

/** 动态加载单个link标签 */
loadCss({
  src: "https://cdn.bootcdn.net/ajax/libs/animate.css/4.1.1/animate.min.css"
})
  .then(() => {
    // 加载成功要做的事
  })
  .catch(err => {
    // 加载失败要做的事
  });

/** 动态加载多个link标签（会按照传入src的先后顺序加载） */
loadCss({
  src: [
    "https://cdn.bootcdn.net/ajax/libs/hover.css/2.3.1/css/hover-min.css",
    "https://cdn.bootcdn.net/ajax/libs/animate.css/4.1.1/animate.min.css",
    "https://cdn.bootcdn.net/ajax/libs/hint.css/2.7.0/hint.min.css"
  ]
})
  .then(() => {
    // 加载成功要做的事
  })
  .catch(err => {
    // 加载失败要做的事
  });

/** 不同link标签可插入相同元素中 */
loadCss({
  src: [
    "https://cdn.bootcdn.net/ajax/libs/hover.css/2.3.1/css/hover-min.css",
    "https://cdn.bootcdn.net/ajax/libs/animate.css/4.1.1/animate.min.css",
    "https://cdn.bootcdn.net/ajax/libs/hint.css/2.7.0/hint.min.css"
  ],
  element: "head" // "body"
})
  .then(() => {
    // 加载成功要做的事
  })
  .catch(err => {
    // 加载失败要做的事
  });

/** 不同link标签可插入不同元素中 */
loadCss([
  {
    src: "https://cdn.bootcdn.net/ajax/libs/hover.css/2.3.1/css/hover-min.css",
    element: "head"
  },
  {
    src: "https://cdn.bootcdn.net/ajax/libs/animate.css/4.1.1/animate.min.css",
    element: "head"
  },
  {
    src: "https://cdn.bootcdn.net/ajax/libs/hint.css/2.7.0/hint.min.css",
    element: "body"
  }
])
  .then(() => {
    // 加载成功要做的事
  })
  .catch(err => {
    // 加载失败要做的事
  });

/** --------------- loadScript --------------- */

/** 动态加载单个script标签 */
loadScript({
  src: "https://cdn.bootcdn.net/ajax/libs/dayjs/1.11.9/dayjs.min.js"
})
  .then(() => {
    // 加载成功要做的事
  })
  .catch(err => {
    // 加载失败要做的事
  });

/** 动态加载多个script标签（会按照传入src的先后顺序加载） */
loadScript({
  src: [
    "https://cdn.bootcdn.net/ajax/libs/dayjs/1.11.9/dayjs.min.js",
    "https://cdn.bootcdn.net/ajax/libs/echarts/5.4.3/echarts.min.js"
  ]
})
  .then(() => {
    // 加载成功要做的事
  })
  .catch(err => {
    // 加载失败要做的事
  });

/** 不同script标签可插入相同元素中 */
loadScript({
  src: [
    "https://cdn.bootcdn.net/ajax/libs/dayjs/1.11.9/dayjs.min.js",
    "https://cdn.bootcdn.net/ajax/libs/echarts/5.4.3/echarts.min.js"
  ],
  element: "body" // "head"
})
  .then(() => {
    // 加载成功要做的事
  })
  .catch(err => {
    // 加载失败要做的事
  });

/** 不同script标签可插入不同元素中 */
loadScript([
  {
    src: "https://cdn.bootcdn.net/ajax/libs/dayjs/1.11.9/dayjs.min.js",
    element: "head"
  },
  {
    src: "https://cdn.bootcdn.net/ajax/libs/echarts/5.4.3/echarts.min.js",
    element: "body"
  }
])
  .then(() => {
    // 加载成功要做的事
  })
  .catch(err => {
    // 加载失败要做的事
  });

/** --------------- loadCss、loadScript 结合使用 --------------- */
loadCss({
  src: "https://cdn.bootcdn.net/ajax/libs/animate.css/4.1.1/animate.min.css"
})
  .then(() => {
    loadScript({
      src: "https://cdn.bootcdn.net/ajax/libs/dayjs/1.11.9/dayjs.min.js"
    })
      .then(() => {})
      .catch(err => {});
  })
  .catch(err => {});
</script>
```

### 最简代码

动态加载`CSS`样式表

```vue
<script setup lang="ts">
import { onMounted } from "vue";
import { useLoader } from "@pureadmin/utils";
const { loadCss } = useLoader();

onMounted(async () => {
  try {
    let result = await loadCss({
      src: "https://cdn.bootcdn.net/ajax/libs/animate.css/4.1.1/animate.min.css"
    });
    if (result) {
      // 加载成功要做的事
    }
  } catch (err) {
    // 加载失败要做的事
  }
});
</script>
```

### API

#### 参数

```ts
//  在此处配置参数
const {} = useLoader(destroy);
```



| **参数属性** | 必传 | **说明**                     | **类型**  | 默认值 |
| ------------ | ---- | ---------------------------- | --------- | ------ |
| `destroy`    | 否   | 是否在生命周期结束后移除标签 | `boolean` | `true` |



#### 返回值、方法



| **返回值、方法** | **说明**                 | **类型**                                                        |
| ---------------- | ------------------------ | --------------------------------------------------------------- |
| `loadCss`        | 动态加载`CSS`样式表      | `(opts: OptionsScript/OptionsScript[])=> Promise<LoadResult[]>` |
| `loadScript`     | 动态加载`JavaScript`脚本 | `(opts: OptionsScript/OptionsScript[])=> Promise<LoadResult[]>` |



#### 类型声明

<<< @/hooks/useLoader/types/useLoader.ts

### 温馨提示

::: info 注意点

1. `src`最好指定版本号，有以下几个好处：  
   ① 可预测性：通过指定确切版本号，可以确保所有用户都加载相同版本的脚本，这有助于避免因为库更新导致的问题  
   ② 缓存优势：浏览器通常会缓存静态资源，如`JavaScript`文件。如果指定了版本号，当更新脚本并更改版本号时，用户的浏览器会加载新版本的文件，而不是使用缓存中可能已经过时的版本  
   ③ 避免`Breaking Changes`：如果没有指定版本号，而是使用了某个库的最新版本（例如通过链接到一个总是指向最新版本的`URL`），那么当该库发布包含破坏性更改的新版本时，网站或应用可能会意外地崩溃

2. 加载`CSS`样式时，要检查是否有样式冲突，避免网站样式被破坏

3. `loadCss`、`loadScript`结合使用时，一般情况先使用`loadCss`加载`CSS`样式后再用`loadScript`加载`JavaScript`脚本，有以下几个好处：  
   ① 渲染性能：网页在加载时，用户首先看到的是页面的内容和布局，这主要由`CSS`控制。将`CSS`放在前面可以确保在文档内容加载时样式已经就绪，这样用户就不会看到无样式或半样式的内容。等到页面结构和样式都加载完毕后，再加载`JS`就不会影响到用户对页面的初始印象  
   ② 避免`FOUC（Flash of Unstyled Content）`：如果`JS`在`CSS`之前加载，可能会导致页面内容在脚本执行完成之前无样式或样式不完整的情况，这种现象称为"无样式内容的闪烁"（`FOUC`）。加载完`CSS`后再加载`JS`可以最大限度地降低`FOUC`情况  
   ③ `JavaScript`依赖于`DOM`和样式：许多`JavaScript`脚本依赖于完全构建的`DOM`树，以及适当应用的样式来执行操作，如获取元素尺寸或位置。确保`CSS`先加载并应用，`JS`脚本才能正确地工作  
   ④ 阻塞行为：传统上，浏览器在解析到`<script>`标签时会停止构建`DOM`，直至脚本执行完毕。如果脚本很大或者加载时间较长，这会导致页面渲染的延迟  
   ⑤ 优化用户体验：用户对网页加载速度的感知很大程度上取决于页面内容的可视化进度。`CSS`负责页面的视觉呈现，而`JavaScript`可能负责交互和行为。优先加载`CSS`确保了用户可以尽快看到完整的页面，而`JavaScript`的加载和执行则可以在其后进行，一般不会影响用户对页面的初步浏览

4. `loadCss`默认把`CSS`（`link`标签）插入到`head`，当然也可以通过设置`element: "body"`将其插入到`body`，默认插入`head`的好处：  
   ① 文档渲染性能：将`<link>`标签放在`<head>`中可以让浏览器尽早知道需要加载的`CSS`文件，从而在渲染页面时就能应用样式，避免出现样式闪烁（也称为`FOUC`，即无样式内容的闪烁）  
   ② `HTML`标准：根据`HTML`规范，某些类型的`<link>`（如指向样式表的链接）应该放在`<head>`中，这样做是为了遵循标准并确保最佳实践  
   ③ 优先级和资源加载：将`<link>`标签放在`<head>`中可以定义资源加载的优先级，确保关键的`CSS`在内容加载之前就被加载和解析，有助于提高页面的可视性能

5. `loadScript`默认把`JavaScript`（`script`标签）插入到`body`底部，当然也可以通过设置`element: "head"`将其插入到`head`，默认插入`body`底部的好处：  
   ① 减少阻塞：浏览器在解析`HTML`并构建`DOM`时，当遇到`<script>`标签会暂停解析，以便先加载并执行脚本。如果脚本位于`<head>`中，这会导致页面渲染的延迟。将脚本放在底部意味着页面的主要内容可以在脚本加载和执行前先被渲染，从而提升用户体验  
   ② 依赖`DOM`元素：许多脚本依赖于页面中的`DOM`元素。将脚本放在底部确保了当脚本执行时，它依赖的`DOM`元素已经存在  
   ③ 当然你可能会有疑问，为什么不使用`async`或`defer`属性并将`<script>`标签放在`<head>`中，这样也不会堵塞页面啊？答：是不会堵塞页面。但当使用`async`属性时脚本的执行顺序不能保证，当使用`defer`属性时脚本会在整个页面解析完成后才加载，所以默认将`<script>`标签放在``底部是一个更可靠的选择

:::

<style scoped>
#VPContent > div > div > div.content > div > main > div > div > div:nth-child(11) > table > thead > tr > th:nth-child(2) {
  min-width: 210px;
}
</style>

---

## File: docs/hooks/useGlobal/useGlobal.md

<script setup>
import demo from './demo.vue'
</script>

# useGlobal

::: tip 适用于 `Vue3`、`Nuxt3`、`HTML`
获取已经注册的全局属性对象 [globalProperties](https://cn.vuejs.org/api/application.html#app-config-globalproperties)
:::

`useGlobal`只做两件事，第一快速提取`globalProperties`，第二更方便、明确的类型提示

#### 既然想获取全局`globalProperties`，肯定要先注册它呀（第一步）

::: code-group

```ts [Vue3]
// main.ts
import { type App, createApp } from "vue";
import App from "./App.vue";

import * as echarts from "echarts";

const app = createApp(App);
// 这里我们就以注册$echarts为例
app.config.globalProperties.$echarts = echarts;

app.mount("#app");
```

```ts [Nuxt3]
// plugins/config.ts
import * as echarts from "echarts";

export default defineNuxtPlugin(nuxtApp => {
  // 这里我们就以注册$echarts为例
  nuxtApp.vueApp.config.globalProperties.$echarts = echarts;
});
```

:::

#### 全局类型声明（第二步）

<<< ../../global.d.ts

#### 在组件中使用它（第三步即最后一步）

<<< @/hooks/useGlobal/demo.vue

##### 获得类型提示，如下图



##### 获得实例的属性和方法，如下图

---

## File: docs/hooks/useECharts/useECharts.md

<script setup>
// 偏业务示例
import { 
  Eloading,
  Edynamic,
  Erequest,
  EcustomTheme
} from './demo/business/index.ts'

// 常用示例
import { 
  Eline, 
  Ebar, 
  Epie, 
  Escatter, 
  Ecandlestick, 
  Eradar, 
  Eboxplot, 
  Eheatmap, 
  Egraph, 
  Etree, 
  Esunburst,
  Esankey,
  Efunnel,
  Egauge,
  EpictorialBar,
  EthemeRiver
} from './demo/simple/index.ts'

// 高级示例
import { 
  Edemo1,
  Edemo2, 
  Edemo3, 
  Edemo4,
  Edemo5,
  Edemo6
} from './demo/advanced/index.ts'
</script>

# useECharts

::: tip 适用于 `Vue3`、`Nuxt3`、`HTML`
兼容 `echarts` 所有 `api` 并且额外添加尺寸自适应容器和自动销毁等功能，`echarts` 能实现的它都行
:::

### 使用前提

如下所示，必须先将 `echarts` 绑定到 [globalProperties](https://cn.vuejs.org/api/application.html#app-config-globalproperties)  
下面代码全局引入了 `echarts` 也可参考 [按需引入](https://echarts.apache.org/handbook/zh/basics/import#%E5%9C%A8-typescript-%E4%B8%AD%E6%8C%89%E9%9C%80%E5%BC%95%E5%85%A5)

::: code-group

```ts [Vue3]
// main.ts // [!code focus]
import { type App, createApp } from "vue";
import App from "./App.vue";

import * as echarts from "echarts"; // [!code focus]

const app = createApp(App);
// 这里$echarts写法自由，起名a、b、c都行，只要保证等号右侧引入的是echarts即可 // [!code focus]
app.config.globalProperties.$echarts = echarts; // [!code focus]

app.mount("#app");
```

```ts [Nuxt3]
// plugins/config.ts
import * as echarts from "echarts";

export default defineNuxtPlugin(nuxtApp => {
  // 这里$echarts写法自由，起名a、b、c都行，只要保证等号右侧引入的是echarts即可
  nuxtApp.vueApp.config.globalProperties.$echarts = echarts;
});
```

:::

### 最简代码

渲染`echarts`

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useECharts } from "@pureadmin/utils";

// 初始化ECharts
const chartRef = ref();
const { setOptions } = useECharts(chartRef);

// 根据配置项渲染ECharts
setOptions({
  /** 配置项 https://echarts.apache.org/zh/option.html */
});
</script>

<template>
  <div ref="chartRef" style="width: 100%; height: 35vh" />
</template>
```

### 偏业务示例

#### 加载动画

<visual-load>
<Eloading />



查看代码

<<< @/hooks/useECharts/demo/business/loading.vue


</visual-load>

#### 动态图表

<visual-load>
<Edynamic />



查看代码

<<< @/hooks/useECharts/demo/business/dynamic.vue


</visual-load>

#### 接口请求和图表下钻

<visual-load>

<ClientOnly>
  <Erequest />
</ClientOnly>



查看代码

<<< @/hooks/useECharts/demo/business/request.vue


  </visual-load>

#### 自定义主题

<visual-load>

在 [theme-builder](https://echarts.apache.org/zh/theme-builder.html) 配置好主题后，点击其网站左上角的下载主题，选择`JSON`版本，复制到本地的自定义主题`json`文件即可，如下图



<EcustomTheme />



查看代码

<<< @/hooks/useECharts/demo/business/customTheme.vue


</visual-load>

### 常用示例

#### 折线图 line

<visual-load>
<Eline />



查看代码

<<< @/hooks/useECharts/demo/simple/line.vue


</visual-load>

#### 柱状图 bar

<visual-load>
<Ebar />



查看代码

<<< @/hooks/useECharts/demo/simple/bar.vue


</visual-load>

#### 饼图 pie

<visual-load>
<Epie />



查看代码

<<< @/hooks/useECharts/demo/simple/pie.vue


</visual-load>

#### 散点图 scatter

<visual-load>
<Escatter />



查看代码

<<< @/hooks/useECharts/demo/simple/scatter.vue


</visual-load>

#### K 线图 candlestick

<visual-load>
<Ecandlestick />



查看代码

<<< @/hooks/useECharts/demo/simple/candlestick.vue


</visual-load>

#### 雷达图 radar

<visual-load>
<Eradar />



查看代码

<<< @/hooks/useECharts/demo/simple/radar.vue


</visual-load>

#### 盒须图 boxplot

<visual-load>
<Eboxplot />



查看代码

<<< @/hooks/useECharts/demo/simple/boxplot.vue


</visual-load>

#### 热力图 heatmap

<visual-load>
<Eheatmap />



查看代码

<<< @/hooks/useECharts/demo/simple/heatmap.vue


</visual-load>

#### 关系图 graph

<visual-load>
<Egraph />



查看代码

<<< @/hooks/useECharts/demo/simple/graph.vue


</visual-load>

#### 树图 tree

<visual-load>
<Etree />



查看代码

<<< @/hooks/useECharts/demo/simple/tree.vue


</visual-load>

#### 旭日图 sunburst

<visual-load>
<Esunburst />



查看代码

<<< @/hooks/useECharts/demo/simple/sunburst.vue


</visual-load>

#### 桑基图 sankey

<visual-load>
<Esankey />



查看代码

<<< @/hooks/useECharts/demo/simple/sankey.vue


</visual-load>

#### 漏斗图 funnel

<visual-load>
<Efunnel />



查看代码

<<< @/hooks/useECharts/demo/simple/funnel.vue


</visual-load>

#### 仪表盘 gauge

<visual-load>
<Egauge />



查看代码

<<< @/hooks/useECharts/demo/simple/gauge.vue


</visual-load>

#### 象形柱图 pictorialBar

<visual-load>
<EpictorialBar />



查看代码

<<< @/hooks/useECharts/demo/simple/pictorialBar.vue


</visual-load>

#### 主题河流图 themeRiver

<visual-load>
  <EthemeRiver />



查看代码

<<< @/hooks/useECharts/demo/simple/themeRiver.vue


</visual-load>

### 高级示例

在最右上角切换主题试试吧

#### demo1

<visual-load>
<ClientOnly>
  <Edemo1 />
</ClientOnly>



查看代码

<<< @/hooks/useECharts/demo/advanced/demo1.vue


</visual-load>

#### demo2

<visual-load>
<Edemo2 />



查看代码

<<< @/hooks/useECharts/demo/advanced/demo2.vue


</visual-load>

#### demo3

<visual-load>
<Edemo3 />



查看代码

<<< @/hooks/useECharts/demo/advanced/demo3.vue


</visual-load>

#### demo4

<visual-load>
<Edemo4 />



查看代码

<<< @/hooks/useECharts/demo/advanced/demo4.vue


</visual-load>

#### demo5

<visual-load>
<Edemo5 />



查看代码

<<< @/hooks/useECharts/demo/advanced/demo5.vue


</visual-load>

#### demo6

<visual-load>
<Edemo6 />



查看代码

<<< @/hooks/useECharts/demo/advanced/demo6.vue


</visual-load>

<visual-load>

::: info 平台维护组件推荐
在使用`ECharts`时，往往有地图需求，但`ECharts`在`V5`版本去除了内置的 [geoJSON](https://echarts.apache.org/handbook/zh/basics/release-note/v5-upgrade-guide/#%E5%8E%BB%E9%99%A4%E5%86%85%E7%BD%AE%E7%9A%84-geojson) ，这使得用户在`ECharts`的`v5`版本中使用地图时还需要自己找地图数据，为了解决这个问题 [@esmjs/geo](https://github.com/esmjs/geo) 诞生，它使用`rust`和`typescript`编写，简单易用
:::

::: info 更多`Demo`
就这点`demo`？好啦，别闹，这就把配方拿出来 [配方](https://www.isqqw.com/) （注册后登录，可免费查看全部图表代码，非广告，只是个人觉得不错，推荐给大家）
:::

</visual-load>

### API

#### 参数

拥有两个参数，它们对`echarts`的 [init](https://echarts.apache.org/zh/api.html#echarts.init) 进行了封装，与`init`唯一的区别是`useECharts`将`theme`属性放到下面的`options`参数里并且新增一个`tooltipId`属性

```ts
//  在此处配置参数
const {} = useECharts(elRef, options);
```



| **参数属性** | 必传 | **说明**                                                                                                 | **类型**              |
| ------------ | ---- | -------------------------------------------------------------------------------------------------------- | --------------------- |
| `elRef`      | 是   | [获取DOM元素或组件实例引用的ref](https://cn.vuejs.org/guide/essentials/template-refs.html#template-refs) | `Ref<HTMLDivElement>` |
| `options`    | 否   | 拥有`11`个属性，具体看下面的 `options` 详情                                                              | `EchartOptions`       |

##### `options` 详情

| **参数属性**       | **说明**                                                                                                                                                                                                                                                                                                                                     | **类型**                                    | **默认值**                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------- |
| `theme`            | [主题色](https://echarts.apache.org/handbook/zh/concepts/style#%E9%A2%9C%E8%89%B2%E4%B8%BB%E9%A2%98%EF%BC%88theme%EF%BC%89)，可选`default`、`light`、`dark`，也可以[自定义主题](https://echarts.apache.org/zh/theme-builder.html)                                                                                                            | `Theme`、`Ref`、`ComputedRef` | `default`                 |
| `tooltipId`        | 给`x`、`y`轴添加`Tooltip`文字提示的元素`id`                                                                                                                                                                                                                                                                                                  | `string`                                    | `tooltipElement`          |
| `devicePixelRatio` | 设备像素比，取自浏览器                                                                                                                                                                                                                                                                                                                       | `number`                                    | `window.devicePixelRatio` |
| `renderer`         | 渲染模式，支持`canvas`或者`svg`。注意：如果是 [按需引入echarts](https://echarts.apache.org/handbook/zh/basics/import/#%E5%9C%A8-typescript-%E4%B8%AD%E6%8C%89%E9%9C%80%E5%BC%95%E5%85%A5) ，就要根据需求先引入`CanvasRenderer`或`SVGRenderer`，具体参考后面括号里的代码（`import { CanvasRenderer, SVGRenderer } from "echarts/renderers"`） | `string`                                    | `canvas`                  |
| `ssr`              | 是否使用服务端渲染，只有在`SVG`渲染模式有效。开启后不再会每帧自动渲染，必须要调用 [renderToSVGString](https://echarts.apache.org/zh/api.html#echartsInstance.renderToSVGString) 方法才能得到渲染后`SVG`字符串                                                                                                                                | `boolean`                                   |                           |
| `useDirtyRect`     | 是否开启脏矩形渲染，只有在`Canvas`渲染模式有效                                                                                                                                                                                                                                                                                               | `boolean`                                   | `false`                   |
| `useCoarsePointer` | 是否扩大可点击元素的响应范围。`null`表示对移动设备开启；`true`表示总是开启；`false`表示总是不开启                                                                                                                                                                                                                                            | `boolean`                                   |                           |
| `pointerSize`      | 扩大元素响应范围的像素大小，配合`opts.useCoarsePointer`使用                                                                                                                                                                                                                                                                                  | `number`                                    |                           |
| `width`            | 可显式指定实例宽度，单位为像素。如果传入值为`null/undefined/'auto'`，则表示自动取`dom`（实例容器）的宽度                                                                                                                                                                                                                                     | `number`、`string`                          |                           |
| `height`           | 可显式指定实例高度，单位为像素。如果传入值为`null/undefined/'auto'`，则表示自动取`dom`（实例容器）的高度                                                                                                                                                                                                                                     | `number`、`string`                          |                           |
| `locale`           | 使用的语言，内置`ZH`和`EN`两个语言，也可以使用 [echarts.registerLocale](https://echarts.apache.org/zh/api.html#echarts.registerLocale) 方法注册新的语言包。目前支持的语言见 [src/i18n](https://github.com/apache/echarts/tree/release/src/i18n)                                                                                              | `string`                                    |                           |



#### 返回值、方法



| **返回值、方法**      | **说明**                                                                                                                                                                           | **类型**                                                             |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `echarts`             | 返回的`echarts`，功能同 [echarts](https://echarts.apache.org/zh/api.html#echarts)                                                                                                  | `ECharts`                                                            |
| `setOptions`          | 根据配置项渲染`ECharts`，功能同 [setOption](https://echarts.apache.org/zh/option.html)                                                                                             | ` (options: UtilsEChartsOption, ...params: OptionsParams[]) => void` |
| `getInstance`         | 获取通过 [echarts.init](https://echarts.apache.org/zh/api.html#echarts.init) 创建的实例，功能同 [echartsInstance](https://echarts.apache.org/zh/api.html#echartsInstance)          | `ECharts`                                                            |
| `showLoading`         | 显示加载动画                                                                                                                                                                       | `(params: LoadOpts) => void`                                         |
| `hideLoading`         | 隐藏加载动画                                                                                                                                                                       | `() => void`                                                         |
| `clear`               | 清空当前`ECharts`实例，会移除实例中所有的组件和图表                                                                                                                                | `() => void`                                                         |
| `resize`              | 改变`ECharts`图表尺寸，使其自适应容器                                                                                                                                              | `() => void`                                                         |
| `getGlobalProperties` | 获取绑定到`echarts`的 [globalProperties](https://cn.vuejs.org/api/application.html#app-config-globalproperties)                                                                    | `() => EchartGlobalProperties`                                       |
| `getDom`              | 获取`ECharts`实例容器的`Dom`节点                                                                                                                                                   | `() => HTMLCanvasElement `                                           |
| `getWidth`            | 获取`ECharts`实例容器的宽度                                                                                                                                                        | `() => number `                                                      |
| `getHeight`           | 获取`ECharts`实例容器的高度                                                                                                                                                        | `() => number `                                                      |
| `getOption`           | 获取当前`ECharts`实例中维护的`option`对象                                                                                                                                          | `() => EChartsCoreOption `                                           |
| `appendData`          | 此方法用于，在大数据量（百万以上）的渲染场景，分片加载数据和增量渲染                                                                                                               | `(opts: AppendDataOpts) => void `                                    |
| `getDataURL`          | 导出图表图片，返回一个`base64`的`URL`，可以设置为`Image`的`src`                                                                                                                    | `(opts: DataURL) => string `                                         |
| `getConnectedDataURL` | 导出联动的图表图片，返回一个`base64`的`url`，可以设置为`Image`的`src`。导出图片中每个图表的相对位置跟容器的相对位置有关                                                            | `(opts: DataURL) => string `                                         |
| `addTooltip`          | 给`x`、`y`轴添加`Tooltip`文字提示。`x`代表`x轴` `y`代表`y轴` `true`(默认)代表`x、y轴` （该属性生效的前提是将 `xAxis` 或者 `yAxis` 添加`triggerEvent: true`属性，用到哪个添加哪个） | `(type: ToolTipType) => void `                                       |

##### `setOptions`详解

`setOptions`非常重要，渲染图表都靠它。下面我们来详细了解一下吧 😜

它接收无限参数，最重要的是第一个参数，完全兼容`echarts`提供的 [setOption](https://echarts.apache.org/zh/option.html) 方法中所传参数，当然也完全兼容 [GL配置](https://echarts.apache.org/zh/option-gl.html#globe)。不仅完全兼容，我们还额外新增五个`api`，如下

| **api**      | **说明**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | **类型**                                     | **默认** |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | -------- |
| `clear`      | 是否清空当前实例，会移除实例中的图表，一般用于动态渲染                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `boolean`                                    | `true`   |
| `addTooltip` | 给`x`、`y`轴添加`Tooltip`文字提示，一般用于文字太长，`x`代表`x轴`， `y`代表`y轴` ， `true`代表`x、y轴`（该属性生效的前提是将 `xAxis` 或者 `yAxis` 添加`triggerEvent: true`属性，用到哪个添加哪个）                                                                                                                                                                                                                                                                                                                                                                 | `string`、`boolean`                          |          |
| `delay`      | 第一种含义（默认）：`window.onresize` 时改变图表尺寸的延时时间，单位毫秒，默认 `300` 毫秒。当 `echarts` 在拖拉窗口时不会自适应（一般不会出现这种情况），可以调整 `delay` 数值到自适应为止  第二种含义：如果设置了`container`，那么`delay`就代表指定容器元素尺寸变化的防抖时长，单位毫秒，默认`40`毫秒                                                                                                                                                                                                                                                         | `number`                                     | `300`    |
| `resize`     | 是否监听页面`resize`事件并在页面`resize`时改变图表尺寸以适应当前容器，监听及改变，`true`代表监听，`false`代表不监听                                                                                                                                                                                                                                                                                                                                                                                                                                                | `boolean`                                    | `true`   |
| `container`  | 监听指定容器元素尺寸的变化，从而实现图表尺寸自适应当前容器 `container`可以是类名（`'.class'`）也可以是`ID`（`'.id'`），内部用的是`document.querySelectorAll`。当然它也可以是 [ref](https://cn.vuejs.org/guide/essentials/template-refs.html#template-refs)  使用场景：常用于在容器宽高尺寸非固定值时，设置`container`实现图表尺寸自适应，毫不夸张的说，该属性支持任何情况下`echarts`图表自适应 注意：设置`container`后，`resize`属性就无效了。如果既想监听指定容器元素，又想监听`body`或更多元素，可以传字符串数组，如`['.class','#id','body',...]` | `string`、`Element`、`string[]`、`Element[]` |          |

上面说完第一个参数，那么剩余参数是干嘛的呢，请看下面的 [事件](useECharts#事件) 解析



#### 事件

所有 [events](https://echarts.apache.org/zh/api.html#events) 都在 `setOptions` 里配置

```ts
const { setOptions } = useECharts(elRef);

setOptions(
  {
    /** 配置项 https://echarts.apache.org/zh/option.html */
  },
  // 从第二个参数起，后面传入的剩余参数都为事件
  {
    // 点击触发
    name: "click",
    callback: params => {
      console.log("click", params);
    }
  },
  {
    // 右键触发
    name: "contextmenu",
    callback: params => {
      console.log("contextmenu", params);
    }
  },
  // 点击空白处触发
  {
    type: "zrender",
    name: "click",
    callback: params => {
      console.log("点击空白处", params);
    }
  },
  ...
);
```

##### 剩余事件参数属性



| **属性**   | 必传 | **说明**                                                                                                                                                                                  | **类型**           |
| ---------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `name`     | 是   | 事件类型名称，具体看下面的`事件类型`详情                                                                                                                                                  | `ElementEventName` |
| `callback` | 是   | 回调函数，返回 [params](https://echarts.apache.org/zh/api.html#events.%E9%BC%A0%E6%A0%87%E4%BA%8B%E4%BB%B6) 参数                                                                          | `Fn`               |
| `query`    | 否   | `query`属性，点击 [此处](https://echarts.apache.org/handbook/zh/concepts/event/#%E9%BC%A0%E6%A0%87%E4%BA%8B%E4%BB%B6%E7%9A%84%E5%A4%84%E7%90%86) 搜索`query`进行了解                      | `string`、`object` |
| `type`     | 否   | `echarts`事件（默认）或 [zrender](https://echarts.apache.org/handbook/zh/concepts/event/#%E7%9B%91%E5%90%AC%E2%80%9C%E7%A9%BA%E7%99%BD%E5%A4%84%E2%80%9D%E7%9A%84%E4%BA%8B%E4%BB%B6) 事件 | `ElementEventType` |

##### `事件类型`详情

下面列出常用事件类型，当然更具体的可以看 [events](https://echarts.apache.org/zh/api.html#events) 都支持

| **name**              | **说明**                                       |
| --------------------- | ---------------------------------------------- |
| `click`               | 当用户点击图表时触发                           |
| `dblclick`            | 当用户双击图表时触发                           |
| `mousewheel`          | 当用户使用鼠标滚轮时触发的事件                 |
| `mouseout`            | 当鼠标从图表上的某个数据项移开时触发           |
| `mouseover`           | 当鼠标移动到图表上的某个数据项时触发           |
| `mouseup`             | 当用户在图表上释放鼠标按钮时触发               |
| `mousedown`           | 当用户在图表上按下鼠标按钮时触发               |
| `mousemove`           | 当用户移动鼠标指针在元素上方时触发             |
| `contextmenu`         | 当用户在图表上点击鼠标右键打开上下文菜单时触发 |
| `globalout`           | 当鼠标从整个图表区域移出时触发                 |
| `selectchanged`       | 当图表中的数据项被选中或取消选中时触发         |
| `legendselectchanged` | 当图例的选中状态发生变化时触发                 |
| `rendered`            | 当图表渲染结束时触发                           |



#### 类型声明

<<< @/hooks/useECharts/types/useECharts.ts

---

## File: docs/hooks/useDraggable/useDraggable.md

<script setup>
import draggable from './draggable.vue'
import naiveuiBase from './naiveuiBase.vue'
import naiveuiDialog from './naiveuiDialog.vue'
</script>

# useDraggable

::: tip 适用于 `Vue3`、`Nuxt3`、`HTML`
使元素可拖动
:::

### 示例

#### 基础示例

<draggable class="mt-2" />



查看代码

<<< @/hooks/useDraggable/draggable.vue



#### 可拖动的 [naiveui模态框](https://www.naiveui.com/zh-CN/os-theme/components/modal)

##### 基础用法

<naiveuiBase class="mt-2" />



查看代码

<<< @/hooks/useDraggable/naiveuiBase.vue



##### 使用 Dialog 预设

哈哈，你没有看错，就是如此简单

<naiveuiDialog class="mt-2" />



查看代码

<<< @/hooks/useDraggable/naiveuiDialog.vue



### 最简代码

可拖动的`Div`

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useDraggable } from "@pureadmin/utils";

const targetRef = ref();
const dragRef = ref();

const { init } = useDraggable(targetRef, dragRef);
// 初始化开启拖动功能
init();
</script>

<template>
  <div ref="targetRef">
    <div ref="dragRef">
      <!-- 内容区 -->
    </div>
  </div>
</template>
```

### API

#### 参数

```ts
//  在此处配置参数
const {} = useDraggable(targetRef, dragRef, args);
```



| **参数属性** | 必传 | **说明**                                                                                                                                                                                          | **类型**                  |
| ------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `targetRef`  | 是   | 要拖动的元素。可以是[获取DOM元素或组件实例引用的ref](https://cn.vuejs.org/guide/essentials/template-refs.html#template-refs)，也可以是`class类名`（如：`".target"`）或`元素ID`（如：`"#target"`） | `Ref<HTMLElement>/string` |
| `dragRef`    | 是   | 拖动的地方。可以是[获取DOM元素或组件实例引用的ref](https://cn.vuejs.org/guide/essentials/template-refs.html#template-refs)，也可以是`class类名`（如：`".drag"`）或`元素ID`（如：`"#drag"`）       | `Ref<HTMLElement>/string` |
| `args`       | 否   | 额外的可选参数，具体看下面的`args`详情                                                                                                                                                            | `ArgsDraggable`           |

##### `args` 详情

对象格式，拥有下面两个属性

| **参数属性**   | **说明**                                                                                                                                                                                    | **类型**         | **默认值**                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| `dragRefStyle` | 为了方便用户识别可拖动的区域，添加额外样式到`dragRef`上。可以使用`{}`空对象清空默认样式，也可以自定义样式                                                                                   | `CSSProperties`  | `{ cursor: "move", userSelect: "none" }` |
| `resize`       | 当页面`resize`时，如果拖动的元素超出新的视口边界，是否将其恢复到初始位置。`true`：代表恢复到初始位置。`false`：代表不会恢复到初始位置。当然也可以填写`resize`时的防抖延迟时间，默认`60`毫秒 | `boolean/number` | `true`                                   |



#### 返回值、方法



| **返回值、方法** | **说明**                                                                            | **类型**                             |
| ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------ |
| `draggable`      | 是否已经开启拖动功能（响应式）。`true`代表已开启拖动功能，`false`代表关闭了拖动功能 | `Ref`                       |
| `dragging`       | 是否正在拖动中（响应式）。`true`代表正在拖动，`false`代表没有拖动                   | `Ref`                       |
| `transform`      | 响应式对象`transform`：包含当前被拖动元素的`offsetX`、`offsetY`信息                 | `{offsetX: number;offsetY: number;}` |
| `init`           | 初始化开启拖动功能                                                                  | `() => void`                         |
| `open`           | 开启拖动功能。常用于当关闭拖动时，想再次开启拖动并在当前所处位置继续拖动            | `() => void`                         |
| `close`          | 关闭拖动功能                                                                        | `() => void`                         |
| `reset`          | 将拖动元素恢复到初始位置                                                            | `() => void`                         |



<style scoped>
.pure-no-border > table > thead > tr > th:nth-child(2) {
  min-width: 60px;
}
.pure-no-border > table > thead > tr > th:nth-child(1) {
   min-width: 120px;
}
</style>

---

## File: docs/hooks/useDark/useDark.md

<script setup>
import dark from "./dark.vue"
import { onMounted, inject } from "vue"
import { useDark } from "@pureadmin/utils"

onMounted(() => {
  console.log(isDark.value ? "dark" : "light")
})
const { isDark } = useDark()
const toggle = inject("toggle-appearance", () => {
  isDark.value = !isDark.value
})
</script>

# useDark

::: tip 适用于 `Vue3`、`Nuxt3`、`HTML`
检测网页整体是否处于暗色（`dark`）主题，它是响应式的
:::

### 示例



<naive-theme>
  <n-button class="mt-2" @click="toggle">{{ `当前网页处于 ${isDark ? 'dark' : 'light'} 主题，点击切换主题` }}</n-button>
</naive-theme>



查看代码

<<< @/hooks/useDark/dark.vue



### 最简代码

检测当前整个网页是否处于`dark`主题

```vue
<script setup lang="ts">
import { useDark } from "@pureadmin/utils";
const { isDark } = useDark();
</script>
```

### API

#### 参数

```ts
//  在此处配置参数
const {} = useDark(options);
```



拥有一个参数`options`对象，详情如下：

| **属性**    | 必传 | **说明**                                           | **类型** |
| ----------- | ---- | -------------------------------------------------- | -------- |
| `selector`  | 否   | 自定义选择器，默认`html`，可选`body`               | `string` |
| `className` | 否   | 检测某个类名是否在`html`或`body`上存在，默认`dark` | `string` |



#### 返回值、方法



| **返回值、方法** | **说明**                             | **类型**              |
| ---------------- | ------------------------------------ | --------------------- |
| `isDark`         | 当前整个网页是否处于暗色(`dark`)主题 | `ShallowRef` |
| `toggleDark`     | `dark`和非`dark`主题间相互切换       | `() => void`          |

---

## File: docs/hooks/useCopyToClipboard/useCopyToClipboard.md

<script setup>
import inputCopy from './input.vue'
import codeCopy from './code.vue'
</script>

# useCopyToClipboard

::: tip 适用于 `Vue3`、`Nuxt3`、`HTML`
文本拷贝
:::

### 示例

#### 文本拷贝





查看代码

<<< @/hooks/useCopyToClipboard/input.vue



#### 代码片段拷贝

自动保留代码的空格、换行符和缩进

<codeCopy />



查看代码

<<< @/hooks/useCopyToClipboard/code.vue



### 最简代码

拷贝文本

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useCopyToClipboard } from "@pureadmin/utils";

let textValue = ref(""); // 要拷贝的文本值
const { copied, update } = useCopyToClipboard();

function copy() {
  update(textValue); // 更新要拷贝的文本值
  if (copied.value) {
    //  拷贝成功
  }
}
</script>

<template>
  <button @click="copy">拷贝</button>
</template>
```

### API

#### 参数

```ts
//  在此处配置参数
const {} = useCopyToClipboard(defaultValue);
```



| **参数属性**   | 必传 | **说明**                                     | **类型** |
| -------------- | ---- | -------------------------------------------- | -------- |
| `defaultValue` | 否   | 当要拷贝的文本值为空时，拷贝的值，默认不设置 | `string` |



#### 返回值、方法



| **返回值、方法** | **说明**                                              | **类型**                              |
| ---------------- | ----------------------------------------------------- | ------------------------------------- |
| `clipboardValue` | 拷贝后的文本值                                        | `ShallowRef<string>`                  |
| `copied`         | 是否拷贝成功。`true`代表拷贝成功，`false`代表拷贝失败 | `ShallowRef`                 |
| `update`         | 更新要拷贝的文本值                                    | `(value: string/Ref<string>) => void` |

---

## File: docs/utils/uuid/uuid.md

<script setup>
import { useAddNumInOutlineLabel } from '../../.vitepress/utils/createElement.ts'
useAddNumInOutlineLabel(4)

import buildUUID from './buildUUID.vue'
import buildGUID from './buildGUID.vue'
import buildPrefixUUID from './buildPrefixUUID.vue'
import uuid from './uuid.vue'
</script>

::: tip 支持任意 `JavaScript` 环境或框架
uuid
:::

## buildUUID

生成 `32` 位 `uuid`







查看代码

<<< @/utils/uuid/buildUUID.vue





## buildGUID

生成 `36` 位带横杠的 `GUID` 字符串（符合 `RFC 4122` 标准的 `UUID v4` 格式，以确保与 `C#` 和 `SQL Server` 的兼容性）







查看代码

<<< @/utils/uuid/buildGUID.vue





## buildPrefixUUID

生成自定义前缀的 `uuid`



####  {#base2}





查看代码

<<< @/utils/uuid/buildPrefixUUID.vue



####  {#param2}

接收一个参数 `prefix` ，返回值类型 `string`

| **参数属性** | **说明**   | **类型** |
| ------------ | ---------- | -------- |
| `prefix`     | 自定义前缀 | `string` |



## uuid

生成指定长度和基数的 `uuid`



####  {#base3}





查看代码

<<< @/utils/uuid/uuid.vue



####  {#param3}

接收三个参数，第一个参数 `len` ，第二个参数 `radix` ，第三个参数 `prefix` ，返回值类型 `string`

| **参数属性** | **说明**   | **类型** |
| ------------ | ---------- | -------- |
| `len`        | 指定长度   | `number` |
| `radix`      | 指定基数   | `number` |
| `prefix`     | 自定义前缀 | `string` |



::: info 提示信息

指定基数的母体为：`0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`，总长度 `62`

指定基数也就是规定要生成的 `uuid` 采用哪些字符组合，比如基数为 `10`，那么生成的 `uuid` 就会采用基数母体的前 `10` 位进行组合，也就是 `0123456789`
:::

---

## File: docs/utils/url/url.md

<script setup>
import { useAddNumInOutlineLabel } from '../../.vitepress/utils/createElement.ts'
useAddNumInOutlineLabel(2)

import getQueryMap from './getQueryMap.vue'
import getLocation from './getLocation.vue'
</script>

::: tip 支持任意运行在浏览器的 `JavaScript` 语言
提取 `url` 中所有参数、获取当前的 `location` 信息
:::

## getQueryMap

提取浏览器 `url` 中所有参数



####  {#base1}

<getQueryMap />



查看代码

<<< @/utils/url/getQueryMap.vue



####  {#param1}

接收一个参数 `url` ，返回值类型 `object`

| **参数属性** | **说明**   | **类型** |
| ------------ | ---------- | -------- |
| `url`        | 超链接地址 | `string` |



## getLocation

获取浏览器当前的 `location` 信息



<getLocation />



查看代码

<<< @/utils/url/getLocation.vue