pit-docs-mcp 1.0.2

package/docs/pitBusinessUtils/validate.md

@@ -0,0 +1,224 @@
+# validate — 基础验证函数
+
+提供常用的格式验证工具函数，以及适配 Element UI 表单校验规则的经纬度校验器。
+
+## 引用方式
+
+```js
+import {
+  isExternal, validURL, validEmail,
+  validLowerCase, validUpperCase, validAlphabets,
+  isString, isArray, islongitude, islatitude
+} from 'pit-business-utils'
+```
+
+---
+
+## 函数列表
+
+### `isExternal(path)`
+
+判断路径是否为外部链接（`http://`、`https://`、`mailto:`、`tel:` 开头）。常用于路由/菜单渲染时区分内部跳转和外部链接。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `path` | `string` | ✅ | 待判断的路径字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean`，是外部链接返回 `true` |
+
+```js
+isExternal('https://www.baidu.com')  // true
+isExternal('/dashboard')             // false
+isExternal('mailto:test@test.com')   // true
+```
+
+---
+
+### `validURL(url)`
+
+验证字符串是否为合法的 URL 格式，支持 `http`、`https`、`ftp` 协议，支持 IP 地址和带端口的 URL。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | `string` | ✅ | 待验证的 URL 字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean` |
+
+```js
+validURL('https://www.example.com')        // true
+validURL('http://192.168.1.1:8080/api')   // true
+validURL('not-a-url')                      // false
+```
+
+---
+
+### `validLowerCase(str)`
+
+验证字符串是否全为小写字母。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `str` | `string` | ✅ | 待验证字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean` |
+
+```js
+validLowerCase('hello')  // true
+validLowerCase('Hello')  // false
+```
+
+---
+
+### `validUpperCase(str)`
+
+验证字符串是否全为大写字母。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `str` | `string` | ✅ | 待验证字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean` |
+
+```js
+validUpperCase('HELLO')  // true
+validUpperCase('Hello')  // false
+```
+
+---
+
+### `validAlphabets(str)`
+
+验证字符串是否全为英文字母（大小写混合均可）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `str` | `string` | ✅ | 待验证字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean` |
+
+```js
+validAlphabets('HelloWorld') // true
+validAlphabets('hello123')   // false（含数字）
+```
+
+---
+
+### `validEmail(email)`
+
+验证字符串是否为合法的邮箱格式。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `email` | `string` | ✅ | 待验证的邮箱字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean` |
+
+```js
+validEmail('user@example.com')   // true
+validEmail('user@')              // false
+validEmail('not-an-email')       // false
+```
+
+---
+
+### `isString(str)`
+
+判断值是否为字符串类型（同时兼容 `new String()` 包装对象形式）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `str` | `any` | ✅ | 待判断的值 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean` |
+
+```js
+isString('hello')          // true
+isString(new String('hi')) // true
+isString(123)              // false
+```
+
+---
+
+### `isArray(arg)`
+
+判断值是否为数组（兼容低版本 JS 引擎，不依赖 `Array.isArray`）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `arg` | `any` | ✅ | 待判断的值 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean` |
+
+```js
+isArray([1, 2, 3]) // true
+isArray({})        // false
+isArray(null)      // false
+```
+
+---
+
+### `islongitude(rule, value, callback)`
+
+Element UI 表单校验器，验证经度值是否在 `-180` 到 `180` 范围内，空值直接通过（不触发报错）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `rule` | `Object` | ✅ | Element UI 校验规则对象（内置传入） |
+| `value` | `string \| number` | ✅ | 表单输入值 |
+| `callback` | `Function` | ✅ | Element UI 回调函数 |
+
+| — | — |
+|---|---|
+| **返回值** | `void`（通过调用 `callback` 返回结果） |
+
+```js
+// 在 el-form rules 中使用
+rules: {
+  longitude: [{ validator: islongitude, trigger: 'blur' }]
+}
+```
+
+---
+
+### `islatitude(rule, value, callback)`
+
+Element UI 表单校验器，验证纬度值是否在 `-90` 到 `90` 范围内，空值直接通过。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `rule` | `Object` | ✅ | Element UI 校验规则对象（内置传入） |
+| `value` | `string \| number` | ✅ | 表单输入值 |
+| `callback` | `Function` | ✅ | Element UI 回调函数 |
+
+| — | — |
+|---|---|
+| **返回值** | `void`（通过调用 `callback` 返回结果） |
+
+```js
+rules: {
+  latitude: [{ validator: islatitude, trigger: 'blur' }]
+}
+```
+
+---
+
+## 注意事项
+
+- `islongitude` 和 `islatitude` 设计为允许空值通过，若需要必填校验，应额外添加 `required: true` 规则。
+- `validEmail` 使用近似 RFC 5322 的正则规则，对极少数特殊合法邮箱格式可能误判，项目中一般场景可直接使用。

