@qilitt-mickey/vue3-temp-skill 1.0.12 → 1.1.2

package/references/form-advanced.md

@@ -1,24 +1,107 @@
+---
+skill: form-advanced
+description: 弹窗（ReDialog / ReDialogResize）、远程下拉、级联、锚点、卡片选择、地址解析等高级表单能力。图标选择完整规范见 icons 模块。
+scope: project
+tags: [form, dialog, ReDialog, ReDialogResize, ReSelectQuery, ReCascader, iconPicker, anchor, address-parse]
+---
+
 # 高级表单组件
 
-规范图标选择器、分段控制器、卡片选择、锚点导航、可折叠面板及地址解析等高级表单组件的使用。在开发复杂表单时参照。
+> 核心选择器与 CRUD 列表筛选项高频相关。  
+> **弹窗**：业务弹窗统一用 `ReDialog` / `ReDialogResize`，禁止业务页直接堆裸 `el-dialog`（除非用户明确要求）。
+
+## 依赖（缺则先装）
+
+按用到的能力安装（先查 `package.json`）：
+
+| 能力 | 包 | 版本 |
+|---|---|---|
+| 地址解析 | `address-parse` | `1.2.19` |
+| 卡片选择 ReCheckCard | `plus-pro-components` | `0.1.31` |
+
+```bash
+pnpm add address-parse@1.2.19 plus-pro-components@0.1.31
+```
+
+`ReDialog` / `ReDialogResize` / `ReSelectQuery` / `ReCascader` / `ReIconPicker` / `ReAnchor` 为项目封装，**无额外 npm 包**。
+
+## ReSelectQuery（远程搜索下拉）
+
+真实 props 以组件为准：`url` / `value` / `label` / `multiple` / `edit-data` / `handle-result` 等（**不是** `:api` + `label-key`）。
+
+```vue
+<script setup lang="ts">
+import { ReSelectQuery } from "@/components/ReSelectQuery";
+
+defineOptions({ name: "UserSelectDemo" });
+
+const formData = reactive({
+  userCode: "",
+  userCodeBack: "WR0173",
+  userBackData: [{ userCode: "WR0173", userName: "示例用户" }],
+});
+
+function handleResult(data: Record<string, unknown>[], totalCount: number, key?: string) {
+  data.forEach((item) => {
+    item.showText = `【${item.userCode}】${item.userName}`;
+    item.keyWords = key || "";
+  });
+  return { content: data, totalCount };
+}
+</script>
+
+<template>
+  <ReSelectQuery
+    v-model="formData.userCode"
+    value="userCode"
+    label="userName"
+    url="/TMdmIpsUserApi/searchTMdmIpsUserPage"
+  />
+  <ReSelectQuery
+    v-model="formData.userCodeBack"
+    value="userCode"
+    label="showText"
+    url="/TMdmIpsUserApi/searchTMdmIpsUserPage"
+    :handle-result="handleResult"
+    :edit-data="formData.userBackData"
+  />
+</template>
+```
+
+## ReCascader（异步级联）
+
+```vue
+<script setup lang="ts">
+import { ReCascader } from "@/components/ReCascader";
+
+const region = ref<string[]>([]);
+</script>
+
+<template>
+  <ReCascader v-model="region" :placeholder="$t('请选择')" />
+</template>
+```
+
+用法细节（懒加载、compare-config）以组件 props / `data-compare` 为准。
 
 ## ReIconPicker 图标选择器
 
+> **完整规范见 `icons` 模块**（命名规则、本地 SVG、菜单 `meta.icon`、UnoCSS、内网离线）。此处仅保留表单场景速览。
+
 ```vue
 <script setup lang="ts">
-import ReIconPicker from "@/components/ReIconPicker";
+import { ReIconPicker } from "@/components/ReIconPicker";
 
 const icon = ref("");
 </script>
 
 <template>
   <ReIconPicker v-model="icon" clearable />
+  <svg-icon v-if="icon" :name="icon" :size="18" />
 </template>
 ```
 
-- 默认支持本地图标、Element Plus、Remix Icon 三类。
-- 支持搜索、分页、自定义 `sources`。
-- 选中值存储为图标名称字符串。
+- 选中值用于 `svg-icon` 的 `name`（本地无冒号；ep/ri 多为 `i-ep:xxx` / `i-ri:xxx`）。
 
 ## ReSegmented 分段控制器
 
@@ -35,16 +118,14 @@ const active = ref(0);
 </script>
 
 <template>
-  <ReSegmented v-model="active" :options="options" @change="onChange" />
+  <ReSegmented v-model="active" :options="options" />
 </template>
 ```
 
-- `block`：宽度铺满父容器。
-- `resize`：内容变化时自动重算滑块位置。
-- `options` 支持 `icon`、`tip`、`disabled`。
-
 ## ReCheckCard 卡片选择
 
+依赖 `plus-pro-components@0.1.31`（缺则见文首安装命令）。
+
 ```vue
 <script setup lang="ts">
 import ReCheckCard from "@/components/ReCheckCard";
