pit-docs-mcp 1.0.2

package/docs/pitBusinessUi/input-formatter.md

@@ -0,0 +1,100 @@
+# pit-input-formatter 格式化输入框
+
+带单位后缀的输入框，支持内置格式化预设（距离、温度等）和自定义格式化函数，可控制数值范围、精度、是否整数等。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值 | String / Number | `""` |
+| unit | 后缀单位（`plain=false` 时展示） | String | `"m"` |
+| plain | 是否隐藏单位后缀 | Boolean | `false` |
+| formatter | 自定义格式化函数（优先于 formatterPreset） | Function | `null` |
+| formatterPreset | 内置预设名称 | String | `"null"` |
+| placeholder | 占位文本 | String | `"请输入"` |
+| describe | 格式化参数配置（配合内置预设） | Object | `{}` |
+| maxMinChange | 超出范围时是否自动修正为边界值（`false` 则恢复上次值） | Boolean | `false` |
+
+**formatterPreset 可选值**
+
+| 预设名 | 说明 |
+| --- | --- |
+| `distance` | 距离（3位小数） |
+| `temperature` | 温度（3位小数，-99~99） |
+| `numberLimit` | 自定义数值范围，配合 `describe` |
+
+**describe 可配置字段**（用于 `numberLimit`）
+
+| 字段 | 说明 | 默认值 |
+| --- | --- | --- |
+| int | 是否为整数 | `true` |
+| fixed | 小数位数 | `0` |
+| max | 最大值 | `1e10` |
+| min | 最小值 | `-1e10` |
+| maxLen | 整数位最大长度 | `10` |
+| negative | 是否允许负数 | `true` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `String` |
+
+## 示例
+
+### 使用内置距离预设（保留 3 位小数，单位 m）
+
+```vue
+<pit-input-formatter
+  v-model="form.length"
+  formatter-preset="distance"
+  unit="m" />
+```
+
+### 使用温度预设
+
+```vue
+<pit-input-formatter
+  v-model="form.temperature"
+  formatter-preset="temperature"
+  unit="°C" />
+```
+
+### 自定义数值范围（2 位小数，0~999）
+
+```vue
+<pit-input-formatter
+  v-model="form.ratio"
+  formatter-preset="numberLimit"
+  unit="%"
+  :describe="{ int: false, fixed: 2, max: 999, min: 0, negative: false }"
+  :max-min-change="true" />
+```
+
+### 自定义格式化函数
+
+```vue
+<pit-input-formatter
+  v-model="form.custom"
+  :formatter="myFormatter"
+  unit="kg" />
+
+<script>
+methods: {
+  myFormatter(val) {
+    return val.replace(/[^\d.]/g, '')
+  }
+}
+</script>
+```
+
+### 隐藏单位（plain 模式）
+
+```vue
+<pit-input-formatter v-model="form.value" formatter-preset="distance" plain />
+```
+
+## 注意事项
+
+- `formatterPreset` 与 `formatter` 同时传时，以 `formatter` 为准。
+- `maxMinChange=false` 时，超出范围输入会恢复为上次合法值；`maxMinChange=true` 时，超出范围自动修正为边界值。

package/docs/pitBusinessUi/input-number.md

