@bytenew/bn-bus-ui 1.1.461 → 1.1.463

package/packages/BnCascader/BnCascader.vue

@@ -0,0 +1,543 @@
+<!--
+  @Description: 级联选择器（完整版）：选择框触发器 + 悬浮面板（BnCascaderPanel）
+  @Features:
+    - 点击选择框弹出级联面板，单选选中后自动收起面板
+    - 单选展示完整路径文本；多选展示 tag 列表，支持折叠与 tooltip
+    - 支持清空、单 tag 删除、禁用、三种尺寸（large / default / small）
+    - 面板相关能力（远程加载、lazy、列虚拟滚动等）均透传自 BnCascaderPanel
+  @Usage:
+    基础：v-model 绑定选中值，options 传入本地树
+    多选折叠：multiple collapse-tags :max-collapse-tags="3"
+    自定义面板顶栏：#top 插槽（透传给 BnCascaderPanel）
+  @modelValue 格式（与 BnCascaderPanel 一致）:
+    单选 labelInValue=false  → [1, 2, 3]
+    单选 labelInValue=true   → [{id:1, title:'...'}, ...]
+    多选 labelInValue=false  → [[1,2,3], [4,5,6]]
+    多选 labelInValue=true   → [[{id:1,...},...], [...]]
+  @Emits:
+    update:modelValue  选中值变化
+    change             选中值变化（与 update 同步触发）
+    visible-change     下拉面板显隐变化
+  @Slots:
+    top                面板工具栏扩展区（如清空按钮），透传至 BnCascaderPanel
+  @VERSION: 1.0
+-->
+<template>
+  <!-- el-popover 承载下拉面板，trigger 为自定义选择框 -->
+  <el-popover
+    ref="popoverRef"
+    :placement="placement"
+    trigger="click"
+    :show-arrow="false"
+    :show-after="0"
+    :hide-after="0"
+    transition="BnCascader-no-transition"
+    :disabled="disabled"
+    :teleported="teleported"
+    :popper-class="`BnCascader-popper ${popperClass}`.trim()"
+    @show="handlePopoverShow"
+    @hide="handlePopoverHide"
+  >
+    <!-- 触发器：模拟 Element Plus Cascader 选择框 -->
+    <template #reference>
+      <div class="BnCascader__trigger" :class="triggerClass" @mouseenter="hovering = true" @mouseleave="hovering = false">
+        <!-- 选中内容区 -->
+        <div class="BnCascader__selection">
+          <!-- 未选中：占位文案 -->
+          <span v-if="isEmptyValue" class="BnCascader__placeholder">{{ placeholder }}</span>
+
+          <!-- 单选：展示整条路径，如 Guide / Navigation / Top Navigation -->
+          <span
+            v-else-if="!multiple"
+            class="BnCascader__single-label"
+            :title="singleDisplayText"
+          >{{ singleDisplayText }}</span>
+
+          <!-- 多选：tag 列表，支持 collapseTags 折叠 -->
+          <div v-else class="BnCascader__tags">
+            <span
+              v-for="tag in visibleTags"
+              :key="tag.index"
+              class="BnCascader__tag"
+            >
+              <span class="BnCascader__tag-text" :title="tag.label">{{ tag.label }}</span>
+              <!-- 点击 x 删除单个 tag，不影响面板展开状态 -->
+              <i
+                v-if="!disabled"
+                class="BnCascader__tag-close bnUIcon bnUIcon-close"
+                @click.stop="removeTag(tag.index)"
+              />
+            </span>
+            <!-- 折叠时展示 +N，hover 可查看被折叠的全部 tag -->
+            <el-tooltip
+              v-if="collapsedCount > 0"
+              :disabled="!collapseTagsTooltip"
+              effect="dark"
+              placement="top"
+            >
+              <template #content>
+                <div class="BnCascader__collapse-tooltip">
+                  <el-scrollbar max-height="320px">
+                    <div v-for="tag in collapsedTags" :key="tag.index">{{ formatDisplayText(tag.path) }}</div>
+                  </el-scrollbar>
+                </div>
+              </template>
+              <span class="BnCascader__tag BnCascader__tag--collapse">+ {{ collapsedCount }}</span>
+            </el-tooltip>
+          </div>
+        </div>
+
+        <!-- 右侧图标：hover 有值且 clearable 时清空替换箭头，否则展示下拉箭头 -->
+        <span class="BnCascader__suffix">
+          <i
+            v-if="showClear"
+            class="BnCascader__clear bnUIcon bnUIcon-clear"
+            @click.stop="clearValue"
+          />
+          <i
+            v-else
+            class="BnCascader__arrow bnUIcon bnUIcon-down"
+            :class="{ 'is-reverse': popoverVisible }"
+          />
+        </span>
+      </div>
+    </template>
+
+    <!-- 级联面板：props 透传 + v-model 双向绑定   -->
+    <BnCascaderPanel
+      ref="panelRef"
+      v-bind="$props"
+      v-model="panelValueModel"
+      @change="handleChange"
+      @changeCheckToLast="$emit('update:checkToLast',$event)"
+      @loadOver="loadOption = true"
+      @close="handlePanelClose">
+      <template v-if="$slots.top" #top>
+        <slot name="top"/>
+      </template>
+    </BnCascaderPanel>
+  </el-popover>
+</template>
+
+<script>
+import {formatPathDisplay, isEmptyValue as checkEmptyValue} from './cascaderDisplay.js';
+export default {
+  name: 'BnCascader',
+  props: {
+    /** 绑定值，格式见文件头 @modelValue 说明 */
+    modelValue: {},
+    /** 本地级联选项树，默认 [{ id, title, children }] */
+    options: { type: Array, default: () => [] },
+    /** 是否多选 */
+    multiple: Boolean,
+    /** 选项字段映射，如 { value: 'id', label: 'title', children: 'children' } */
+    optionProps: { default: () => ({}) },
+    /** labelInValue 为 true 时，返回对象保留的字段列表 */
+    valueProps: { type: Array },
+    /** true 返回完整对象路径，false 返回 id 路径 */
+    labelInValue: { type: Boolean, default: true },
+    /** 是否禁用 */
+    disabled: { type: Boolean, default: false },
+    /** 「选到最后一级」：多选勾选父级时选中所有叶子；单选开启后仅叶子可选 */
+    checkToLast: { default: false },
+    /** 是否隐藏面板内「选到最后一级」开关 */
+    hideCheckToLast: { type: Boolean, default: false },
+    /** 远程请求方法，签名 (url, data) => Promise */
+    postFunc: Function,
+    /** 远程请求附加参数 */
+    postData: { type: Object, default: () => ({}) },
+    /** 远程接口路径 */
+    pathUrl: { type: String, default: '' },
+    /** 远程模式：tree 一次拉树 / lazy 按级懒加载 */
+    remoteMode: { type: String, default: 'tree' },
+    /** lazy 模式请求体中的层级字段名 */
+    lazyLevelKey: { type: String, default: 'level' },
+    /** lazy 模式起始层级（默认 1，展开第一层时传 2） */
+    lazyLevelStart: { type: Number, default: 1 },
+    /** lazy 模式叶子节点标识字段 */
+    leafKey: { type: String, default: 'leaf' },
+    /** 远程 tree 模式是否在 mounted 时自动初始化 */
+    isInitOptions: { type: Boolean, default: true },
+    /** 单列超过该数量启用虚拟滚动 */
+    virtualThreshold: { type: Number, default: 40 },
+    /** 面板每列最大高度（px） */
+    columnHeight: { type: Number, default: 300 },
+    /** 未选中时的占位文案 */
+    placeholder: { type: String, default: '请选择' },
+    /** 是否显示清空按钮（hover 时替换箭头图标） */
+    clearable: { type: Boolean, default: true },
+    /** 路径各级之间的分隔符 */
+    separator: { type: String, default: ' / ' },
+    /** 单选是否展示完整层级路径 */
+    showAllLevels: { type: Boolean, default: true },
+    /** 多选 tag 是否折叠超出部分 */
+    collapseTags: { type: Boolean, default: false },
+    /** 折叠 tag 的 +N 是否启用 tooltip 展示全部 */
+    collapseTagsTooltip: { type: Boolean, default: true },
+    /** collapseTags 为 true 时，最多展示几个 tag */
+    maxCollapseTags: { type: Number, default: 1 },
+    /** popover 弹出位置，同 el-popover placement */
+    placement: { type: String, default: 'bottom-start' },
+    /** 面板是否 teleport 到 body */
+    teleported: { type: Boolean, default: true },
+    /** 面板 popper 附加 class */
+    popperClass: { type: String, default: '' },
+    /** 选择框尺寸：large / default / small */
+    size: {
+      type: String,
+      default: 'default',
+      validator: v => ['large', 'default', 'small'].includes(v)
+    }
+  },
+  emits: ['update:modelValue', 'change', 'visible-change','update:checkToLast'],
+  data() {
+    return {
+      /** popover 显隐本地状态，用于触发器样式与 visible-change */
+      popoverVisible: false,
+      /** 鼠标是否悬停在触发器上，用于控制清空按钮显示 */
+      hovering: false,
+      // 面板是否远程加载选项
+      loadOption: false,
+    };
+  },
+  computed: {
+    /** 路径展示相关配置，传给 cascaderDisplay 工具函数 */
+    displayOptions() {
+      return {
+        labelInValue: this.labelInValue,
+        optionProps: this.optionProps,
+        options: this.displayRootOptions,
+        separator: this.separator,
+        showAllLevels: this.showAllLevels
+      };
+    },
+    /** 回显解析用的选项树：优先 Panel 已加载数据（含远程 lazy），否则用 props.options */
+    displayRootOptions() {
+      const panelOptions = this.$refs.panelRef?.rootOptions;
+      if (Array.isArray(panelOptions) && panelOptions.length) {
+        return panelOptions;
+      }
+      return this.options || [];
+    },
+    /** 当前值是否为空（单选 null/[]，多选 []） */
+    isEmptyValue() {
+      return checkEmptyValue(this.modelValue, {
+        multiple: this.multiple,
+        labelInValue: this.labelInValue
+      });
+    },
+    /** 单选模式下触发器展示的完整路径文本 */
+    singleDisplayText() {
+      return this.formatDisplayText(this.modelValue);
+    },
+    /** 多选模式下全部 tag 数量 */
+    selectedCount() {
+      return Array.isArray(this.modelValue) ? this.modelValue.length : 0;
+    },
+    /** 多选模式下当前可见 tag（受 collapseTags / maxCollapseTags 影响，仅格式化可见项） */
+    visibleTags() {
+      if (!this.selectedCount) {
+        return [];
+      }
+      const end = this.collapseTags
+          ? Math.min(this.maxCollapseTags, this.selectedCount)
+          : this.selectedCount;
+      const tags = [];
+      for (let index = 0; index < end; index++) {
+        const path = this.modelValue[index];
+        const label = this.formatDisplayText(path);
+        if (label) {
+          tags.push({ index, label, path });
+        }
+      }
+      return tags;
+    },
+    /** 多选模式下被折叠隐藏的 tag 列表（仅保留 path，展示时再格式化） */
+    collapsedTags() {
+      if (!this.collapseTags || this.selectedCount <= this.maxCollapseTags) {
+        return [];
+      }
+      return this.modelValue.slice(this.maxCollapseTags).map((path, offset) => ({
+        index: this.maxCollapseTags + offset,
+        path
+      }));
+    },
+    /** 被折叠的 tag 数量（+N 中的 N） */
+    collapsedCount() {
+      if (!this.collapseTags || this.selectedCount <= this.maxCollapseTags) {
+        return 0;
+      }
+      return this.selectedCount - this.maxCollapseTags;
+    },
+    /**
+     * Panel v-model 代理：读 modelValue prop，写时 emit 并在单选时关闭面板
+     */
+    panelValueModel: {
+      get() {
+        return this.modelValue;
+      },
+      set(value) {
+        this.handleValueUpdate(value);
+      }
+    },
+    /** 是否展示清空图标：可清空 + 未禁用 + 有值 + 鼠标悬停 */
+    showClear() {
+      return this.clearable && !this.disabled && !this.isEmptyValue && this.hovering;
+    },
+    /** 触发器动态 class：禁用 / 聚焦 / 多选 / 尺寸 */
+    triggerClass() {
+      return {
+        'is-disabled': this.disabled,
+        'is-focus': this.popoverVisible,
+        'is-multiple': this.multiple,
+        [`BnCascader__trigger--${this.size}`]: true
+      };
+    }
+  },
+  watch: {
+    /** 面板显隐变化时向外抛出 visible-change */
+    popoverVisible(val) {
+      this.$emit('visible-change', val);
+      if (!val) {
+        this.$refs.panelRef?.clearSearch?.();
+      }
+    }
+  },
+  methods: {
+    /**
+     * 格式化单条路径展示文本
+     * labelInValue=false 时优先从 Panel 已加载树按 value 解析 title，远程 lazy 同样适用
+     */
+    formatDisplayText(path) {
+      if (!this.labelInValue && (!this.pathUrl || this.loadOption)) {
+        const panelText = this.$refs.panelRef?.getPathDisplayText?.(path, {
+          separator: this.separator,
+          showAllLevels: this.showAllLevels
+        });
+        if (panelText) {
+          return panelText;
+        }
+      }
+      return formatPathDisplay(path, this.displayOptions);
+    },
+    /** popover 打开：同步状态、聚焦搜索；禁用时立即关闭 */
+    handlePopoverShow() {
+      if (this.disabled) {
+        this.$refs.popoverRef?.hide?.();
+        return;
+      }
+      this.popoverVisible = true;
+      this.$refs.panelRef?.focusSearchInput?.();
+    },
+    /** popover 关闭：同步本地显隐状态 */
+    handlePopoverHide() {
+      this.popoverVisible = false;
+    },
+    /**
+     * Panel 选中值更新
+     * @param {*} value 新选中值
+     */
+    handleValueUpdate(value) {
+      this.$emit('update:modelValue', value);
+    },
+    /** 单选选中后关闭面板；使用位置：Panel @close */
+    handlePanelClose() {
+      if (this.multiple) {
+        return;
+      }
+      this.$refs.popoverRef?.hide?.();
+    },
+    /** 透传 Panel change 事件 */
+    handleChange(value) {
+      this.$emit('change', value);
+    },
+    /** 点击清空图标：重置为 empty 并触发 change */
+    clearValue() {
+      if (this.disabled) {
+        return;
+      }
+      const empty = this.multiple ? [] : (this.labelInValue ? null : []);
+      this.$emit('update:modelValue', empty);
+      this.$emit('change', empty);
+    },
+    /**
+     * 删除多选 tag
+     * @param {Number} index tag 在 modelValue 数组中的下标
+     */
+    removeTag(index) {
+      if (this.disabled || !this.multiple || !Array.isArray(this.modelValue)) {
+        return;
+      }
+      const next = [...this.modelValue];
+      next.splice(index, 1);
+      this.$emit('update:modelValue', next);
+      this.$emit('change', next);
+    }
+  }
+};
+</script>
+
+<!-- popover 全局样式：去掉默认 padding，宽度随面板内容自适应 -->
+<style>
+.BnCascader-popper.el-popover.el-popper {
+  padding: 0 !important;
+  width: auto !important;
+  min-width: 0 !important;
+}
+
+/* 禁用 popover 显隐过渡，避免打开/关闭延迟 */
+.BnCascader-no-transition-enter-active,
+.BnCascader-no-transition-leave-active {
+  transition: none !important;
+}
+</style>
+
+<style scoped lang="scss">
+@import '../font/iconfont.css';
+
+/* 触发器主体：对齐 Element Plus Select/Cascader 外观 */
+.BnCascader__trigger {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  width: 100%;
+  min-height: 32px;
+  padding: 1px 30px 1px 11px;
+  box-sizing: border-box;
+  font-size: 14px;
+  line-height: 24px;
+  color: #606266;
+  background-color: #fff;
+  border: 1px solid #dcdfe6;
+  border-radius: 4px;
+  cursor: pointer;
+
+  &:hover:not(.is-disabled) {
+    border-color: #c0c4cc;
+  }
+
+  &.is-focus:not(.is-disabled) {
+    border-color: #409eff;
+  }
+
+  &.is-disabled {
+    color: #a8abb2;
+    background-color: #f5f7fa;
+    border-color: #e4e7ed;
+    cursor: not-allowed;
+  }
+
+  &--large {
+    min-height: 40px;
+    font-size: 14px;
+  }
+
+  &--small {
+    min-height: 24px;
+    font-size: 12px;
+    padding-top: 0;
+    padding-bottom: 0;
+  }
+}
+
+/* 选中内容区，占据除 suffix 外的剩余宽度 */
+.BnCascader__selection {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.BnCascader__placeholder {
+  color: #a8abb2;
+}
+
+/* 单选路径文本溢出省略 */
+.BnCascader__single-label {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* 多选 tag 容器 */
+.BnCascader__tags {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 6px;
+  padding: 2px 0;
+}
+
+.BnCascader__tag {
+  display: inline-flex;
+  align-items: center;
+  max-width: 100%;
+  height: 24px;
+  padding: 0 8px;
+  font-size: 12px;
+  color: #909399;
+  background: #f0f2f5;
+  border-radius: 4px;
+  box-sizing: border-box;
+
+  &--collapse {
+    padding: 0 8px;
+    cursor: default;
+    background: #f0f2f5;
+  }
+}
+
+.BnCascader__tag-text {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.BnCascader__tag-close {
+  margin-left: 4px;
+  font-size: 12px;
+  color: #909399;
+  cursor: pointer;
+  border-radius: 50%;
+  flex-shrink: 0;
+
+  &:hover {
+    color: #409eff;
+    background: #ecf5ff;
+  }
+}
+
+/* 右侧 suffix：清空 / 箭头互斥展示，固定宽度不占双图标空间 */
+.BnCascader__suffix {
+  position: absolute;
+  top: 50%;
+  right: 8px;
+  display: inline-flex;
+  align-items: center;
+  transform: translateY(-50%);
+  color: #a8abb2;
+}
+
+.BnCascader__clear {
+  font-size: 14px;
+  cursor: pointer;
+
+  &:hover {
+    color: #909399;
+  }
+}
+
+.BnCascader__arrow {
+  font-size: 12px;
+
+  &.is-reverse {
+    transform: rotate(180deg);
+  }
+}
+
+/* 折叠 tag tooltip 内容 */
+.BnCascader__collapse-tooltip {
+  max-width: 280px;
+  line-height: 1.6;
+}
+</style>