vue2-filter-type-ysy01

Vue2 通用下拉筛选组件（基于 Element UI），支持「默认选项/排除选项/自定义选项/精准定位」，适配多场景复用，交互流畅（选中高亮、点击自动关弹窗）。

🔥 核心疑问：FilterType.install 作用解析

这是 Vue 组件全局注册的标准写法，核心是让组件支持「全项目复用」，不用每个页面都手动引入：

// 组件全局注册的核心逻辑
FilterType.install = function(Vue) {
  // 1. 注册全局组件：组件名映射为 <filter-type>（符合 HTML 标签规范）
  Vue.component(FilterType.name || 'FilterType', FilterType);
};

• 核心作用：执行 Vue.use(FilterType) 后，全项目任意组件都能直接用 <filter-type> 标签，不用再写 import 和 components 局部注册
• 使用场景：多页面需要用这个筛选组件时，全局注册一次更高效；单页面用可直接局部引入（下文有示例）
• 为什么是 <filter-type>？：Vue 推荐组件标签用「kebab-case（短横线命名）」，注册的 FilterType 会自动映射为这个标签名

📌 组件特性

1. 灵活筛选：支持「排除指定选项」「显示指定选项」「自定义全量选项」三种模式
2. 交互友好：选中项高亮、点击选项自动关闭弹窗、支持弹窗位置/宽度自定义
3. 兼容复用：支持全局注册（多页面）和局部引入（单页面），适配不同项目结构
4. 默认兜底：无筛选条件时显示内置选项，无选中项时默认选中第一个

📦 安装 & 依赖

1. 依赖要求（必须满足）

组件基于 Element UI 开发，使用前需确保项目已引入以下依赖：

• Vue 2.5.2+
• Element UI 2.13.0+（需引入组件和样式）

2. 简化安装命令

# 推荐：npm 安装（npm 5.0+ 无需 --save，默认写入依赖）
npm i vue2-filter-type-ysy01

# 可选：yarn 安装（效果一样）
yarn add vue2-filter-type-ysy01

3. 依赖引入示例（main.js）

如果项目还没引入 Element UI，需在 main.js 中补充：

// main.js
import Vue from 'vue';
import ElementUI from 'element-ui'; // 引入 Element UI 组件
import 'element-ui/lib/theme-chalk/index.css'; // 引入 Element UI 样式（必须）
Vue.use(ElementUI); // 注册 Element UI

🚀 快速开始（2种引入方式）

方式1：全局注册（推荐多页面复用）

适合项目中多个页面需要用这个筛选组件，一次注册全项目可用：

// main.js（项目入口文件）
import Vue from 'vue';
import App from './App.vue';
import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';
// 1. 引入我们的筛选组件
import FilterType from 'vue2-filter-type-ysy01';

// 2. 注册依赖和组件
Vue.use(ElementUI);
Vue.use(FilterType); // 全局注册，现在任意组件都能直接用 <filter-type>

new Vue({
  el: '#app',
  render: h => h(App)
});

全局注册后使用示例（任意组件中直接写标签）：

<template>
  <div>
    <!-- 无需 import，直接使用 -->
    <filter-type @select="handleSelect" />
  </div>
</template>

<script>
export default {
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected); // { value: 'xxx', name: 'xxx' }
    }
  }
};
</script>

方式2：局部注册（单页面使用）

适合仅单个页面需要用，不用全局注册污染环境：

<template>
  <div>
    <!-- 局部引入后使用 -->
    <filter-type @select="handleSelect" />
  </div>
</template>

<script>
// 1. 仅在当前页面引入组件（不用在 main.js 注册）
import FilterType from 'vue2-filter-type-ysy01';

export default {
  // 2. 局部注册组件
  components: { FilterType },
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected);
    }
  }
};
</script>

📝 全场景使用示例（复制即用）

🔹 示例1：基础用法（默认选项）

显示组件内置的5个选项（已更新为：全部数据、我负责的、我创建的、共享给我的、我共享的）：

<template>
  <div style="padding: 20px;">
    <filter-type @select="handleSelect" />
  </div>
</template>

<script>
import FilterType from 'vue2-filter-type-ysy01';

export default {
  components: { FilterType },
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected);
      // 输出示例：{ value: 'all-datas', name: '全部数据' }
      // 业务逻辑：this.loadTable({ type: selected.value });
    }
  }
};
</script>

组件内置默认选项： | value | name | |----------------|------------| | all-datas | 全部数据 | | my-responsible | 我负责的 | | my-create | 我创建的 | | shared-to-me | 共享给我的 | | shared-by-me | 我共享的 |

🔹 示例2：排除指定选项（excludeOptions）

排除不需要的选项，示例：排除「我共享的」和「共享给我的」：

<template>
  <div style="padding: 20px;">
    <filter-type
      :exclude-options="['shared-by-me', 'shared-to-me']"
      @select="handleSelect"
    />
  </div>
</template>

<script>
import FilterType from 'vue2-filter-type-ysy01';

export default {
  components: { FilterType },
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected);
      // 可选选项：全部数据、我负责的、我创建的
    }
  }
};
</script>

🔹 示例3：只显示指定选项（visibleOptions）

精准显示指定选项，示例：只显示「全部数据」和「我负责的」：