@@ -0,0 +1,47 @@
+# pit-input-number 数字输入框
+
+对 `el-input-number` 的封装，控件位置默认在右侧，最大值默认从 `$Business.inputNumberMax` 读取。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值 | Number | `0` |
+| min | 最小值 | Number | `0` |
+| max | 最大值（未传则读取 `$Business.inputNumberMax`） | Number | — |
+| controlsPosition | 控制按钮位置 | String | `"right"` |
+
+> 其余 `el-input-number` 属性通过 `v-bind="$attrs"` 透传。
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `Number` |
+| change | 值变化 | `Number` |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-input-number v-model="form.count" />
+```
+
+### 自定义范围
+
+```vue
+<pit-input-number v-model="form.percent" :min="0" :max="100" />
+```
+
+### 修改全局最大值
+
+```js
+// main.js 注册时配置
+Vue.use(PitBusinessUI, { inputNumberMax: 99999999 })
+```
+
+## 注意事项
+
+- 输入 `null` / 空时，组件内部统一置为 `0`（见源码）。
+- 全局默认最大值通过 `inputNumberMax` 配置，默认为 `9999`。

package/docs/pitBusinessUi/input-select.md

@@ -0,0 +1,68 @@
+# pit-input-select 输入选择框
+
+显示为只读输入框 + 右侧图标，用于点击后弹出自定义选择面板的场景（配合 Dialog / Drawer 使用）。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值（展示文本） | String | `""` |
+| suffixIcon | 右侧 icon class | String | `"el-icon-arrow-right"` |
+| disabled | 是否禁用 | Boolean | `false` |
+| readonly | 是否只读 | Boolean | `false` |
+| clearable | 是否显示清空按钮 | Boolean | `true` |
+| placeholder | 占位文本 | String | `"请选择"` |
+
+> 其余 `el-input` 属性通过 `v-bind="$attrs"` 透传。
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化时触发（v-model） | `String` |
+| change | 值变化时触发 | `String` |
+
+## 示例
+
+### 基础用法（点击打开选择弹窗）
+
+```vue
+<template>
+  <div>
+    <pit-input-select
+      v-model="selected"
+      placeholder="请选择部门"
+      @click.native="showDialog = true" />
+
+    <pit-dialog :visible.sync="showDialog" title="选择部门">
+      <!-- 部门树组件 -->
+      <dept-tree @select="onDeptSelect" />
+    </pit-dialog>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return { selected: '', showDialog: false }
+  },
+  methods: {
+    onDeptSelect(dept) {
+      this.selected = dept.name
+      this.showDialog = false
+    }
+  }
+}
+</script>
+```
+
+### 禁用状态
+
+```vue
+<pit-input-select v-model="value" disabled />
+```
+
+## 注意事项
+
+- 该组件本身不内置弹窗，仅提供"选择框外观"，需配合弹窗/抽屉组合使用。
+- 点击触发事件推荐使用 `@click.native` 绑定在组件上。

package/docs/pitBusinessUi/input.md

@@ -0,0 +1,56 @@
+# pit-input 输入框
+
+对 `el-input` 的封装，统一 `maxlength`、`show-word-limit`，默认从 `$Business.inputMaxlength` 读取最大长度。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值 | String / Number | `""` |
+| maxlength | 最大输入长度（未传则读取 `$Business.inputMaxlength`） | Number | — |
+| clearable | 是否可清空 | Boolean | `true` |
+| placeholder | 占位文本 | String | — |
+
+> 其余 `el-input` 属性通过 `v-bind="$attrs"` 透传，事件通过 `v-on="$listeners"` 透传。
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 输入时触发，用于 v-model | `String / Number` |
+| change | 值变化时触发 | `String / Number` |
+
+## Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| prepend | 前置内容 |
+| append | 后置内容 |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-input v-model="form.name" placeholder="请输入姓名" />
+```
+
+### 自定义最大长度
+
+```vue
+<pit-input v-model="form.remark" :maxlength="200" placeholder="请输入备注" />
+```
+
+### 带前后缀
+
+```vue
+<pit-input v-model="form.url">
+  <template slot="prepend">https://</template>
+  <template slot="append">.com</template>
+</pit-input>
+```
+
+## 注意事项
+
+- 组件已默认开启 `show-word-limit`，无需额外配置。
+- 全局默认最大长度通过 `Vue.use(PitBusinessUI, { inputMaxlength: 100 })` 修改。

package/docs/pitBusinessUi/jm-preview.md

