# @fiscozen/composables 中文文档

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

版本：1\.2\.0
npm 元数据更新时间：2026-10-23T08:36:53.866Z
中文译文更新时间：2026-11-14T20:25:14.097Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：262 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：vue ^3\.4\.13，tailwindcss ^3\.4\.1
- 首次发布：2024-05-14T08:34:01.228Z
- 最新版本发布：2026-10-23T08:36:53.625Z
- 近 30 天下载量：4841（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 16 个）

## 中文简介

设计系统

## 安装

```sh
npm install @fiscozen/composables
```

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

## README

# @ fiscozen/ 组合

> 关于使用量的文件,见 [故事书文档](https://npmcn.com/package/apps/storybook/src/Composables.mdx)

## 发展

### 设置

```bash
pnpm install
pnpm --filter @fiscozen/composables build
```

### 代码组织

```
src/
  index.ts                        Re-exports everything (composables, types, utils, FzFloating)
  types.ts                        Shared types (FzFloatingPosition, FzRect, FzUseCurrencyOptions, etc.)
  utils/
    index.ts                      Barrel file for utilities
    number/
      index.ts                    Currency format/parse helpers
    position/
      index.ts                    Floating position calculation helpers
  FzFloating.vue                  Component wrapper for useFloating
  composables/
    index.ts                      Barrel file for all composables
    useFloating.ts                Floating element positioning
    useMediaQuery.ts              Reactive CSS media query matching
    useBreakpoints.ts             Responsive breakpoint detection (wraps useMediaQuery)
    useClickOutside.ts            Click-outside detection
    useKeyDown.ts                 Keydown event listener
    useKeyUp.ts                   Keyup event listener
    useCurrency.ts                Currency formatting (deprecated)
  __tests__/
    useFloating.spec.ts           useFloating unit tests
    FzFloating.spec.ts            FzFloating component tests
    number.spec.ts                Currency/number utility tests
```

## 可编曲

### 浮动

浮动/流行元素的定位逻辑(工具提示,下放,弹出等).

**结构 :**

-   **查询表**数字 : `positionCalculators` (带有开口器)和 `containerPositionCalculators` (没有打开器)为所有12个明确位置提供O(1)位置分辨率(上/下/左/右+-起/端变体).
-   **自动定位解析**数字 : `resolveAutoPosition` 代表团 `getHighestAvailableSpacePos` 页:1 `auto`, (中文(简体) ), `auto-vertical`, (中文(简体) ), `auto-start`, (中文(简体) ), `auto-end`和他们的组合.
-   **边界更正**数字 : `applyBoundaryCorrections` 夹住容器界限内的最后位置,当元素溢出时会改变.
-   **轮班预防**: 该元素设置为 `position: fixed` 在直径计算之前.
-   **反应重定位**: 用途 `IntersectionObserver` 以跟踪可见度的变化.

这个 `FzFloating` 构成部分`src/FzFloating.vue`)是显示 `useFloating` 通过声明模板 API.

### 使用媒体查询

绕行回放 `window.matchMedia`返回计算 `Ref<boolean>` 当媒体查询符合状态变化时更新。 生命周期意识:在挂载上添加收听器,在卸载上删除.

### 使用断点

高级抽象 `useMediaQuery` 用于响应性设计. 接受打入的断点映射( R)`Record<T, '${number}px'>`返回时 `isGreater(bp)`, (中文(简体) ), `isSmaller(bp)`,以及 `isInBetween(min, max)`。 。 。 .

### 使用 Click 外部

检测到在目标元素外单击。 接受一个组件 ref,一个回调,和一个可选择的元素来限制听众(默认为 `document`) (中文(简体) ). 支持动态监听器通过 `watch` 当范围元素改变时.

### 使用密钥下

附 录a `keydown` 组件参考器的监听器。 生命周期管理(山地/非山地)。 如果缺少组件或回调则丢出 .

### 使用键

附 录a `keyup` 组件的收听器 `document` 当未提供组件时。 参数顺序不同于 `useKeyDown`数字 : `(callback, component?)` ——构件可选.

### 使用频率

**堕地.** 环绕 `format` 财务报告和审定财务报表 `parse` 从 `src/utils/number`消费者应直接进口这些功能.

## 测试

### 运行测试

```bash
pnpm --filter @fiscozen/composables test:unit
pnpm --filter @fiscozen/composables coverage
```

### 测试结构

-   `useFloating.spec.ts` 编号 : `FzFloating.spec.ts`: 位置计算和组件渲染.
-   `number.spec.ts`: 货币格式/公用设施.

测试模拟 `window.matchMedia` 内 `beforeEach`覆盖率目标: > 90%.

## 依赖关系

-   `@fiscozen/style` (工作空间) —— 断点符号 `useBreakpoints` 编号 : `useMediaQuery`

## 构建

```bash
pnpm --filter @fiscozen/composables build
```

运行 Vite 库建设 。 输出到 `dist/`。 。 。 .

## 常见问题

### @fiscozen/composables 是什么？

设计系统

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

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

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

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

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

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

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

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

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

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

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

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