# @fiscozen/action 中文文档

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

版本：3\.0\.1
npm 元数据更新时间：2026-04-30T07:24:40.546Z
中文译文更新时间：2026-11-14T20:58:57.931Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：134 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：tailwindcss ^3\.4\.1，vue ^3\.4\.13，vue-router ^4\.3\.0，@fiscozen/icons ^1\.0\.4
- 首次发布：2025-12-15T14:50:10.536Z
- 最新版本发布：2026-04-30T07:24:40.383Z
- 近 30 天下载量：2309（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

设计系统行动部分

## 安装

```sh
npm install @fiscozen/action
```

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

## README

# @fiscozen/行动

用于构建交互列表、菜单和可选择选项的 Versatile 动作组件.

## 特征

-   **行动**: 可作为按钮或链接的灵活动作组件
-   **行动列表**: 组织多种行动的集装箱
-   **Fz 行动科**: 带标签的分区分隔符,用于组合动作
-   多个变体: `textLeft`, (中文(简体) ), `textCenter`, (中文(简体) ), `onlyIcon`
-   环境特有的结构: `backoffice` (契约)和 `frontoffice` (舒缓)
-   完全无障碍支持,可配置的ARIA角色
-   键盘导航和焦点管理
-   仅可读状态
-   带椭圆的文本调值
-   图标定位( 左, 右, 或仅图标)

## 安装

```bash
npm install @fiscozen/action
```

## 基本用途

### Fz 动作作为按钮

```vue
<script setup>
import { FzAction } from '@fiscozen/action'
</script>

<template>
  <FzAction
    type="action"
    variant="textLeft"
    label="Click me"
    @click="handleClick"
  />
</template>
```

### Fz 动作作为链接

```vue
<script setup>
import { FzAction } from '@fiscozen/action'
</script>

<template>
  <FzAction
    type="link"
    variant="textLeft"
    label="Go to page"
    to="/page"
  />
</template>
```

### 包含多个动作的 Fz 动作列表

```vue
<script setup>
import { FzActionList, FzAction } from '@fiscozen/action'
</script>

<template>
  <FzActionList>
    <FzAction type="action" variant="textLeft" label="Edit" />
    <FzAction type="action" variant="textLeft" label="Delete" />
    <FzAction type="action" variant="textLeft" label="Share" />
  </FzActionList>
</template>
```

### Fz 分组行动科

```vue
<script setup>
import { FzActionList, FzAction, FzActionSection } from '@fiscozen/action'
</script>

<template>
  <FzActionList>
    <FzActionSection label="File" />
    <FzAction type="action" variant="textLeft" label="New" />
    <FzAction type="action" variant="textLeft" label="Open" />
    
    <FzActionSection label="Edit" />
    <FzAction type="action" variant="textLeft" label="Cut" />
    <FzAction type="action" variant="textLeft" label="Copy" />
  </FzActionList>
</template>
```

## 道具