@@ -0,0 +1,47 @@
+# pit-jm-preview 积木报表预览
+
+极简的积木报表（JimuReport）内嵌预览组件，将外部传入的报表 URL 渲染在 `<iframe>` 中。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| previewUrl | 积木报表完整预览 URL（含参数） | String | `""` |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-jm-preview :preview-url="reportUrl" />
+```
+
+### 动态拼接报表参数
+
+```vue
+<template>
+  <pit-jm-preview :preview-url="getReportUrl()" />
+</template>
+
+<script>
+export default {
+  computed: {
+    getReportUrl() {
+      const base = this.env.VUE_APP_JM_URL + '/jmreport/show'
+      const params = new URLSearchParams({
+        id: this.reportId,
+        projectId: localStorage.getItem('projectId'),
+        token: this.getToken()
+      })
+      return `${base}?${params}`
+    }
+  }
+}
+</script>
+```
+
+## 注意事项
+
+- 组件不处理 URL 生成逻辑，完整 URL 需由父组件构造好后传入。
+- `iframe` 宽高默认铺满父容器（`.pit-jm-preview` 使用 `width: 100%; height: 100%`），请保证父容器有明确高度。
+- 若积木报表系统要求携带鉴权 Token，需在 URL 参数中自行拼接。

package/docs/pitBusinessUi/json-editor.md

@@ -0,0 +1,71 @@
+# pit-json-editor JSON 编辑器
+
+基于 `CodeMirror` 的 JSON 专用编辑器，带行号、实时 JSON lint 校验。
+
+## 前置依赖
+
+- `codemirror`（含 json lint 插件）
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | JSON 对象（组件内部自动 `JSON.stringify` 格式化显示） | any | — |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 编辑器内容变化（v-model） | `String`（JSON 字符串，可能非法） |
+| changed | 同 input | `String` |
+
+## Methods
+
+| 方法名 | 说明 | 返回值 |
+| --- | --- | --- |
+| `getValue()` | 获取编辑器当前原始字符串 | `String` |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-json-editor v-model="jsonData" />
+
+<script>
+export default {
+  data() {
+    return {
+      jsonData: { name: 'test', version: 1 }
+    }
+  }
+}
+</script>
+```
+
+### 提交前解析验证
+
+```vue
+<pit-json-editor ref="jsonEditor" v-model="rawJson" />
+
+<el-button @click="submit">提交</el-button>
+
+<script>
+methods: {
+  submit() {
+    try {
+      const parsed = JSON.parse(this.$refs.jsonEditor.getValue())
+      this.saveConfig(parsed)
+    } catch (e) {
+      this.$message.error('JSON 格式错误，请检查后重试')
+    }
+  }
+}
+</script>
+```
+
+## 注意事项
+
+- `value` 传入的是 **对象**，组件内部在 `mounted` 和 `watch` 中调用 `JSON.stringify(value, null, 2)` 格式化显示。
+- `input`/`changed` 事件输出的是**字符串**（可能存在语法错误），提交前需 `JSON.parse` 验证。
+- lint 错误以红色下划线标注（CodeMirror lint 插件），但不会阻止 `input` 事件触发。

package/docs/pitBusinessUi/loading-btn.md

@@ -0,0 +1,64 @@
+# pit-loading-btn 加载按钮
+
+点击后自动进入 Loading 状态，等待传入的异步回调完成后自动恢复，避免重复点击。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| confirmCallBack | 点击后执行的异步函数，**必须返回 Promise** | Function | `null` |
+| type | 按钮类型（同 `el-button` type） | String | `"colour-10"` |
+| disabled | 是否禁用 | Boolean | `false` |
+
+> 其余 `el-button` 属性通过 `v-bind="$attrs"` 透传。
+
+## Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| default | 按钮文字内容 |
+
+## 示例
+
+### 基础用法（提交表单）
+
+```vue
+<pit-loading-btn :confirm-call-back="handleSubmit">保存</pit-loading-btn>
+
+<script>
+methods: {
+  async handleSubmit() {
+    await this.$api.saveForm(this.form)
+    this.$message.success('保存成功')
+  }
+}
+</script>
+```
+
+### 带错误处理（loading 无论成功失败都会恢复）
+
+```vue
+<pit-loading-btn :confirm-call-back="handleDelete" type="danger">
+  删除
+</pit-loading-btn>
+
+<script>
+methods: {
+  async handleDelete() {
+    try {
+      await this.$api.delete(this.id)
+      this.$message.success('删除成功')
+    } catch (e) {
+      this.$message.error('删除失败')
+      throw e  // 需 rethrow 以触发 finally
+    }
+  }
+}
+</script>
+```
+
+## 注意事项
+
+- `confirmCallBack` 必须返回 `Promise`（`async` 函数天然满足）。
+- 无论 Promise resolve 还是 reject，`loading` 都会在 `finally` 中重置为 `false`。
+- 不使用 `@click` 事件，点击逻辑完全由 `confirmCallBack` 接管。