package/docs/pitElementUi/alert.md

@@ -0,0 +1,238 @@
+## Alert 警告
+
+用于页面中展示重要的提示信息。
+
+### 基本用法
+
+页面中的非浮层元素，不会自动消失。
+
+:::demo Alert 组件提供四种主题，由`type`属性指定，默认值为`info`。
+```html
+<template>
+  <el-alert
+    title="成功提示的文案"
+    type="success">
+  </el-alert>
+  <el-alert
+    title="消息提示的文案"
+    type="info">
+  </el-alert>
+  <el-alert
+    title="警告提示的文案"
+    type="warning">
+  </el-alert>
+  <el-alert
+    title="错误提示的文案"
+    type="error">
+  </el-alert>
+</template>
+```
+:::
+
+### 主题
+
+Alert 组件提供了两个不同的主题：`light`和`dark`。
+
+:::demo 通过设置`effect`属性来改变主题，默认为`light`。
+```html
+<template>
+  <el-alert
+    title="成功提示的文案"
+    type="success"
+    effect="dark">
+  </el-alert>
+  <el-alert
+    title="消息提示的文案"
+    type="info"
+    effect="dark">
+  </el-alert>
+  <el-alert
+    title="警告提示的文案"
+    type="warning"
+    effect="dark">
+  </el-alert>
+  <el-alert
+    title="错误提示的文案"
+    type="error"
+    effect="dark">
+  </el-alert>
+</template>
+```
+:::
+
+
+
+### 自定义关闭按钮
+
+自定义关闭按钮为文字或其他符号。
+
+:::demo 在 Alert 组件中，你可以设置是否可关闭，关闭按钮的文本以及关闭时的回调函数。`closable`属性决定是否可关闭，接受`boolean`，默认为`true`。你可以设置`close-text`属性来代替右侧的关闭图标，注意：`close-text`必须为文本。设置`close`事件来设置关闭时的回调。
+```html
+<template>
+  <el-alert
+    title="不可关闭的 alert"
+    type="success"
+    :closable="false">
+  </el-alert>
+  <el-alert
+    title="自定义 close-text"
+    type="info"
+    close-text="知道了">
+  </el-alert>
+  <el-alert
+    title="设置了回调的 alert"
+    type="warning"
+    @close="hello">
+  </el-alert>
+</template>
+
+<script>
+  export default {
+    methods: {
+      hello() {
+        alert('Hello World!');
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 带有 icon
+
+表示某种状态时提升可读性。
+
+:::demo 通过设置`show-icon`属性来显示 Alert 的 icon，这能更有效地向用户展示你的显示意图。
+```html
+<template>
+  <el-alert
+    title="成功提示的文案"
+    type="success"
+    show-icon>
+  </el-alert>
+  <el-alert
+    title="消息提示的文案"
+    type="info"
+    show-icon>
+  </el-alert>
+  <el-alert
+    title="警告提示的文案"
+    type="warning"
+    show-icon>
+  </el-alert>
+  <el-alert
+    title="错误提示的文案"
+    type="error"
+    show-icon>
+  </el-alert>
+</template>
+```
+:::
+
+### 文字居中
+
+使用 `center` 属性让文字水平居中。
+
+:::demo
+```html
+<template>
+  <el-alert
+    title="成功提示的文案"
+    type="success"
+    center
+    show-icon>
+  </el-alert>
+  <el-alert
+    title="消息提示的文案"
+    type="info"
+    center
+    show-icon>
+  </el-alert>
+  <el-alert
+    title="警告提示的文案"
+    type="warning"
+    center
+    show-icon>
+  </el-alert>
+  <el-alert
+    title="错误提示的文案"
+    type="error"
+    center
+    show-icon>
+  </el-alert>
+</template>
+```
+:::
+
+### 带有辅助性文字介绍
+
+包含标题和内容，解释更详细的警告。
+
+:::demo 除了必填的`title`属性外，你可以设置`description`属性来帮助你更好地介绍，我们称之为辅助性文字。辅助性文字只能存放单行文本，会自动换行显示。
+```html
+<template>
+  <el-alert
+    title="带辅助性文字介绍"
+    type="success"
+    description="这是一句绕口令：黑灰化肥会挥发发灰黑化肥挥发；灰黑化肥会挥发发黑灰化肥发挥。 黑灰化肥会挥发发灰黑化肥黑灰挥发化为灰……">
+  </el-alert>
+</template>
+```
+:::
+
+### 带有 icon 和辅助性文字介绍
+
+:::demo 最后，这是一个同时具有 icon 和辅助性文字的样例。
+```html
+<template>
+  <el-alert
+    title="成功提示的文案"
+    type="success"
+    description="文字说明文字说明文字说明文字说明文字说明文字说明"
+    show-icon>
+  </el-alert>
+  <el-alert
+    title="消息提示的文案"
+    type="info"
+    description="文字说明文字说明文字说明文字说明文字说明文字说明"
+    show-icon>
+  </el-alert>
+  <el-alert
+    title="警告提示的文案"
+    type="warning"
+    description="文字说明文字说明文字说明文字说明文字说明文字说明"
+    show-icon>
+  </el-alert>
+  <el-alert
+    title="错误提示的文案"
+    type="error"
+    description="文字说明文字说明文字说明文字说明文字说明文字说明"
+    show-icon>
+  </el-alert>
+</template>
+```
+:::
+
+### Attributes
+| 参数      | 说明          | 类型      | 可选值                           | 默认值  |
+|---------- |-------------- |---------- |--------------------------------  |-------- |
+| title     | 标题           | string | — | — |
+| type | 主题 | string | success/warning/info/error | info |
+| description | 辅助性文字。也可通过默认 slot 传入 | string | — | — |
+| closable | 是否可关闭 | boolean | — | true |
+| center | 文字是否居中 | boolean | — | true |
+| close-text | 关闭按钮自定义文本 | string | — | — |
+| show-icon | 是否显示图标 | boolean | — | false |
+| effect | 选择提供的主题 | string | light/dark | light |
+
+### Slot
+
+| Name | Description |
+|------|--------|
+| — | 描述 |
+| title | 标题的内容 |
+
+### Events
+| 事件名称 | 说明 | 回调参数 |
+|---------- |-------- |---------- |
+| close | 关闭alert时触发的事件 | — |

package/docs/pitElementUi/avatar.md

@@ -0,0 +1,147 @@
+## Avatar 头像
+
+用图标、图片或者字符的形式展示用户或事物信息。
+
+### 基本用法
+
+通过 `shape` 和 `size` 设置头像的形状和大小。
+
+:::demo
+```html
+<template>
+  <el-row class="demo-avatar demo-basic">
+    <el-col :span="12">
+      <div class="sub-title">circle</div>
+      <div class="demo-basic--circle">
+        <div class="block"><el-avatar :size="50" :src="circleUrl"></el-avatar></div>
+        <div class="block" v-for="size in sizeList" :key="size">
+          <el-avatar :size="size" :src="circleUrl"></el-avatar>
+        </div>
+      </div>
+    </el-col>  
+    <el-col :span="12">
+      <div class="sub-title">square</div>
+      <div class="demo-basic--circle">
+        <div class="block"><el-avatar shape="square" :size="50" :src="squareUrl"></el-avatar></div>
+        <div class="block" v-for="size in sizeList" :key="size">
+          <el-avatar shape="square" :size="size" :src="squareUrl"></el-avatar>
+        </div>
+      </div>
+    </el-col> 
+  </el-row>
+</template>
+<script>
+  export default {
+    data () {
+      return {
+        circleUrl: "https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png",
+        squareUrl: "https://cube.elemecdn.com/9/c2/f0ee8a3c7c9638a54940382568c9dpng.png",
+        sizeList: ["large", "medium", "small"]
+      }
+    }
+  }
+</script>
+
+```
+:::
+
+### 展示类型
+
+支持三种类型：图标、图片和字符
+
+:::demo
+```html
+<template>
+  <div class="demo-type">
+    <div>
+      <el-avatar icon="el-icon-user-solid"></el-avatar>
+    </div>
+    <div>
+      <el-avatar src="https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png"></el-avatar>
+    </div>
+    <div>
+      <el-avatar> user </el-avatar>
+    </div>
+  </div>
+</template>
+```
+:::
+
+### 图片加载失败的 fallback 行为
+
+当展示类型为图片的时候，图片加载失败的 fallback 行为
+
+:::demo
+```html
+<template>
+  <div class="demo-type">
+    <el-avatar :size="60" src="https://empty" @error="errorHandler">
+      <img src="https://cube.elemecdn.com/e/fd/0fc7d20532fdaf769a25683617711png.png"/>
+    </el-avatar>
+  </div>
+</template>
+<script>
+  export default {
+    methods: {
+      errorHandler() {
+        return true
+      }
+    }
+  }
+</script>
+
+```
+:::
+
+### 图片如何适应容器框
+
+当展示类型为图片的时候，使用 `fit` 属性定义图片如何适应容器框，同原生 [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit)。
+
+:::demo
+```html
+<template>
+  <div class="demo-fit">
+    <div class="block" v-for="fit in fits" :key="fit">
+        <span class="title">{{ fit }}</span>
+        <el-avatar shape="square" :size="100" :fit="fit" :src="url"></el-avatar>
+    </div>
+  </div>
+</template>
+<script>
+  export default {
+    data() {
+      return {
+        fits: ['fill', 'contain', 'cover', 'none', 'scale-down'],
+        url: 'https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg'
+      }
+    }
+  }
+</script>
+
+```
+:::
+
+### Attributes
+
+| 参数              | 说明                             | 类型            | 可选值 | 默认值 |
+| ----------------- | -------------------------------- | --------------- | ------ | ------ |
+| icon              | 设置头像的图标类型，参考 Icon 组件   | string          |        |        |
+| size              | 设置头像的大小                     | number/string | number / large / medium / small | large  |
+| shape             | 设置头像的形状  | string |    circle / square     |   circle  |
+| src               | 图片头像的资源地址 | string |        |      |
+| srcSet            | 以逗号分隔的一个或多个字符串列表表明一系列用户代理使用的可能的图像 | string |        |      |
+| alt               | 描述图像的替换文本 | string |        |      |
+| fit               | 当展示类型为图片的时候，设置图片如何适应容器框 | string |    fill / contain / cover / none / scale-down    |   cover   |
+
+
+### Events
+
+| 事件名 | 说明               | 回调参数 |
+| ------ | ------------------ | -------- |
+| error  | 图片类头像加载失败的回调， 返回 false 会关闭组件默认的 fallback 行为 |(e: Event)  |
+
+### Slot
+
+| 名称	 | 说明               |  
+| ------ | ------------------ | 
+| default  | 自定义头像展示内容 |

package/docs/pitElementUi/backtop.md

@@ -0,0 +1,60 @@
+## Backtop 回到顶部
+
+返回页面顶部的操作按钮
+
+### 基础用法
+
+滑动页面即可看到右下方的按钮。
+:::demo
+
+```html
+<template>
+  Scroll down to see the bottom-right button.
+  <el-backtop target=".page-component__scroll .el-scrollbar__wrap"></el-backtop>
+</template>
+```
+
+:::
+
+### 自定义显示内容
+
+显示区域被固定为 40px \* 40px 的区域, 其中的内容可支持自定义。
+:::demo
+
+```html
+<template>
+  Scroll down to see the bottom-right button.
+  <el-backtop target=".page-component__scroll .el-scrollbar__wrap" :bottom="100">
+    <div
+      style="{
+        height: 100%;
+        width: 100%;
+        background-color: #f2f5f6;
+        box-shadow: 0 0 6px rgba(0,0,0, .12);
+        text-align: center;
+        line-height: 40px;
+        color: #1989fa;
+      }"
+    >
+      UP
+    </div>
+  </el-backtop>
+</template>
+```
+
+:::
+
+### Attributes
+
+| 参数              | 说明                             | 类型            | 可选值 | 默认值 |
+| ----------------- | -------------------------------- | --------------- | ------ | ------ |
+| target            | 触发滚动的对象                   | string          |        |        |
+| visibility-height | 滚动高度达到此参数值才出现       | number |        | 200    |
+| right             | 控制其显示位置, 距离页面右边距   | number |        | 40     |
+| bottom            | 控制其显示位置, 距离页面底部距离 | number |        | 40     |
+
+### Events
+
+| 事件名 | 说明               | 回调参数 |
+| ------ | ------------------ | -------- |
+| click  | 点击按钮触发的事件 | 点击事件 |