ep-craft 0.1.42 → 0.2.0

package/dist-ai/components/select-v2.md

@@ -0,0 +1,193 @@
+# EpSelectV2
+
+`ep-select-v2` · form（表单） · `component:select-v2`
+
+## 摘要
+
+虚拟化选择器，适合海量选项渲染
+
+## 适用场景
+
+- 适用：数千条以上选项的下拉选择
+- 适用：需要保持流畅滚动的筛选器
+- 不适用：选项较少时使用 Select 更轻量
+
+## 关键词
+
+- 中文：虚拟化选择器、下拉、海量选项、表单
+- English: select-v2, select, v2, virtual-select, dropdown, form
+
+## 变体
+
+- size: large/default/small（按容器空间与信息密度选择尺寸）
+- state: disabled/loading（通过布尔属性切换禁用、加载或选中状态）
+- effect: dark/light（通过视觉修饰属性调整外观效果）
+
+## Props
+
+- allowCreate (boolean)：是否允许用户创建新条目（须配合 filterable）
+- autocomplete ('none' | 'both' | 'list' | 'inline'，默认 none)：原生 autocomplete 属性
+- automaticDropdown (boolean)：对于不可搜索的选择器，获取焦点后是否自动弹出下拉面板
+- clearable (boolean)：是否可以清空选项
+- clearIcon (string | Component，默认 CircleClose)：自定义清空图标
+- effect ('dark' | 'light'，默认 light)：tooltip 主题
+- collapseTags (boolean)：多选时是否将选中值折叠为计数标签
+- collapseTagsTooltip (boolean)：多选折叠时是否在悬停计数标签时展示全部选中值
+- tagTooltip (TagTooltipProps，默认 {})：折叠标签 tooltip 的配置对象
+- maxCollapseTags (number，默认 1)：多选折叠时最多显示的标签数量（须配合 collapse-tags）
+- defaultFirstOption (boolean)：按下回车是否选择第一个匹配项
+- disabled (boolean，默认 false)：是否禁用
+- estimatedOptionHeight (number，默认 见文档)：可变高度选项的估算项高
+- filterable (boolean)：是否可搜索
+- filterMethod ((query: string) => void)：自定义筛选方法（须配合 filterable）
+- height (number，默认 274)：下拉面板高度（按每项约 34px 计算）
+- itemHeight (number，默认 34)：选项列表单项高度
+- id (string)：原生 id 属性
+- loading (boolean)：是否正在从远程获取数据
+- loadingText (string)：远程加载时显示的文字
+- modelValue（别名 v-model） (string | number | boolean | object | any[]，默认 见文档)：绑定值
+- multiple (boolean)：是否多选
+- multipleLimit (number，默认 0)：多选时可被选择的最大数目（0 为不限制）
+- name (string)：原生 name 属性
+- noDataText (string)：无选项时显示的文字（也可用 empty 插槽）
+- noMatchText (string)：筛选无匹配时显示的文字（也可用 empty 插槽）
+- remoteMethod ((query: string) => void)：远程搜索方法
+- reserveKeyword (boolean，默认 true)：多选且可搜索时选中后是否保留关键字
+- options (Array，必填)：选项数据数组，字段名（value / label / disabled / options）可通过 props 自定义
+- placeholder (string)：占位符
+- teleported (boolean，默认 true)：是否将下拉列表插入至 body 元素
+- persistent (boolean，默认 true)：下拉菜单关闭后是否销毁
+- popperClass (string)：下拉框的类名
+- popperStyle (string | object，默认 见文档)：下拉框的自定义样式
+- popperOptions (object，默认 {})：popper.js 参数
+- remote (boolean)：是否为远程搜索
+- debounce (number，默认 300)：远程搜索去抖延迟（毫秒）
+- size ('large' | 'default' | 'small')：输入框尺寸
+- props (object & { value: string; label: string; disabled: string; options: string }，默认 { value: 'value', label: 'label', disabled: 'disabled', options: 'options' })：配置选项字段映射（value / label / disabled / options 的键名）
+- valueKey (string，默认 value)：作为 value 唯一标识的键名
+- scrollbarAlwaysOn (boolean)：是否始终显示下拉滚动条
+- validateEvent (boolean，默认 true)：是否触发表单验证
+- offset (number，默认 12)：下拉框出现的偏移量
+- remoteShowSuffix (boolean)：远程搜索时是否显示后缀图标
+- showArrow (boolean，默认 true)：是否显示下拉箭头
+- placement (Placement，默认 bottom-start)：下拉框出现的位置
+- fallbackPlacements (Placement[]，默认 ['bottom-start', 'top-start', 'right', 'left'])：下拉框可能出现的备用位置列表
+- tagType ('success' | 'info' | 'warning' | 'danger'，默认 info)：标签类型
+- tagEffect ('dark' | 'light' | 'plain'，默认 light)：标签主题
+- tabindex (string | number，默认 0)：输入框的 tabindex
+- appendTo (string | HTMLElement)：下拉列表挂载到哪个元素
+- fitInputWidth (boolean | number，默认 true)：下拉框宽度是否与输入框一致
+- suffixIcon (string | Component，默认 ArrowDown)：自定义后缀图标
+- floatLabel (boolean，默认 false)：是否启用浮动标签（Material 风格），聚焦、展开虚拟化下拉或有值时占位文本上浮；多选折叠为计数标签时仍保持上浮
+- emptyValues (any[])：视为空值的值列表
+- valueOnClear (string | number | boolean | (() => string | number | boolean)，默认 undefined)：清空时写入的值
+- ariaLabel (string)：原生 aria-label 属性
+- ariaLabelledby (string)：原生 aria-labelledby 属性；显式传入时优先于浮动标签自动关联的文本
+
+## Events
+
+- update:modelValue((value: any))：绑定值变化时触发
+- change((value: any))：选中值发生变化时触发
+- endReached((direction: 'top' | 'bottom' | 'left' | 'right'))：下拉列表滚动到边界时触发（用于远程加载更多）
+- removeTag((tagValue: any))：多选模式下移除 tag 时触发
+- visibleChange((visible: boolean))：下拉框出现/隐藏时触发
+- focus((event: FocusEvent))：当 input 获得焦点时触发
+- blur((event: FocusEvent))：当 input 失去焦点时触发
+- clear(())：可清空的单选模式下用户点击清空按钮时触发
+
+## Slots
+
+- default：下拉列表内容（选项列表，作用域含 item / index 等）
+- prefix：Select 组件头部内容
+- empty：无选项时的列表
+- label：自定义选中项标签
+- tag：多选模式下自定义 tag 内容
+- header：下拉列表顶部的内容
+- footer：下拉列表底部的内容
+- loading：自定义加载中内容
+
+## Exposes
+
+- focus(() => void)：使选择器的输入框获取焦点
+- blur(() => void)：使选择器的输入框失去焦点，并隐藏下拉框
+
+## 关系
+
+- 子级：EpOption、EpOptionGroup
+- 常用组合：EpSelectV2 + EpOption、EpSelectV2 + EpOptionGroup
+
+## 视觉提示
+
+- 形状：矩形输入框
+- 密度：中等
+- 插槽内容：default：下拉列表内容（选项列表，作用域含 item / index 等）；prefix：Select 组件头部内容；empty：无选项时的列表
+- CSS 变量：--el-border-color、--el-border-radius-base、--el-color-primary、--el-font-size-base
+
+## 示例
+
+### 基础选择
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { EpSelectV2 } from 'ep-craft'
+
+const value = ref('')
+const options = [
+  { label: '选项一', value: 'one' },
+  { label: '选项二', value: 'two' },
+]
+</script>
+
+<template>
+  <ep-select-v2 v-model="value" :options="options" placeholder="请选择" />
+</template>
+```
+
+### 可搜索
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { EpSelectV2 } from 'ep-craft'
+
+const value = ref('')
+const options = Array.from({ length: 100 }, (_, index) => ({
+  label: `选项 ${index + 1}`,
+  value: index + 1,
+}))
+</script>
+
+<template>
+  <ep-select-v2 v-model="value" :options="options" filterable placeholder="搜索选项" />
+</template>
+```
+
+### 多选
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { EpSelectV2 } from 'ep-craft'
+
+const value = ref([])
+const options = [
+  { label: '选项一', value: 'one' },
+  { label: '选项二', value: 'two' },
+  { label: '选项三', value: 'three' },
+]
+</script>
+
+<template>
+  <ep-select-v2 v-model="value" :options="options" multiple collapse-tags />
+</template>
+```
+
+## 相关条目
+
+- EpOption
+- EpOptionGroup
+
+---
+
+ep-craft 0.2.0