package/docs/pitBusinessUi/monaco.md

@@ -0,0 +1,82 @@
+# pit-monaco 代码编辑器（Monaco Editor）
+
+基于 `monaco-editor` 封装的代码编辑器，支持语法高亮、自动换行、只读模式，通过 v-model 双向绑定内容，提供光标位置插入文本的 Methods。
+
+## 前置依赖
+
+- `monaco-editor`（须在 webpack/vite 中配置 MonacoWebpackPlugin 或同等插件）
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 编辑器代码内容 | String | `""` |
+| options | Monaco editor 配置项（深合并到默认配置） | Object | `{}` |
+
+## 默认配置
+
+```js
+{
+  selectOnLineNumbers: true,
+  roundedSelection: false,
+  wordWrap: 'on',      // 自动换行
+  language: 'java',   // 语言：css/html/java/javascript/json/csharp 等
+  theme: 'vs',        // 主题：vs / vs-dark / hc-black
+  formatOnPaste: true,
+  formatOnType: true,
+  glyphMargin: true,
+  fontSize: 14,
+  readOnly: false
+}
+```
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 内容变化（v-model） | `String` |
+
+## Methods
+
+| 方法名 | 说明 | 参数 |
+| --- | --- | --- |
+| `changeEditor(data)` | 同时更新内容和配置项 | `{ value: String, options: Object }` |
+| `insert(text)` | 在当前光标位置插入文本 | `String` |
+
+## 示例
+
+### 基础用法（Java）
+
+```vue
+<pit-monaco v-model="code" />
+```
+
+### 切换语言和主题
+
+```vue
+<pit-monaco
+  v-model="code"
+  :options="{ language: 'javascript', theme: 'vs-dark', readOnly: true }" />
+```
+
+### 编程插入文本
+
+```vue
+<pit-monaco ref="editor" v-model="code" />
+
+<el-button @click="insertSnippet">插入模板</el-button>
+
+<script>
+methods: {
+  insertSnippet() {
+    this.$refs.editor.insert('\n// TODO: implement')
+  }
+}
+</script>
+```
+
+## 注意事项
+
+- `options` prop 更新时通过 `monacoEditor.updateOptions()` 增量更新，不会重建编辑器实例。
+- 组件销毁时未内置 `editor.dispose()`，若页面频繁创建/销毁本组件，建议在父组件 `beforeDestroy` 中手动调用。
+- 使用 `vite` 构建时，需安装 `vite-plugin-monaco-editor` 并配置 worker。

package/docs/pitBusinessUi/money-input.md

