# @fiscozen/select 中文文档

规范地址：https://npmcn.com/package/%40fiscozen/select/

版本：3\.3\.0
npm 元数据更新时间：2026-11-12T14:11:09.548Z
中文译文更新时间：2026-11-14T20:32:13.427Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fiscozen/select
原文对照：https://npmcn.com/package/%40fiscozen/select/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：481 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：7 个
- peer 依赖：vue ^3\.4\.13，tailwindcss ^3\.4\.1，@fiscozen/icons ^1\.0\.8
- 首次发布：2024-06-28T14:59:26.758Z
- 最新版本发布：2026-11-12T14:11:09.100Z
- 近 30 天下载量：2745（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 39 个）

## 中文简介

设计系统 选择组件

## 安装

```sh
npm install @fiscozen/select
```

也可以使用：`pnpm add @fiscozen/select`、`yarn add @fiscozen/select`、`bun add @fiscozen/select`

## README

# @ fiscozen/ 选择

> 关于使用量的文件,见 [故事书文档](https://storybook-url/FzSelect)

## 发展

### 设置

1.  清除仓库
2.  安装依赖性 : `pnpm install`
3.  运行 Dev 服务器 : `pnpm dev` (从工作空间根)

### 建筑

这个 `FzSelect` 组件是支持两个标准选择行为(默认,当 `filterable` 错误)和打字头/可过滤行为(当 `filterable` ) (中文(简体). 它分享了相同的浮动面板,懒惰地加载,以及键盘导航模式. 默认情况下,它表现为标准选择下拉. 何时 `filterable` 设置为真,组件打开后显示一个可过滤的输入字段;否则,则显示所选选项标签为按钮.

**关键部件 :**

-   `FzSelect.vue`: 主要部件 管弦状态、过滤和导航
-   `FzSelectButton.vue`: 开口按钮,在按钮和输入模式之间切换
-   `FzSelectOptionsList.vue`: 含有懒惰加载支持的选项列表
-   `FzSelectLabel.vue`: 有所需指标的标签部分
-   `FzSelectHelpError.vue`: 帮助/错误消息组件

**州管理层:**

-   `model`: 所选值(字符串 QQ未定义)
-   `searchValue`: 当前用于过滤的输入文本
-   `debouncedSearchValue`: 跳过搜索Value版本
-   `internalFilteredOptions`: 应用过滤器Fn或Fuse.js后过滤的选项
-   `visibleOptions`: 被过滤选项的懒惰子集
-   `focusedIndex`: 当前重点选择的索引 `selectableOptions`
-   `isOpen`: 放下打开/关闭状态

**过滤流 :**

1.  用户类型 + `searchValue` 更新
2.  之后 `delayTime` 妇女 □ `debouncedSearchValue` 更新
3.  `updateFilteredOptions()` 称为 − 适用 `filterFn` 或 Fuse.js 系统
4.  `internalFilteredOptions` 更新 + 触发 `visibleOptions` 重设
5.  卷起懒惰的装入 `visibleOptions` 扩展

### 代码组织

-   `src/FzSelect.vue`: 具有所有业务逻辑的主要组件
-   `src/types.ts`: 道具和选项的类型定义
-   `src/common.ts`: 共享公用事业(width计算,常数)
-   `src/utils.ts`: 工具函数( 调试)
-   `src/components/`: 内部列报部分
    -   `FzSelectButton.vue`: 按钮/输入切换器
    -   `FzSelectOptionsList.vue`: 选项列表渲染器
    -   `FzSelectLabel.vue`: 标签渲染器
    -   `FzSelectHelpError.vue`: 帮助/透视渲染器
    -   `types.ts`: 内部组件道具类型

### 关键概念

#### 双模式输入

该组成部分采用双模式方法,当 `filterable` 事实 :

-   **关闭状态**:按钮显示所选选项标签(或占位符)
-   **打开状态**: 用于过滤的输入字段

何时 `filterable` 是虚假的(默认),组件作为标准选择的仅按键交互下拉.

这是处理在 `FzSelectButton.vue` 使用 `shouldShowTheInput` 计算检查的财产 `filterable && isOpen`。 。 。 .

#### 过滤策略

该组件支持三种过滤模式:

1.  **自定义 `filterFn` (同步或同步)**: 优先于默认过滤
    
    -   打电话 `debouncedSearchValue`
    -   可以返回同步操作的承诺
    -   没有种族条件保护 - 显示最后得到的结果
2.  **Fuse.js 模糊搜索**: 当 `filterable` 没错, `fuzzySearch` 是真的,没有 `filterFn`
    
    -   搜索在 `label` 字段
    -   处理打字和部分匹配
    -   仅在输入有值时活动
    -   可以通过设置禁用 `fuzzySearch: false` 要使用简单的 `includes()` 搜索改为
3.  **简单包括搜索**: 当 `filterable` 没错, `fuzzySearch` 是假的,没有 `filterFn`
    
    -   不区分大小写的使用 `includes()` 用于子字符串匹配
    -   不处理打字( 只匹配精确的子字符串)
    -   仅在输入有值时活动
4.  **无过滤**: 当 `filterable` 错误( 默认) 或输入为空
    
    -   显示所有可用的选项

#### 懒惰装入

为性能分批提供选项:

-   初始负载: 第一 `optionsToShow` (默认 25) 选项
-   滚动触发器: 当用户滚动到底部附近时装入下一批
-   缓冲 : `OPTIONS_BUFFER * OPTIONS_HEIGHT` 从下方触发的像素加载
-   选中选项: 超过可见范围时自动加载

#### 带有已禁用选项的键盘导航

该组件浏览所有选项(包括禁用/只读),用于遵守WCAG:

-   `selectableOptions`: 所有可选选项(不包括标签,包括禁用/只读)
-   `focusedIndex`: 索引的点 `selectableOptions`
-   导航穿行所有选项, 但禁用/ 仅读选项在不显示图像的情况下获得焦点
-   Tab 导航允许为可访问性翻转已禁用的选项

#### 在过滤器更改上重置滚动

何时 `internalFilteredOptions` 更改( 由于过滤或选项更新):

-   `visibleOptions` 重排为第一批
-   向上滚动位置 `resetScrollPosition()`
-   防止过滤器更改后显示错误的选项

### 测试

#### 运行测试

```bash
pnpm test:unit
pnpm coverage
```

#### 测试结构

-   单位测试 `src/__tests__/FzSelect.spec.ts`
-   测试命名 : `describe` 特性组的块, `it` 特定案件的块
-   覆盖范围要求: > 90%
-   使用 `mount` 从 `@vue/test-utils` 用于组件测试

#### 测试范围

测试覆盖 :

-   制作和道具
-   v- 模型绑定
-   选项过滤( Fuse.js 和自定义过滤Fn)
-   懒惰装入
-   键盘导航(包括已禁用选项)
-   重点管理
-   错误和帮助状态
-   无障碍属性
-   边框(空选项,未定义选项等)

### 添加特性

#### 步骤1:更新类型

添加新道具到 `src/types.ts` 与联合来文文件:

```typescript
/**
 * Description of the prop
 * @default 'defaultValue' if applicable
 */
newProp?: string
```

#### 步骤2:实施逻辑

在 `src/FzSelect.vue`数字 :

-   采用代表制模式
-   使用信息专家模式( 将全部对象传递给助手)
-   提取重复逻辑到帮助函数

#### 步骤 3: 更新模板

在模板部分添加新的 UI 元素 :

-   维护区域顺序 : `<script>` → `<template>` → `<style>`
-   使用语义 HTML 和 ARIA 属性

#### 第4步:添加测试

新功能的写入单元测试 :

-   检测阳性和阴性病例
-   测试边缘大小写( null, 未定义, 空值)
-   测试无障碍功能

#### 步骤5:更新文档

-   以使用示例更新 MDX
-   如果架构/日志更改, 更新 README

### 构建和释放

-   构建 : `pnpm build`
-   版本: 跟踪 semver
-   发布 : `pnpm publish` (从工作空间根)

### 内部逻辑

#### Width 计算算法

这个 `calculateContainerWidth()` 函数在 `src/common.ts`数字 :

1.  测量开口元素的边框矩形
2.  设置最小宽度( 打开宽度, MIN WIDTH)
3.  计算左右可用的空间
4.  将最大宽度设置为打开宽度 + 最大( 空间左, 空间右)

这保证了下放匹配开口宽度,同时尊重取景口边界.

#### 重点管理

打开滴入时的焦点流 :

1.  若为 `filterable`: 焦点移动到输入字段(`FzInput` 内部 `FzSelectButton`(中文(简体) )
2.  如果没有 `filterable`: 焦点移动到第一个启用的选项
3.  如果选中选项: 焦点移动到所选选项( 如果启用)

关闭时的焦点流 :

1.  焦点返回到打开按钮
2.  `focusedIndex` 重排为 - 1

#### 过滤种族条件

何时 `filterFn` 快速调用 :

-   没有取消机制 - 所有通话进行
-   显示最后结果( 可覆盖先前的结果)
-   开发者处理种族条件的责任( 如请求取消)

这种设计选择将简化和开发者对自动赛跑条件处理的控制放在优先位置.

### 设计决定

#### 为什么双模式输入而不是总输入?

双模式方法(关闭时的按钮,打开时的输入)提供:

-   更好的 UX: 选中的值在不过滤时清晰可见
-   空间效率:仅在需要时才出现输入
-   熟悉模式: 匹配常见的选定执行

#### 为什么没有为过滤器Fn提供种族条件保护?

种族条件处理由开发者负责,因为:

-   不同的使用情况需要不同的策略(取消、取消、排队)
-   自动取消可以在开发者的代码中隐藏错误
-   较简单的 API: 只显示最后收到的结果

#### 为什么通过所有选项( 包含已禁用) ?

导航所有选项( 包括禁用/ 仅读) , 用于遵守 WCAG :

-   屏幕阅读器可以宣布所有选项,包括已禁用选项
-   键盘用户可以翻转完整的上下文列表
-   禁用选项获得焦点,但没有视觉指示
-   更好的可获取性:用户理解全套选项集

#### 为什么是第一种风格的代理模式?

使用 `switch(true)` 有条件样式的辅助函数 :

-   清晰地绘制出:"元件何时看起来像X
-   可维护:添加新视觉状态=添加新病例
-   自我文档:结构回答"何时看起来像X"
-   可测试: 帮助器功能可以单独测试

### 依赖关系

**同伴依赖关系 :**

-   `vue`: ^3.4.13 (中文(简体) )
-   `tailwindcss`页:1

**依赖性 :**

-   `@fiscozen/composables`: 浮动面板定位
-   `@fiscozen/action`: 选项列表渲染
-   `@fiscozen/input`输入字段
-   `@fiscozen/icons`图标组件
-   `@fiscozen/progress`: 正在装入指标
-   `fuse.js`: 模糊搜索库

**依赖性:**

-   标准测试和构建工具(viest, vite, typescript等)

### 业绩考量

-   **懒惰装入**: 大列表(100+项目)的自动
-   **调试**: 可通过配置 `delayTime` (默认500ms)
-   **Fuse.js (法语)**: 只有在需要时才被即时处理(计算的财产)
-   **滚动收听器**: 附着一次,在卸载上清理
-   **监视优化**: 用途 `immediate: true` 仅在需要时

### 已知的限制

-   **无多选择**单项选择
-   **没有虚拟滚动**: 懒惰加载批次, 但所有可见选项都在 DOM 中
-   **无过滤器Fn 取消**: Async filterFn 调用不会自动取消

## 常见问题

### @fiscozen/select 是什么？

设计系统 选择组件

### 如何安装 @fiscozen/select？

在项目目录运行 npm install @fiscozen/select，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.4\.13）、tailwindcss（^3\.4\.1）、@fiscozen/icons（^1\.0\.8）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fiscozen/select 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fiscozen\_\_select 是否存在。

### @fiscozen/select 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fiscozen/select 可以商用吗？

@fiscozen/select 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fiscozen/select 的下载量有多少？

根据 npm 官方下载统计，@fiscozen/select 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,745 次，日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fiscozen/select 还在维护吗？

最新版本 3\.3\.0 发布于 2026/11/12（2 天前）；至今共发布 66 个版本，其中过去 12 个月发布了 39 个；首次发布于 2024/06/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。