### 行动

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `type` | `'action' | 'link'` | `'action'` | 组件类型(按钮或链接) |
| `variant` | `'textLeft' | 'textCenter' | 'onlyIcon'` | `'textLeft'` | 版式变体 |
| `environment` | `'backoffice' | 'frontoffice'` | `'backoffice'` | 环境造型( 契约 vs 宽度) |
| `label` | `string` | \- 说吧 | 主要标签文本 |
| `subLabel` | `string` | \- 说吧 | 主标签下的次要文本 |
| `disabled` | `boolean` | `false` | 禁用动作 |
| `readonly` | `boolean` | `false` | 让动作非交互而视觉正常 |
| `focused` | `boolean` | `false` | 视觉焦点状态(用于键盘导航) |
| `isTextTruncated` | `boolean` | `false` | 启用带有椭圆形的文本校正 |
| `iconLeftName` | `string` | \- 说吧 | FontAsome 图标名称( 左侧) |
| `iconLeftVariant` | `IconVariant` | \- 说吧 | FontAwesome 图标变体( 左侧) |
| `iconRightName` | `string` | \- 说吧 | FontAsome 图标名称( 右侧) |
| `iconRightVariant` | `IconVariant` | \- 说吧 | FontAwesome 图标变体( 右侧) |
| `id` | `string` | \- 说吧 | ARIA 关系的独特ID |
| `role` | `string` | \- 说吧 | ARIA的作用(例如:, `"option"`, (中文(简体) ), `"menuitem"`(中文(简体) ) |
| `ariaSelected` | `boolean` | \- 说吧 | ARIA 选定状态(用于 `role="option"`(中文(简体) ) |
| `tabindex` | `number` | \- 说吧 | 覆盖标签索引值(用于自定义焦点管理) 。 默认 : `0` 当重点突出和互动时, `-1` 否则 |

**链接专用道具( 当 `type="link"`:**

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `to` | `RouteLocationRaw` | \- 说吧 | 路由器链接目的地( 需要) |
| `replace` | `boolean` | `false` | 使用替换导航 |
| `target` | `string` | \- 说吧 | 链接目标(例如, `"_blank"`(中文(简体) ) |
| `external` | `boolean` | `false` | 外部链接旗 |

**只有图标的变体道具( 当 `variant="onlyIcon"`:**

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `iconName` | `string` | \- 说吧 | FontAsome 图标名称( 需要) |
| `iconVariant` | `IconVariant` | \- 说吧 | FontAwesome 图标变体( 需要) |

### 行动列表

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `listClass` | `string` | `''` | 列表的额外 CSS 类 |
| `role` | `string` | \- 说吧 | ARIA在列表中的作用(例如:, `"listbox"`, (中文(简体) ), `"menu"`(中文(简体) ) |
| `ariaLabelledby` | `string` | \- 说吧 | 标签列表的元素的标识 |
| `ariaActivedescendant` | `string` | \- 说吧 | 目前活跃的后裔的身份 |

### Fz 行动科

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | `''` | 区域标签文本 |

## 活动

### 行动

| 活动 | 有效载荷 | 说明 |
| --- | --- | --- |
| `click` | `MouseEvent` | 单击动作时退出 |
| `keydown` | `KeyboardEvent` | 在按键下发送( Enter/ Space 触发点击) |

## 无障碍

### ARIA 角色

这个 `role` 道具允许配置动作的语义作用 :

**作为列表框选项( 如 FzSelect) :**

```vue
<FzActionList role="listbox" aria-labelledby="select-label">
  <FzAction
    type="action"
    variant="textLeft"
    label="Option 1"
    role="option"
    :ariaSelected="true"
  />
  <FzAction
    type="action"
    variant="textLeft"
    label="Option 2"
    role="option"
    :ariaSelected="false"
  />
</FzActionList>
```

**作为菜单 :**

```vue
<FzActionList role="menu">
  <FzAction
    type="action"
    variant="textLeft"
    label="Edit"
    role="menuitem"
  />
  <FzAction
    type="action"
    variant="textLeft"
    label="Delete"
    role="menuitem"
  />
</FzActionList>
```

### 键盘导航

-   **输入/ 空间**: 触发动作( 当聚焦时)
-   **标签**: 将焦点移到下一个可聚焦元素
-   **箭头键**: 由母组件管理(例如FzSelect)

### 屏幕阅读器支持

-   `aria-disabled`: 总是清晰地显示 `"true"` 或者说 `"false"` 数值
-   `aria-selected`: 当 `role="option"` 以显示选择状态
-   `aria-label`: 只为图标变量自动计算
-   文本截图: 可通过 `title` 属性

## 实例

### 仅限图标动作

```vue
<FzAction
  type="action"
  variant="onlyIcon"
  iconName="trash"
  iconVariant="solid"
  label="Delete"
  @click="handleDelete"
/>
```

### 带有图标的动作

```vue
<FzAction
  type="action"
  variant="textLeft"
  label="Settings"
  iconLeftName="gear"
  iconLeftVariant="solid"
  iconRightName="chevron-right"
  iconRightVariant="solid"
/>
```

### 使用子标签操作

```vue
<FzAction
  type="action"
  variant="textLeft"
  label="John Doe"
  subLabel="john.doe@example.com"
  iconLeftName="user"
  iconLeftVariant="solid"
/>
```

### 残疾人行动

```vue
<FzAction
  type="action"
  variant="textLeft"
  label="Unavailable"
  disabled
/>
```

### 只读动作

```vue
<FzAction
  type="action"
  variant="textLeft"
  label="Read Only"
  readonly
/>
```

### 文本截断

```vue
<FzAction
  type="action"
  variant="textLeft"
  label="Very long text that will be truncated with ellipsis"
  isTextTruncated
/>
```

### 环境变式

```vue
<!-- Backoffice (compact) -->
<FzAction
  type="action"
  variant="textLeft"
  environment="backoffice"
  label="Compact action"
/>

<!-- Frontoffice (spacious) -->
<FzAction
  type="action"
  variant="textLeft"
  environment="frontoffice"
  label="Spacious action"
/>
```

## 页:1

-   **默认环境**数字 : `backoffice` (繁体语)
-   **图标变体**: 要求 `@fiscozen/icons` 软件包
-   **链接功能**: 要求 `vue-router` 财务报告和审定财务报表 `@fiscozen/link` 软件包
-   **ARIA 角色**: 可选但建议在复杂组件中无障碍
-   **文本切换**: 适用于两者 `label` 财务报告和审定财务报表 `subLabel`
-   **只读对已禁用**:只读保持正常外观,但防止交互;已禁用显示灰色外观

## 相关构成部分

-   **Fz 选择**: 用途 `FzAction` 与 `role="option"` 用于下拉选项
-   **弗兹林克**: 基准链接组件,当 `type="link"`
-   **福兹康**图标组件来自 `@fiscozen/icons`

## 常见问题

### @fiscozen/action 是什么？

设计系统行动部分

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

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

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

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

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

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

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

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

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

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

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

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