# ldesign-select

**Repository Path**: ldesign-v1/ldesign-select

## Basic Information

- **Project Name**: ldesign-select
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @ldesign/select

下拉选择器组件库 — 框架无关的核心库 + Vue 3 适配层

## 📋 项目简介

`@ldesign/select` 是一个功能完整的下拉选择器组件库，采用 **Core + Vue** 双层架构：
- `@ldesign/select-core` — 框架无关的核心逻辑（状态机 + DOM 渲染器）
- `@ldesign/select-vue` — Vue 3 组件封装

## ✨ 核心特性

### 📝 选择模式
- **单选模式** — 标准下拉单选
- **多选模式** — 标签式多选，支持 maxTagCount
- **树形选择** — 多层级树形结构

### 🔍 搜索
- **本地搜索** — 基于 label 的模糊匹配
- **远程搜索** — 通过 `remoteMethod` 异步加载选项
- **自定义过滤** — 通过 `filterFn` 自定义搜索逻辑

### 🎨 自定义渲染
- **renderOption** — 自定义选项 HTML 渲染
- **renderLabel** — 自定义触发器标签文本

### ⌨️ 键盘导航
- `↑↓` 切换选项、`←→` 展开/折叠树节点
- `Enter` 确认选择、`Escape` 关闭
- `Backspace` 删除最后标签（多选模式）

### 📐 尺寸变体
- `small` / `medium`（默认）/ `large`

### 🎯 设计系统集成
- 颜色引用 `packages/color` 生成的 `--ld-*` 全局 CSS 变量
- 尺寸引用 `packages/size` 生成的 `--ld-*` 全局 CSS 变量
- 所有 class 以 `ldesign-` 为前缀
- 自动适配 light/dark 主题

### 🔧 其他功能
- **Loading 状态** — 远程搜索时自动显示加载指示器
- **Form 集成** — 自动生成隐藏 `<input>` 用于表单提交
- **自动翻转** — 空间不足时下拉面板自动向上展开

## 🚀 快速开始

### 安装

```bash
pnpm add @ldesign/select-vue
```

### Vue 组件使用

```vue
<template>
  <LSelect
    v-model="value"
    :options="options"
    searchable
    allow-clear
    placeholder="请选择"
    @change="onChange"
  />
</template>

<script setup>
import { ref } from 'vue'
import { LSelect } from '@ldesign/select-vue'

const value = ref(null)
const options = [
  { value: '1', label: '选项1' },
  { value: '2', label: '选项2' },
  { value: '3', label: '选项3' },
]

const onChange = (val) => console.log('选中:', val)
</script>
```

### 多选 + 远程搜索

```vue
<template>
  <LSelect
    v-model="selected"
    :remote-method="fetchOptions"
    :loading="loading"
    mode="multiple"
    searchable
    :max-tag-count="3"
    placeholder="输入搜索..."
  />
</template>

<script setup>
import { ref } from 'vue'
import { LSelect } from '@ldesign/select-vue'

const selected = ref([])
const loading = ref(false)

async function fetchOptions(query) {
  loading.value = true
  const res = await fetch(`/api/search?q=${query}`)
  const data = await res.json()
  loading.value = false
  return data.map(item => ({ value: item.id, label: item.name }))
}
</script>
```

### Core 直接使用（无框架）

```ts
import { SelectCore, createSelect } from '@ldesign/select-core'

const select = createSelect({
  options: [
    { value: '1', label: '选项1' },
    { value: '2', label: '选项2' },
  ],
  placeholder: '请选择',
  searchable: true,
  allowClear: true,
})

select.on('change', (value) => console.log('选中:', value))
select.setValue('1')
```

### DOM 渲染器使用

```ts
import { SelectDOM } from '@ldesign/select-core'
import '@ldesign/select-core/styles/select.css'

const select = new SelectDOM({
  container: '#my-select',
  options: [...],
  searchable: true,
  size: 'large',
  theme: { primaryColor: '#667eea' },
})
```

## 📁 项目结构

```
select/
├── packages/
│   ├── core/                    # @ldesign/select-core
│   │   ├── src/
│   │   │   ├── types.ts         # 类型定义
│   │   │   ├── core/            # SelectCore 状态机
│   │   │   ├── dom/             # SelectDOM 渲染器
│   │   │   ├── utils/           # 过滤/键盘/树形工具
│   │   │   └── styles/          # CSS 样式
│   │   └── package.json
│   └── vue/                     # @ldesign/select-vue
│       ├── src/
│       │   ├── components/      # Vue 组件
│       │   ├── composables/     # useSelect
│       │   └── plugins/         # Vue 插件
│       └── package.json
└── README.md
```

## 📦 构建产物

| 目录 | 格式 | 说明 |
|------|------|------|
| `es/` | ESM | ES Modules（preserveModules） |
| `esm/` | ESM | ES Modules（保留模块结构） |
| `lib/` | CJS | CommonJS（.cjs 后缀） |
| `dist/` | UMD | 浏览器直接引用 |

## 📄 许可证

MIT License