# @fiscozen/textarea 中文文档

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

版本：3\.4\.1
npm 元数据更新时间：2026-10-23T08:35:56.283Z
中文译文更新时间：2026-11-14T20:50:41.572Z
软件包许可：MIT

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

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

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

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

## 中文简介

设计系统文本区组件

## 安装

```sh
npm install @fiscozen/textarea
```

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

## README

# @fiscozen/文本区

多行文本输入组件,有标签,验证状态,调整大小控制,以及WCAG 2.1 AA可访问性.

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

## 发展

### 设置

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

### 建筑

FzTextrea 是一个将本地文件包起来的窗体组件 `<textarea>` 有标签、验证状态(error/valid)、帮助/error消息,以及完全的ARIA可访问性。 使用错误消息 `FzAlert` 与 `FzInput`。 。 。 .

关键设计决定:

-   **自动生成的ID**: 当无 `id` 提供了道具,通过 `utils.ts` 确保标签-文本区协会始终有效。 使用时间戳 + 计数器模式(与 `@fiscozen/input`) (中文(简体) ).
-   **ARIA 三角图案**: Boolean ARIA属性使用ternary表达式(例如. `:aria-invalid="error ? 'true' : 'false'"`Vue 3 取消了布尔属性 `false`,但ARIA spec需要字符串值.
-   **通过 FzAlert 出错**: 使用错误消息 `<FzAlert tone="error" variant="text">` 与 `role="alert"`匹配 `FzInput` 模式。 这个 `circle-xmark` 图标由 FzAlert 自动提供。 依赖性 : `@fiscozen/alert`。 。 。 .
-   **基于槽的信息**: 错误和帮助内容通过 `errorMessage` 财务报告和审定财务报表 `helpText` 插槽, 匹配 `FzInput` 模式。 用途 `defineSlots` 用于类型脚本打字和 `useSlots()` 用于运行时段检测(与 `FzInput`) (中文(简体) ).
-   **自定义焦点环**: 浏览器默认大纲被压制 (`outline-none focus:ring-0 focus:outline-none`)取而代之的是焦点上的边框颜色变化(`focus:border-blue-600`) (中文(简体) ). 在错误状态下, 焦点用途 `focus:border-semantic-error-300` 以保持错误上下文。 这种办法不同于 `FzInput` 用于 `has-[:focus]` 在包装上。 这里边界直接在 `<textarea>` 键.
-   **设计符号对齐( 图)**: 使用边框颜色 `semantic-error-200` (默认错误) / `semantic-error-300` (错误+焦点). 占位符用途 `placeholder:text-grey-300`一. 背景情况 `bg-core-white`文字 `text-core-black`文本总是 `text-base` (16px)相匹配的Figma spec(无大小变体). 标签和帮助文本使用 `font-normal text-base`。只应用残疾/只读状态 `text-grey-300` 以标签和帮助文本.
-   **折旧 `size` 道具**编号: `size` 道具( r)`sm | md | lg`)被接受为后向相容但被忽略. 文本区总是由 `text-base`运行时间 `console.warn` 当任何值被传递时,会释放。 将在下一个主要版本中删除.
-   **`inheritAttrs: false` + 键 `v-bind="$attrs"`**: 额外的属性和本地事件听众直接传送给本地 `<textarea>` 元素,而不是 root 包装 div。 无自定义 `defineEmits` 用于 DOM 事件——模糊、焦点、粘贴、按键等 `$attrs` 自动.
-   **`defineExpose({ textareaRef })`**: 向当地人展示 `<textarea>` 方案重点或衡量要素参考,模式与 `FzInput` (单位:千美元)`inputRef`, (中文(简体) ), `containerRef`) (中文(简体) ).
-   **标签标识 + `aria-labelledby`**: 标签元素获得清晰 `id` (单位:千美元)`{effectiveId}-label`)和文本区域使用 `aria-labelledby` 提供更强大的屏幕阅读器关联 `for`编号 :`id` 装订。 模式与 `FzInput`。 。 。 .
-   **`watch` 折旧**: 用途 `watch(() => props.size, ..., { immediate: true })` 改为 `onMounted` 用于校正警告,与 `FzInput`以观察者为基础的方法。 抓取运行时间道具更改 .
-   **根识别类**数字 : `fz-textarea` root div 上用于调试和外部样式、镜像的类 `FzInput`是因为 `fz-input` 课.
-   **合并状态**:错误+残疾,需要+帮助,已禁用+编译均被支持. 当错误+损坏时,两者均 `aria-invalid` 财务报告和审定财务报表 `aria-disabled` 设置为“ true”,错误消息仍然可见。 当禁用/ 只读时, 帮助文本会灰化 .
-   **最小宽度/ 高度**数字 : `min-w-[96px]` 防止水平倒塌; `min-h-[77px]` 执行最小高度 `rows: 2` 默认(2行内容 + 10px 垫底+ 10px 垫底+ 1px 边框上+ 1px 边框下方).
-   **自动身高**: 当 `autoHeight` 实值 `true`中,文本区高度按每个 `v-model` 通过 `adjustHeight()`A级 `ResizeObserver` 用于外部大小变化。 垂直调整大小被禁用;水平保留. 字体度量衡( E)`lineHeight`, (中文(简体) ), `paddingY`, (中文(简体) ), `borderY`)在挂载时被缓存一次,因为它们是由设计系统固定的. `maxRows` 将生长盖上;在此之后会出现滚动条(`overflow-y: auto`) (中文(简体) ). `autoHeight` 必须在挂载时设置 —— 运行时更改不支持, 因为 hooks (`onMounted`, (中文(简体) ), `watch`)在设置时间有条件注册.