@@ -58,14 +139,11 @@ const options = [
 
 <template>
   <ReCheckCard v-model="value" :options="options" />
-  <ReCheckCard v-model="values" :options="options" multiple />
 </template>
 ```
 
 ## ReAnchor 锚点导航
 
-用于长表单/详情页模块跳转。
-
 ```vue
 <script setup lang="ts">
 import { ReAnchor } from "@/components/ReAnchor";
@@ -78,14 +156,12 @@ const modules = [
 
 <template>
   <ReAnchor :anchor-modules="modules" />
-
   <div id="baseInfo">...</div>
   <div id="contactInfo">...</div>
 </template>
 ```
 
-- 支持 `scrollContent` 指定滚动容器，用于弹窗场景。
-- `instanceId` 用于多实例区分相同 ID。
+弹窗内指定 `scrollContent`。
 
 ## ReCollapsible 可折叠面板
 
@@ -103,19 +179,14 @@ const collapsed = ref(false);
 </template>
 ```
 
-- 支持 `left` / `right` 位置。
-- 暴露 `toggle()` 与 `collapsed` 状态。
-
 ## 地址解析
 
-```vue
-<script setup lang="ts">
+```typescript
 import AddressParse, { Utils } from "address-parse";
 
 function parseAddress(text: string) {
   const [result] = AddressParse.parse(text);
   const codeArr = Utils.getTargetAreaListByCode("province", result.code, true);
-
   return {
     name: result.name,
     phone: result.mobile || result.phone,
@@ -125,13 +196,180 @@ function parseAddress(text: string) {
     areaCode: codeArr[2]?.code,
   };
 }
+```
+
+---
+
+## ReDialog 通用弹窗（必用）
+
+> 落点：`src/components/ReDialog`。基于 `el-dialog` 封装：居中、可拖拽、`destroy-on-close`、默认禁止点遮罩关闭、可选全屏切换、内容区 `el-scrollbar`。  
+> 样板参考：`src/views/table/base/index.vue`、`src/views/form/moreForm/MultiFormDialog.vue`。
+
+### Props / 插槽
+
+| 项 | 说明 |
+|---|---|
+| `v-model` / `modelValue` | 显隐 |
+| `title` | 标题文案（也可用 `#title` 插槽） |
+| `width` | 默认 `'50%'` |
+| `maxHeight` | 内容区滚动高度，默认 `500`（number 会拼 `px`） |
+| `fullscreen` | 是否显示右上角全屏按钮，默认 `true` |
+| 默认插槽 | 内容区（包在 scrollbar 内） |
+| `#footer` | 有则渲染底部操作区 |
+| `#title` | 自定义标题 |
+| 其它 attrs | 透传给 `el-dialog`（组件内部会剔除 `fullscreen` / `title` / `maxHeight`） |
+
+内置行为：`lock-scroll`、`draggable`、`destroy-on-close`、`close-on-click-modal=false`、自定义关闭/全屏图标（非默认 `show-close`）。
+
+### 列表页表单弹窗（黄金样板）
+
+```vue
+<script setup lang="ts">
+import type { FormInstance, FormRules } from "element-plus";
+import ReDialog from "@/components/ReDialog";
+import { message } from "@/utils/message";
+
+defineOptions({ name: "CustomerDialog" });
+
+const dialogVisible = ref(false);
+const title = ref("");
+const submitLoading = ref(false);
+const formRef = ref<FormInstance>();
+const formData = reactive({ name: "", status: 1 });
+
+const rules: FormRules = {
+  name: [{ required: true, message: "请输入名称", trigger: "blur" }],
+};
+
+function openCreate() {
+  title.value = "新增客户";
+  Object.assign(formData, { name: "", status: 1 });
+  dialogVisible.value = true;
+}
+
+function openEdit(row: { name: string; status: number }) {
+  title.value = "编辑客户";
+  Object.assign(formData, row);
+  dialogVisible.value = true;
+}
+
+async function onSubmit() {
+  const ok = await formRef.value?.validate().catch(() => false);
+  if (!ok) return;
+  submitLoading.value = true;
+  try {
+    // await saveApi(formData)
+    message("保存成功", { type: "success" });
+    dialogVisible.value = false;
+  } finally {
+    submitLoading.value = false;
+  }
+}
+
+defineExpose({ openCreate, openEdit });
+</script>
+
+<template>
+  <ReDialog v-model="dialogVisible" :title="title" width="560px" :max-height="420">
+    <el-form ref="formRef" :model="formData" :rules="rules" label-width="96px">
+      <el-form-item :label="$t('名称')" prop="name">
+        <el-input v-model="formData.name" />
+      </el-form-item>
+      <el-form-item :label="$t('状态')" prop="status">
+        <el-select v-model="formData.status" class="w-full">
+          <el-option :label="$t('启用')" :value="1" />
+          <el-option :label="$t('停用')" :value="0" />
+        </el-select>
+      </el-form-item>
+    </el-form>
+    <template #footer>
+      <el-button @click="dialogVisible = false">{{ $t("取 消") }}</el-button>
+      <el-button type="primary" :loading="submitLoading" @click="onSubmit">
+        {{ $t("确 定") }}
+      </el-button>
+    </template>
+  </ReDialog>
+</template>
+```
+
+### 大内容 / 多表单弹窗
+
+```vue
+<script setup lang="ts">
+import { ReDialog } from "@/components/ReDialog";
+
+const dialogVisible = ref(false);
 </script>
+
+<template>
+  <ReDialog
+    v-model="dialogVisible"
+    :title="$t('弹窗多表单')"
+    width="90%"
+    :max-height="600"
+  >
+    <!-- 内容区可嵌 ReAnchor + ReCollapsible；弹窗内锚点滚动容器传 scrollContent -->
+    <div class="min-h-400">...</div>
+    <template #footer>
+      <el-button @click="dialogVisible = false">{{ $t("取消") }}</el-button>
+      <el-button type="primary">{{ $t("确认保存") }}</el-button>
+    </template>
+  </ReDialog>
+</template>
+```
+
+### 约定
+
+1. 业务弹窗优先 `ReDialog`，不要直接写裸 `el-dialog`。
+2. 提交按钮必须有 `loading`，防止重复提交。
+3. 需要二次确认删除等：用 `ElMessageBox.confirm` / `message` 封装，不必为确认框再套一层 `ReDialog`。
+4. 弹窗内嵌锚点时指定 `scrollContent`（见上方 ReAnchor）。
+
+---
+
+## ReDialogResize 可拖拽缩放弹窗
+
+> 落点：`src/components/ReDialogResize`。在 `ReDialog` 外包一层边缘拖拽改宽高。  
+> **何时用**：用户需要手动拉大/缩小内容区（复杂表单、预览、对照编辑）。普通 CRUD 弹窗用 `ReDialog` 即可。
+
+### Props
+
+| 项 | 说明 |
+|---|---|
+| `v-model` / `title` / `fullscreen` | 同 `ReDialog`，透传 |
+| `initWidth` | 初始宽度（number，px），默认 `window.innerWidth / 2` |
+| `initHeight` | 初始内容高度（number，px），默认 `500` |
+| `minResizeWidth` / `minResizeHeight` | 缩放下限 |
+
+```vue
+<script setup lang="ts">
+import ReDialogResize from "@/components/ReDialogResize";
+
+const visible = ref(false);
+</script>
+
+<template>
+  <ReDialogResize
+    v-model="visible"
+    :title="$t('可缩放弹窗')"
+    :init-width="800"
+    :init-height="520"
+    :min-resize-width="560"
+    :min-resize-height="400"
+  >
+    <div>{{ $t("拖拽弹窗边缘可调整大小") }}</div>
+    <template #footer>
+      <el-button @click="visible = false">{{ $t("关闭") }}</el-button>
+    </template>
+  </ReDialogResize>
+</template>
 ```
 
-- 地址与姓名、手机之间建议用空格或逗号分隔，识别更准确。
+---
 
 ## 关键约定
 
-1. 图标选择器返回值直接用于 `svg-icon` 的 `name`。
-2. 分段控制器 `v-model` 为索引数字时使用响应式；传字符串需自行维护选中态。
-3. 锚点模块 ID 与 `refName` 保持一致，弹窗内指定 `scrollContent`。
+1. 业务弹窗用 `ReDialog`；要边缘缩放再用 `ReDialogResize`；勿业务页自研弹窗壳。
+2. 简单下拉用 `el-select`；搜索+分页用 `ReSelectQuery`。
+3. 树选用 `el-tree-select`；级联用 `ReCascader`。
+4. 变更对比场景配合 `compare-config`（见 `data-compare`）。

package/references/graph-relation.md

@@ -1,8 +1,18 @@
 # 知识图谱（relation-graph）
 
-## 依赖
+> 必须使用选型表中的 `relation-graph-vue3`，勿改用 D3 / vis.js 等同类库。按下列示例编写。
 
-`relation-graph-vue3` — 关系图谱/知识图谱可视化组件。
+## 依赖（缺则先装）
+
+| 包 | 版本 |
+|---|---|
+| `relation-graph-vue3` | `2.2.11` |
+
+```bash
+pnpm add relation-graph-vue3@2.2.11
+```
+
+先查 `package.json`；已存在则跳过安装。
 
 ## 页面结构
 
@@ -246,8 +256,3 @@ const legendConfig = ref([
 3. 图谱容器必须有明确高度（使用 `calc(100vh - ...)` 计算）。
 4. `setJsonData` 的回调中执行居中、缩放、高亮等初始化操作。
 5. 节点自定义样式通过 `#node` 插槽，class 根据 `data` 字段动态绑定。
-
-## 关联文件
-
-- [src/views/graph/index.vue](file:///e:/work/vue3-web-temp/src/views/graph/index.vue)
-- [src/api/graph.ts](file:///e:/work/vue3-web-temp/src/api/graph.ts)