@agile-team/wl-skills-kit 2.6.0 → 2.7.1

package/files/docs/jh-dept-picker.md

@@ -100,6 +100,23 @@ const form = ref({
 
 > ⚠️ `jh-dept-picker` 仅用于选择，展示请使用 `jh-text`
 
+### 场景 4：BaseQuery 配置式用法（推荐）
+
+```ts
+import { BusLogicDataType } from "@jhlc/types/src/logical-data";
+
+export const queryItems: BaseQueryItemDesc<any>[] = [
+  {
+    name: "deptId",
+    label: "部门",
+    logicType: BusLogicDataType.dept,
+    // 自动渲染为 DeptPickerComponent
+  },
+];
+```
+
+> **源码映射**: `BusLogicDataType.dept` → `DeptPickerComponent`
+
 ---
 
 ## 与手动实现对比

package/files/docs/jh-drag-row.md

@@ -176,16 +176,24 @@ onMounted(() => {
 
 ## Props 属性
 
-| 参数       | 说明                                 | 类型      | 默认值  |
-| ---------- | ------------------------------------ | --------- | ------- |
-| top-height | 上部区域的初始高度（单位：px）       | `number`  | -       |
-| topPercent | 上部区域的初始百分比（与 top-height 二选一） | `number`  | -       |
-| bottomHeight | 下部区域的初始高度（单位：px）       | `number`  | -       |
-| bottomPercent | 下部区域的初始百分比       | `number`  | -       |
-| height     | 容器总高度       | `string`  | `"400px"` |
-| sliderWidth | 拖拽分割线的宽度（单位：px） | `number`  | `10`    |
-
-> **提示**: 推荐使用 `top-height` 设置上部区域高度,下部区域会自动填充剩余空间。
+| 参数              | 说明                                         | 类型      | 默认值      |
+| ----------------- | -------------------------------------------- | --------- | ----------- |
+| topHeight         | 上部区域的初始高度（单位：px）               | `number`  | -           |
+| topPercent        | 上部区域的初始百分比（与 topHeight 二选一）   | `number`  | -           |
+| bottomHeight      | 下部区域的初始高度（单位：px）               | `number`  | -           |
+| isNest            | 是否嵌套使用（嵌套在另一个 drag 组件内部）   | `boolean` | `false`     |
+| width             | 容器总宽度                                   | `string`  | `"400px"`   |
+| height            | 容器总高度                                   | `string`  | `"400px"`   |
+| sliderWidth       | 拖拽分割线的高度（单位：px）                 | `number`  | `10`        |
+| sliderColor       | 拖拽手柄指示线颜色                           | `string`  | `"#6f808d"` |
+| sliderBgColor     | 拖拽手柄背景色                               | `string`  | `"#a7caec"` |
+| sliderHoverColor  | 拖拽手柄悬停时指示线颜色                     | `string`  | `"#6f808d"` |
+| sliderBgHoverColor| 拖拽手柄悬停时背景色                         | `string`  | `"#c8dcea"` |
+
+> **提示**:
+> - 推荐使用 `topHeight` 设置上部区域高度，下部区域会自动填充剩余空间
+> - `topPercent` 与 `topHeight` 二选一；当两者都传时，`topHeight` 在 mounted 后会被转换为百分比
+> - 实际项目中通常配合 CSS `height: 100%` 使容器占满可用空间，因此 `width`/`height` prop 仅作为兜底默认值
 
 ## Slots 插槽
 
@@ -506,37 +514,52 @@ const handlePlanChange = (row: any) => {
 
 ## 样式定制
 
-### 修改拖拽手柄样式
+### 通过 Props 自定义手柄颜色（推荐）
+
+```vue
+<jh-drag-row
+  :top-height="380"
+  slider-color="#409eff"
+  slider-bg-color="#e6f0fa"
+  slider-hover-color="#1890ff"
+  slider-bg-hover-color="#bae0ff"
+>
+  ...
+</jh-drag-row>
+```
+
+### 通过 CSS 覆盖手柄样式
 
 ```scss
 :deep(.drager_row) {
   height: 100%;
 
-  // 拖拽手柄
-  .drager {
-    background: #e0e0e0; // 手柄背景色
-    height: 6px; // 手柄高度
-    cursor: row-resize; // 鼠标样式
+  // 拖拽手柄（CSS 类名为 .slider_row）
+  > .slider_row {
+    background: #e0e0e0;
+    cursor: row-resize;
 
     &:hover {
-      background: #1890ff; // 悬停颜色
+      background: #1890ff;
     }
   }
 }
 ```
 
+> **源码 CSS 类名参考**: `.drager_row`（主容器）、`.drager_top`（上部区域）、`.drager_bottom`（下部区域）、`.slider_row`（拖拽手柄）
+
 ### 调整上下区域内边距
 
 ```scss
 :deep(.drager_row) {
   height: 100%;
 
-  .top-area {
-    padding: 10px;
+  .drager_top {
+    padding-bottom: 10px;
   }
 
-  .bottom-area {
-    padding: 10px;
+  .drager_bottom {
+    padding-top: 10px;
   }
 }
 ```

package/files/docs/jh-file-upload.md

@@ -191,6 +191,49 @@ interface FileItem {
 
 ---
 
+## 编程式调用（FormDialog 工具类）
+
+源码中 `FormDialog` 提供了便捷的附件上传/预览方法，无需手动放置 `<jh-file-upload />`：
+
+### uploadAttach — 上传附件弹窗
+
+```ts
+import { FormDialog } from "@jhlc/common-core/src/util/form-dialog";
+
+const handleUpload = async () => {
+  const { type, fileList } = await FormDialog.uploadAttach("上传附件", {
+    relativeType: "order",
+    relativeId: orderId,
+    autoUpload: false,  // 点确认后才上传
+    limit: 5,
+    deletable: true,
+    disabled: false,
+  });
+  if (type === "success") {
+    // 上传成功
+  }
+};
+```
+
+### previewAttach — 预览附件弹窗（只读）
+
+```ts
+FormDialog.previewAttach("查看附件", "order", orderId);
+```
+
+### previewAttachBatch — 批量预览
+
+```ts
+FormDialog.previewAttachBatch("查看全部附件", [
+  { relativeType: "order", relativeId: id1, title: "订单附件" },
+  { relativeType: "contract", relativeId: id2, title: "合同附件" },
+]);
+```
+
+> **源码位置**: `@jhlc/common-core/src/util/form-dialog.ts`
+
+---
+
 ## 🎯 真实项目示例
 
 ### 示例 1：合同附件

package/files/docs/jh-select.md

@@ -50,7 +50,9 @@ const form = ref({
 | collapseTag          | 多选时是否折叠 Tag        | `boolean`                                                | `false`    |
 | teleported           | 是否将下拉面板插入 body   | `boolean`                                                | `true`     |
 
-> **重点**: 当 `dict` 属性存在时,组件会自动加载对应字典数据,无需手动设置 `items`。
+> **重点**:
+> - 当 `dict` 属性存在时，组件会自动加载对应字典数据，无需手动设置 `items`
+> - 源码中 `BusLogicDataType.dict` 和 `BusLogicDataType.company` 都映射为 `SelectComponent`，即公司选择也使用同一组件
 
 ## Events 事件
 
@@ -81,9 +83,38 @@ const form = ref({
 
 ### 场景 4：BaseQuery 配置式用法（推荐）
 
+#### 方式一：使用 logicType 自动映射（推荐）
+
 ```ts
-// data.ts 查询项配置
-export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
+import { BusLogicDataType } from "@jhlc/types/src/logical-data";
+
+export const queryItems: BaseQueryItemDesc<any>[] = [
+  {
+    name: "status",
+    label: "状态",
+    logicType: BusLogicDataType.dict,
+    logicValue: "order_status",
+    // 自动渲染为 jh-select，自动加载字典 order_status 的选项
+  },
+  {
+    name: "companyId",
+    label: "公司",
+    logicType: BusLogicDataType.company,
+    logicValue: "companyId",
+    // BusLogicDataType.company 同样映射为 SelectComponent
+  },
+];
+```
+
+> **源码映射规则**（`getFormItemByLogicType`）：
+> - `BusLogicDataType.dict` → `SelectComponent`
+> - `BusLogicDataType.company` → `SelectComponent`
+> - `BusLogicDataType.enums` → `SelectComponent`
+
+#### 方式二：使用 component 自定义
+
+```ts
+export const queryItems: BaseQueryItemDesc<any>[] = [
   {
     name: "orderStatus",
     label: "操作类型",
@@ -91,7 +122,6 @@ export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
     component: () => {
       return {
         tag: "jh-select",
-        // 方式一：静态数据
         items: [
           { label: "是", value: 1 },
           { label: "否", value: 0 }
@@ -99,16 +129,22 @@ export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
       };
     }
   },
-  {
-    name: "status",
-    label: "状态",
-    logicType: BusLogicDataType.dict,
-    logicValue: "order_status" // 字典 code
-    // 方式二：使用字典数据（会自动加载）
-  }
 ];
 ```
 
+#### historyTop 个人偏好（仅对 jh-select 生效）
+
+```ts
+{
+  name: "customerId",
+  label: "客户",
+  logicType: BusLogicDataType.dict,
+  logicValue: "customer_type",
+  historyTop: true,
+  // 启用后，用户近期选择过的选项会置顶显示
+}
+```
+
 ### 场景 5：静态 items 方式
 
 ```vue
@@ -126,9 +162,10 @@ export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
 
 ## 最佳实践
 
-1. **始终使用 dict 属性**
-   - 不要手动写 options
-   - 保证字典来源统一
+1. **优先使用 logicType + logicValue**
+   - 配置式优于模板式，保证字典来源统一
+   - `logicType: BusLogicDataType.dict` 自动渲染 jh-select
+   - 只有静态选项时才使用 `component` + `items`
 
 2. **配合 jh-text 使用**
    - 列表展示用 `jh-text`

package/files/docs/jh-text.md

@@ -67,9 +67,10 @@ import "@jhlc/common-core";
 | fontSize | 字体大小 | `"extra-small" \| "small" \| "base" \| "medium" \| "large" \| "extra-large"` | - |
 | fontWeight | 字体粗细 | `"light" \| "regular" \| "medium" \| "semi"` | - |
 
-> **提示**: 
-> - `dict` 传入时,会自动设置 `type="dict"`
-> - 同时使用 `logicType` 和 `logicValue` 可以实现自动翻译
+> **源码说明**:
+> - `content` 是框架内部渲染时优先使用的属性（如 `base-form-detail` 自动传入 `content: form[name]`）
+> - `dict` 传入时，会自动设置 `type="dict"`
+> - `logicType` + `logicValue` 是配置式用法的核心，框架会根据类型自动翻译（字典/用户/部门）
 
 ---
 
@@ -132,28 +133,45 @@ import "@jhlc/common-core";
 />
 ```
 
-### 场景 5：BaseDetail 配置式用法
+### 场景 5：BaseFormDetail 配置式用法（自动渲染）
+
+在 `BaseFormDetail` 中，当配置项没有自定义 `component` 时，框架会自动使用 `jh-text` 渲染，并传入 `content`、`logicType`、`logicValue`：
 
 ```ts
-// data.ts 详情项配置
-export const detailItemsConfig: BaseFormDetailDesc[] = [
+import { BusLogicDataType } from "@jhlc/types/src/logical-data";
+
+export const detailItems: BaseFormDetailDesc[] = [
   {
     name: "status",
     label: "状态",
     logicType: BusLogicDataType.dict,
-    logicValue: "order_status"
-    // 会自动渲染为 jh-text 并翻译字典
+    logicValue: "order_status",
+    // 框架自动渲染为: <jh-text :content="form.status" logicType="dict" logicValue="order_status" />
   },
   {
     name: "createUserId",
     label: "创建人",
     logicType: BusLogicDataType.user,
-    logicValue: "userId"
-    // 会自动翻译用户名
-  }
+    // 自动翻译用户 ID 为用户名称
+  },
+  {
+    name: "deptId",
+    label: "部门",
+    logicType: BusLogicDataType.dept,
+    // 自动翻译部门 ID 为部门名称
+  },
+  {
+    name: "remark",
+    label: "备注",
+    // 无 logicType 时直接展示文本
+  },
 ];
 ```
 
+> **源码逻辑**（`form-detail-item.ts` 的 `renderItem`）：
+> 1. 若配置了 `component` → 渲染自定义组件
+> 2. 若未配置 `component` → 自动渲染 `<jh-text :content="form[name]" :logicType :logicValue />`
+
 ---
 
 ## 与手动处理对比

package/files/docs/jh-textarea.md

@@ -0,0 +1,159 @@
+# jh-textarea - 多行文本输入组件
+
+> 平台统一的多行文本输入组件，适用于备注、描述等需要输入较长文本的场景
+
+## 📦 组件位置
+
+```ts
+import "@jhlc/common-core";
+```
+
+组件已全局注册，可直接在模板中使用 `<jh-textarea />`。
+
+---
+
+## 基本用法
+
+### 1️⃣ 表单录入（最常用）
+
+```vue
+<template>
+  <jh-textarea v-model="form.remark" placeholder="请输入备注" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const form = ref({
+  remark: ""
+});
+</script>
+```
+
+---
+
+### 2️⃣ 限制行数
+
+```vue
+<jh-textarea v-model="form.description" :rows="4" placeholder="请输入描述信息" />
+```
+
+---
+
+## Props 属性
+
+| 参数                 | 说明                    | 类型               | 默认值         |
+| -------------------- | ----------------------- | ------------------ | -------------- |
+| modelValue / v-model | 绑定值                  | `string`           | -              |
+| placeholder          | 占位提示                | `string`           | `"请输入"`     |
+| rows                 | 显示行数                | `number`           | `3`            |
+| maxlength            | 最大输入长度            | `number`           | -              |
+| showWordLimit        | 是否显示字数统计        | `boolean`          | `false`        |
+| disabled             | 是否禁用                | `boolean`          | `false`        |
+| clearable            | 是否可清空              | `boolean`          | `true`         |
+| autosize             | 自适应内容高度          | `boolean \| object`| `false`        |
+
+---
+
+## Events 事件
+
+| 事件名            | 说明         | 回调参数          |
+| ----------------- | ------------ | ----------------- |
+| change            | 值变化时触发 | `(value) => void` |
+| update:modelValue | v-model 更新 | `(value) => void` |
+| blur              | 失去焦点     | `() => void`      |
+
+---
+
+## 常见场景
+
+### 场景 1：表单备注
+
+```vue
+<jh-textarea v-model="form.remark" placeholder="请输入备注" />
+```
+
+### 场景 2：带字数限制
+
+```vue
+<jh-textarea
+  v-model="form.description"
+  :maxlength="500"
+  show-word-limit
+  placeholder="请输入描述（最多500字）"
+/>
+```
+
+### 场景 3：BaseQuery / BaseForm 配置式用法
+
+```ts
+import { BusLogicDataType } from "@jhlc/types/src/logical-data";
+
+export const formItems: BaseFormItemDesc<any>[] = [
+  {
+    name: "remark",
+    label: "备注",
+    logicType: BusLogicDataType.textarea,
+    // 自动渲染为 jh-textarea
+  },
+];
+```
+
+> **源码映射**（`getFormItemByLogicType`）：`BusLogicDataType.textarea` → `jh-textarea`
+
+---
+
+## 与 el-input 对比
+
+### 使用 jh-textarea（推荐）
+
+```vue
+<jh-textarea v-model="form.remark" />
+```
+
+✅ 统一样式风格
+✅ 简化配置
+
+### 使用 el-input（不推荐）
+
+```vue
+<el-input v-model="form.remark" type="textarea" :rows="3" />
+```
+
+❌ 需要每次指定 `type="textarea"`
+❌ 样式与交互可能不统一
+
+---
+
+## 最佳实践
+
+1. **表单中长文本字段统一使用 jh-textarea**
+   - 与 `jh-select`、`jh-date` 等保持一致的组件体系
+
+2. **配合 logicType 使用**
+   - 配置式表单中使用 `logicType: BusLogicDataType.textarea`
+   - 框架自动渲染为 `jh-textarea`
+
+3. **详情页展示使用 jh-text**
+   - 编辑：`jh-textarea`
+   - 展示：`jh-text`
+
+---
+
+## 注意事项
+
+1. **仅用于编辑场景**
+   - 详情/只读展示使用 `jh-text`
+
+2. **长度限制建议配合后端校验**
+   - 前端 `maxlength` 仅做交互限制
+
+---
+
+## 🚀 快速开始
+
+1. 直接使用 v-model 绑定字段
+2. 配置式表单使用 `logicType: BusLogicDataType.textarea`
+3. 详情展示统一使用 `jh-text`
+
+**推荐作为平台统一的多行文本输入组件使用！**

package/files/docs/jh-user-picker.md

@@ -97,6 +97,23 @@ const form = ref({
 
 > ⚠️ `jh-user-picker` 仅用于选择，展示请使用 `jh-text`
 
+### 场景 4：BaseQuery 配置式用法（推荐）
+
+```ts
+import { BusLogicDataType } from "@jhlc/types/src/logical-data";
+
+export const queryItems: BaseQueryItemDesc<any>[] = [
+  {
+    name: "createUserId",
+    label: "创建人",
+    logicType: BusLogicDataType.user,
+    // 自动渲染为 UserPickerComponent
+  },
+];
+```
+
+> **源码映射**: `BusLogicDataType.user` → `UserPickerComponent`
+
 ---
 
 ## 与手动实现对比