### 代码组织

-   `src/FzTextarea.vue`: 主要部件(进口FzAlert、FzIcon)
-   `src/types.ts`: 类型定义(`FzTextareaProps`(中文(简体) )
-   `src/utils.ts`: ID 生成工具`generateTextareaId`(中文(简体) )
-   `src/index.ts`: 公共出口

### 依赖关系

-   `@fiscozen/alert` (工作空间): FzAlert 用于错误消息
-   `@fiscozen/icons` (pier):用于有效检查图标的 FzIcon

### 关键概念

#### 有效的身份证

组件计算 a `effectiveId` 回到自动生成的 ID 当没有明确 `id` 提供了道具。 这确保:

-   标签 `for` 属性总是匹配文本区域 `id`
-   标签 `id` (单位:千美元)`{effectiveId}-label`页:1 `aria-labelledby` 文本区域
-   `aria-describedby` 引用( error/ help ID) 总是有效的
-   错误消息容器 ID (E)`{effectiveId}-error`)和帮助消息ID(`{effectiveId}-help`)是决定性的

#### 自动高度算法

何时 `autoHeight` 启用 :

1.  **挂载**数字 : `measureMetrics()` 读取 `lineHeight`, (中文(简体) ), `paddingTop+paddingBottom`, (中文(简体) ), `borderTopWidth+borderBottomWidth` 从 `getComputedStyle()`。这些是组件寿命的缓存.
2.  **输入时** (单位:千美元)`watch(model)`: `adjustHeight()` 后调用 `nextTick`。它重现 `height` 改为 `"auto"` 这样 `scrollHeight` 然后计算受限高度:如果 `maxRows` 设置和 `scrollHeight > maxRows * lineHeight + paddingY`,它封顶高度和设置 `overflow-y: auto`; 否则 `overflow-y: hidden`。 。 。 .
3.  **`ResizeObserver`**: 监视外部宽度变化(例如容器调整大小),这些变化可以回流文本,调用 `adjustHeight()` 用于重新计算.
4.  **清理**: 观察员已断开 `onBeforeUnmount`。 。 。 .