<template>
  <div style="padding: 20px;">
    <filter-type
      :visible-options="['all-datas', 'my-responsible']"
      @select="handleSelect"
    />
  </div>
</template>

<script>
import FilterType from 'vue2-filter-type-ysy01';

export default {
  components: { FilterType },
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected);
    }
  }
};
</script>

🔹 示例4：自定义全量选项（customAllOptions）

覆盖内置选项，自定义业务所需选项：

<template>
  <div style="padding: 20px;">
    <filter-type
      :custom-all-options="customOptions"
      @select="handleSelect"
    />
  </div>
</template>

<script>
import FilterType from 'vue2-filter-type-ysy01';

export default {
  components: { FilterType },
  data() {
    return {
      customOptions: [
        { value: 'all', name: '全部事项' },
        { value: 'pending', name: '待处理' },
        { value: 'completed', name: '已完成' }
      ]
    };
  },
  methods: {
    handleSelect(selected) {
      console.log('选中自定义选项：', selected);
    }
  }
};
</script>

🔹 示例5：设置默认选中项（defaultSelected）

页面加载时默认选中「全部数据」（对应value：all-datas）：

<template>
  <div style="padding: 20px;">
    <filter-type
      default-selected="all-datas"
      @select="handleSelect"
    />
  </div>
</template>

<script>
import FilterType from 'vue2-filter-type-ysy01';

export default {
  components: { FilterType },
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected);
      // 页面初始显示：全部数据
    }
  }
};
</script>

🔹 示例6：自定义弹窗位置和宽度

设置弹窗显示在顶部，宽度150px：

<template>
  <div style="padding: 20px;">
    <filter-type
      placement="top"
      width="150"
      @select="handleSelect"
    />
  </div>
</template>

<script>
import FilterType from 'vue2-filter-type-ysy01';

export default {
  components: { FilterType },
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected);
    }
  }
};
</script>

支持的placement值：top/bottom/left/right/top-start等Element UI标准位置

🔹 示例7：修改触发方式（trigger）

改为鼠标悬浮触发弹窗：

<template>
  <div style="padding: 20px;">
    <filter-type
      trigger="hover"
      @select="handleSelect"
    />
  </div>
</template>

<script>
import FilterType from 'vue2-filter-type-ysy01';

export default {
  components: { FilterType },
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected);
    }
  }
};
</script>

🔹 示例8：组合传参（多属性同时使用）

默认选中「我创建的」+ 排除「我共享的」+ 宽度120px + 弹窗在右侧：

<template>
  <div style="padding: 20px;">
    <filter-type
      default-selected="my-create"
      :exclude-options="['shared-by-me']"
      width="120"
      placement="right"
      @select="handleSelect"
    />
  </div>
</template>

<script>
import FilterType from 'vue2-filter-type-ysy01';

export default {
  components: { FilterType },
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected);
      this.$refs.table.loadTable({ filterType: selected.value });
    }
  }
};
</script>

🎨 样式自定义（覆盖默认样式）

通过深度选择器修改样式，适配项目设计：

<template>
  <div style="padding: 20px;">
    <filter-type class="custom-filter" @select="handleSelect" />
  </div>
</template>

<script>
import FilterType from 'vue2-filter-type-ysy01';

export default {
  components: { FilterType },
  methods: {
    handleSelect(selected) {
      console.log('选中结果：', selected);
    }
  }
};
</script>

<style scoped>
/* 修改触发按钮样式 */
::v-deep .custom-filter .trigger {
  background-color: #f0f9ff;
  color: #1890ff;
  border: 1px solid #91d5ff;
}

/* 修改选中项样式 */
::v-deep .custom-filter .selected {
  color: #096dd9;
  background-color: #e6f7ff !important;
  font-weight: 600;
}
</style>

📚 完整Props说明

| Prop 名称 | 类型 | 默认值 | 说明 | |------------------|--------------|--------------|----------------------------------------------------------------------| | visibleOptions | Array | [] | 精准显示的选项value数组（优先级高于excludeOptions） | | excludeOptions | Array | [] | 需排除的选项value数组（仅visibleOptions为空时生效） | | customAllOptions | Array | [] | 自定义全量选项（格式：[{value, name}]），覆盖内置选项 | | defaultSelected | String | '' | 默认选中项的value（需在选项列表中存在，默认选中第一个） | | width | String/Number| '90' | 弹窗宽度（数字转px，字符串支持px/%） | | placement | String | 'bottom' | 弹窗位置（Element UI标准位置，如top/right） | | trigger | String | 'click' | 触发方式：click/hover/focus |

🎯 事件说明

| 事件名称 | 触发时机 | 回调参数 | 说明 | |----------|----------------|------------------------------|--------------------| | select | 点击选项时触发 | 选中项对象 {value, name} | 向父组件传递选中结果 |

❌ 常见问题解决

1. 组件报错：检查Element UI是否引入（含样式），版本是否符合要求
2. 默认选中不生效：确认defaultSelected的value在筛选后的选项中存在
3. 样式覆盖失败：必须用深度选择器::v-deep，且给组件加自定义类名
4. 筛选不生效：visibleOptions和excludeOptions不能同时使用，优先走visibleOptions