# @fiscozen/card 中文文档

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

版本：3\.0\.15
npm 元数据更新时间：2026-10-23T08:35:11.194Z
中文译文更新时间：2026-11-14T20:32:32.562Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：146 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：4 个
- peer 依赖：vue ^3\.4\.13，tailwindcss ^3\.4\.1，@fiscozen/icons ^1\.0\.8
- 首次发布：2024-06-21T08:23:16.543Z
- 最新版本发布：2026-10-23T08:35:10.980Z
- 近 30 天下载量：2741（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 22 个）

## 中文简介

设计系统卡组件

## 安装

```sh
npm install @fiscozen/card
```

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

## README

# @ fiscozen/ card (中文(简体) )

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

## 发展

### 建筑

这个 `FzCard` 组件是一个组合相关内容和行动的布局容器。 它提供了一个一致的结构:可选标题(title + slots),主要内容区域,以及可选页脚(默认动作按钮或自定义的槽). 它支持多个背景颜色变体,可折叠内容与可配置的默认状态,以及可选的信息图标. 所有动作按钮和信息图标使用相同的 `environment` 视觉上下文的道具(后台对前台).

**密钥状态 :**

-   `isOpen`: 修改控制扩展/缩合状态时 `collapsible` 是真实的; 初始值来自 `defaultExpanded ?? false`
-   `normalizedColor`:计算出映射已贬值的颜色值(如. `aliceblue` → `blue`用于内部造型
-   `showContent`: 已计算——非相撞或扩展时为真
-   `isAlive`: 计算出——当 `alwaysAlive` 或者说 `showContent`;驱动文章/脚是否在 DOM (v- 如果) 中
-   `existHeader`: 计算出——在提供标题或标题/标题内容槽时为真
-   `atLeastOneButton`:计算出来的——确定任何初级/中级/高等教育行动时属实

**颜色和样式流 :**

-   `normalizedColor` 种子 `backgroundColor` 财务报告和审定财务报表 `borderColor` 计算属性
-   背景/边界使用 Tailwind 类:默认/蓝色/橙色/纯色/灰色设计符号;黄色语义符号(`--semantic-warning-50`)和红色(`--semantic-error-50`(中文(简体) )
-   文字颜色总是 `text-core-black` 所有变体

### 代码组织

-   `src/FzCard.vue`: 单文件组件; 所有逻辑和模板在一个地方
-   `src/types.ts`数字 : `FzCardProps`, (中文(简体) ), `FzCardColor`, (中文(简体) ), `FzCardEnvironment`, (中文(简体) ), `FzCardEvents`, (中文(简体) ), `FzCardSlots`和内部行动类型
-   `src/index.ts`出口部分和类型

无子组件或 `utils`编号 :`common` 模块; 色彩映射和布局逻辑存在于主组件中.

### 关键概念

#### 颜色变体和规范化

这个 `color` 道具接受 : `default`, (中文(简体) ), `blue`, (中文(简体) ), `orange`, (中文(简体) ), `purple`, (中文(简体) ), `grey`, (中文(简体) ), `yellow`, (中文(简体) ), `red`,且已贬值 `aliceblue`。所有样式用途 `normalizedColor` 因此:

-   `aliceblue` 被映射为 `blue` (同样的视觉结果)
-   A 类 `watch` 与 `immediate: true` 当 `color === 'aliceblue'`

背景和边框类按两个计算属性解决(`backgroundColor`, (中文(简体) ), `borderColor`带有 `switch (normalizedColor.value)` 超过正常值。 添加新颜色需要在计算和扩展时添加大小写 `FzCardColor` 内 `types.ts`。 。 。 .

#### 可折叠性和内容可见性

-   何时 `collapsible` 虚假:内容和页脚总是可见; `isAlive` 财务报告和审定财务报表 `showContent` 真实
-   何时 `collapsible` 是真的: 点击页眉切换 `isOpen`· ; `showContent` 如下 `isOpen`; 文章用途 `v-show="showContent"` 所以它可以隐藏而不毁灭
-   `isAlive`:当真实时,会提供文章和页脚(v-if). 假的(可折叠而倒塌,不可折叠) `alwaysAlive`),文章不在DOM. 所以说: `alwaysAlive` 崩溃时将内容保存在 DOM; 否则崩溃状态会删除文章( 没有动作/ 片段时则删除页脚)

页脚仅在 `(slots.footer || atLeastOneButton) && isAlive` 财务报告和审定财务报表 `v-show="showContent"`,所以它隐藏的内容当崩溃,除非被槽用法所压倒.

#### 动作按钮和警告

初级、二级和三级行动在默认页脚槽中通过 `FzContainer` + 键 `FzButton` 编号 : `FzIconButton`在模板中排列顺序:三级(立体)、二级、初级。 在挂载时,组件警告:

-   `tertiaryAction` 设置时没有两者 `primaryAction` 财务报告和审定财务报表 `secondaryAction`
-   `secondaryAction` 未设置 `primaryAction`

这些只是指导;制作工作仍在进行.

#### 响应页脚

`useMediaQuery` 从 `@fiscozen/composables` 财务报告和审定财务报表 `breakpoints` 从 `@fiscozen/style` 驱动 `smOrSmaller`当真实时,页脚已经 `w-full` 在集装箱上 `flex-grow` 二级/一级按钮;页脚布局使用 `justify-end` 当不是时 `smOrSmaller`。 。 。 .

### 内部逻辑

#### 颜色类映射

-   `backgroundColor`数字 : `default` → `bg-core-white`· ; `blue` → `bg-background-alice-blue`· ; `orange` → `bg-background-seashell`· ; `purple` → `bg-background-pale-purple`· ; `grey` → `bg-background-white-smoke`· ; `yellow` → `bg-semantic-warning-50`· ; `red` → `bg-semantic-error-50`
-   `borderColor`: 相同的密钥 ^ `border-grey-100` (违约), `border-background-alice-blue`, (中文(简体) ), `border-background-seashell`, (中文(简体) ), `border-background-pale-purple`, (中文(简体) ), `border-background-white-smoke`, (中文(简体) ), `border-semantic-warning-50`, (中文(简体) ), `border-semantic-error-50`

所有其他颜色(如:未来符号)都需要在计算时添加一个大小写,并确保设计系统中存在Tailwind/语义符号.

#### 页脚可见度

当有东西可以显示并且内容是“活性的”时,脚便会被制成(v-if):

-   条件 : `(slots.footer || atLeastOneButton) && isAlive`
-   可见度 : `v-show="showContent"` 所以它藏起来 当相撞而倒塌时
-   当仅存在动作时, 默认页脚位会变成 `FzContainer` 有三级(FzIconButton),二级(FzButton),初级(FzButton). 自定义页脚完全通过 `#footer`。 。 。 .

#### 定义退出

仅 `toggleOpen` ; 用于程序扩展/缩放 `collapsible` 这是真的.

### 设计决定

#### 为什么将颜色正常化而不是去除苍蝇蓝?

保存中 `aliceblue` 类型和正态化到 `blue` 保存后向兼容性。 消费者可以按照自己的速度移徙,同时得到单一的贬值警告。 把它取出将是一个突破性的变化.

#### 为什么V -如果是Article/Footer和V -show的可见度?

`v-if="isAlive"` 控制内容块是否完全存在(例如,当崩溃而不是 `alwaysAlive`) (中文(简体) ). `v-show="showContent"` 只在相撞和倒塌时将块遮住,但仍“活着”。 这允许在支持时为性能可选删除 DOM `alwaysAlive` 对于必须挂载的状态内容.

#### 为什么在山上发出行动警告?

第三级/中等教育没有小学,则被类型系统允许,但被认为是劣等UX. 《闪电警告》指导消费者在不违反现有代码的情况下建议使用.

### 已知的限制

-   **无内置加载/误入状态**: 卡不提供加载或出错 UI; 消费者可以使用插槽或内容Class
-   **行动命令已定**:三级,二级,一级顺序不能通过道具来配置
-   **单一扩展状态**: 没有手风琴/团体行为;每张牌管理自己的 `isOpen`

## 常见问题

### @fiscozen/card 是什么？

设计系统卡组件

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

在项目目录运行 npm install @fiscozen/card，或使用 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/card 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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