这个 `autoHeightResizeMap` 对象地图 `resize` 道具值到它们的自发高度等同,在保留水平时会剥去垂直大小.

#### 槽优先级

当两者 `errorMessage` 财务报告和审定财务报表 `helpText` 提供了槽,错误优先(仅在 `error` 道具为真. 这个 `ariaDescribedBy` 计算用途 `useSlots()` (runtime)用于检测提供哪个槽,遵循相同的优先级:出错ID > 帮助ID. 这个匹配 `FzInput`"接近哪里" "这里" `defineSlots` 仅用于类型脚本打字.

### 测试

#### 运行测试

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

#### 测试结构

试验组织在巢中 `describe` 块 :

-   **渲染**: 基本组件渲染, FzAlert 集成
-   **道具**: 每个道具都有自己的道具 `describe` 块
-   **活动**: 本地事件通过 $atters, v- model 转发
-   **展览**数字 : `textareaRef` 可用性和类型
-   **无障碍**: ARIA属性(包括 `aria-labelledby`),角色="提醒",装饰图标,键盘导航
-   **CSS 类**: 静态和动态类应用程序
-   **边缘案件**: null/未定义/空值,特殊字符,合并状态(error+disabled, help+disabled,需要+帮助)
-   **自动高度**: 调整类映射大小, 警告( maxRows 不自动Height, 垂直调整大小), 高度调整, 溢出行为
-   **抓图**: 所有主要州和组合,并有明确的身份证,以促进稳定

#### 稳定

快照测试提供了明确的 `id` 避免自动生成的ID(包含时间戳)的道具在测试运行中引起片面比较.

### 添加特性

1.  更新类型 `src/types.ts` 与联合来文文件
2.  在 `src/FzTextarea.vue`
3.  在其中添加测试 `src/__tests__/FzTextarea.spec.ts`
4.  更新故事书故事 `apps/storybook/src/stories/form/Textarea.stories.ts`
5.  更新 MDX 文档 `apps/storybook/src/FzTextarea.mdx`

### 构建

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

## 中断更改

### 删除 `errorMessage` 财务报告和审定财务报表 `helpMessage` 道具(以槽取代)

这个 `errorMessage` 财务报告和审定财务报表 `helpMessage` 道具已经取出。 错误和帮助内容现在通过命名槽提供,与 `FzInput` 财务报告和审定财务报表 `FzSelect` 模式.

**在此之前:**

```vue
<FzTextarea label="Notes" :error="hasError" errorMessage="Error text" helpMessage="Help text" />
```

**之后:**

```vue
<FzTextarea label="Notes" :error="hasError">
  <template #errorMessage>Error text</template>
  <template #helpText>Help text</template>
</FzTextarea>
```

### 折旧 `size` 道具

这个 `size` 道具被接受但被忽略. 文本区总是使用 `text-base` (16px) (英语). 当任何值被传递时都会发出运行时间警告 。 将在下一个主要版本中删除.

### 删除 `FzTextareaEvents` 类型和明确事件

原生DOM活动(`blur`, (中文(简体) ), `focus`, (中文(简体) ), `paste`不再通过下列方式宣布: `defineEmits`自动传送给本地人 `<textarea>` 通过 `v-bind="$attrs"` (与 `inheritAttrs: false`) (中文(简体) ). 这个 `FzTextareaEvents` 类型已经从出口中删除.

**在此之前:**

```vue
<FzTextarea label="Notes" @blur="onBlur" />
<!-- Worked via defineEmits + explicit emit('blur', $event) -->
```

**之后:**

```vue
<FzTextarea label="Notes" @blur="onBlur" @keydown="onKeydown" />
<!-- Works via $attrs forwarding. Any native event is supported. -->
```

## 常见问题

### @fiscozen/textarea 是什么？

设计系统文本区组件

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

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

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

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

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

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

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

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

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

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

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