@@ -0,0 +1,59 @@
+# pit-money-input 金额输入框
+
+专为金额场景设计的输入框，自动千分位格式化，支持精度控制、负数、最小值限制，默认追加"元"单位后缀。
+
+## Props
+
+| 参数 | 说明 | 类型 | 必填 | 默认值 |
+| --- | --- | --- | --- | --- |
+| value / v-model | 绑定值（实际数值，不含逗号） | any | ✅ | — |
+| bit | 保留小数位数 | Number | — | `2` |
+| min | 最小值（设为 `0` 时会拦截负数输入） | String / Number | — | `null` |
+| maxlength | 最大输入长度 | Number | — | `50` |
+| placeholder | 占位文本 | String | — | `"请输入金额"` |
+| showWordLimit | 是否显示字数统计 | Boolean | — | `false` |
+| showComma | 是否显示千分位逗号 | Boolean | — | `true` |
+| template | 单位后缀样式：`'append'` 显示"元"，`'tenThousandYuan'` 显示"万元"，其他值不显示 | String | — | `"append"` |
+| data | 实时输入值（含逗号），支持 `.sync` 获取 | any | — | `null` |
+| enterFuc | 按 Enter 键时的回调 | Function | — | `() => {}` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 失焦/回车后输出纯数字值（v-model） | `String`（纯数字，无逗号） |
+| update:data | 实时输入值变化（含千分位格式） | `String` |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-money-input v-model="form.amount" />
+<!-- 展示：1,234.56 元  绑定值：'1234.56' -->
+```
+
+### 保留 4 位小数，显示万元单位
+
+```vue
+<pit-money-input v-model="form.totalAmount" :bit="4" template="tenThousandYuan" />
+```
+
+### 不允许负数、不显示千分位
+
+```vue
+<pit-money-input v-model="form.price" :min="0" :show-comma="false" />
+```
+
+### 实时获取格式化后的显示值
+
+```vue
+<pit-money-input v-model="form.amount" :data.sync="form.amountDisplay" />
+<!-- form.amountDisplay 为含逗号格式的字符串，用于显示 -->
+```
+
+## 注意事项
+
+- `v-model` 绑定值为**纯数字字符串**（无千分位逗号），请勿直接展示给用户。
+- `data.sync` 获取的是含千分位格式的**显示值**，不能直接提交接口。
+- `bit` 控制保留精度（截断，非四舍五入），请按业务场景配置。

package/docs/pitBusinessUi/pagination.md

@@ -0,0 +1,70 @@
+# pit-pagination 分页
+
+对 `el-pagination` 的封装，支持 `page.sync` + `limit.sync` 双向绑定，自动滚动至顶部。
+
+## Props
+
+| 参数 | 说明 | 类型 | 必填 | 默认值 |
+| --- | --- | --- | --- | --- |
+| total | 总条目数 | Number | ✅ | — |
+| page | 当前页码，支持 `.sync` | Number | — | `1` |
+| limit | 每页条数，支持 `.sync` | Number | — | `10` |
+| pageSizes | 每页条数候选列表 | Array | — | `[10, 20, 30, 50, 100]` |
+| layout | 分页组件布局 | String | — | `"total, sizes, prev, pager, next, jumper"` |
+| background | 是否显示背景色 | Boolean | — | `true` |
+| autoScroll | 翻页后是否自动滚动至顶部 | Boolean | — | `true` |
+| hidden | 是否隐藏分页组件 | Boolean | — | `false` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| pagination | 翻页或切换每页条数时触发 | `{ page: Number, limit: Number }` |
+| update:page | 页码变化时触发，配合 `.sync` | `Number` |
+| update:limit | 每页条数变化时触发，配合 `.sync` | `Number` |
+
+## 示例
+
+### 基础用法
+
+```vue
+<template>
+  <pit-pagination
+    :total="total"
+    :page.sync="queryParams.page"
+    :limit.sync="queryParams.limit"
+    @pagination="fetchList" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      total: 0,
+      queryParams: { page: 1, limit: 10 }
+    }
+  },
+  methods: {
+    fetchList({ page, limit }) {
+      // 调用接口
+    }
+  }
+}
+</script>
+```
+
+### 隐藏分页（数据少于一页时）
+
+```vue
+<pit-pagination
+  :total="total"
+  :page.sync="page"
+  :limit.sync="limit"
+  :hidden="total <= limit"
+  @pagination="fetchList" />
+```
+
+## 注意事项
+
+- `total` 为必填项，缺少时分页无法正常计算。
+- 关闭自动滚动：`:auto-scroll="false"`。