# @cypress-design/vue-textbox 中文文档

规范地址：https://npmcn.com/package/%40cypress-design/vue-textbox/

版本：1\.0\.1
npm 元数据更新时间：2026-02-02T17:11:42.329Z
中文译文更新时间：2026-11-11T07:31:39.182Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cypress-design/vue-textbox
原文对照：https://npmcn.com/package/%40cypress-design/vue-textbox/?lang=original

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

- 包体积（解压后）：155 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-02T17:11:41.723Z
- 最新版本发布：2026-02-02T17:11:42.058Z
- 近 30 天下载量：4997（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

## 安装

## 安装

```sh
npm install @cypress-design/vue-textbox
```

也可以使用：`pnpm add @cypress-design/vue-textbox`、`yarn add @cypress-design/vue-textbox`、`bun add @cypress-design/vue-textbox`

## README

# 文本框

## 安装

文本框组件载于 `@cypress-design/vue-textbox` 软件包。 你也想安装 `@cypress-design/constants-textbox` 以获取 TypeScript 的适当类型.

```bash
npm install @cypress-design/vue-textbox @cypress-design/constants-textbox
```

或者用纱线

```bash
yarn add @cypress-design/vue-textbox @cypress-design/constants-textbox
```

## 使用量

```ts
import Textbox from '@cypress-design/vue-textbox'
```

```vue
<script lang="ts" setup>
import { IconShapeLightningBolt } from '@cypress-design/vue-icon'
import Textbox from '@cypress-design/vue-textbox'
</script>

<template>
  <Textbox :icon-left="IconShapeLightningBolt" placeholder="Search..." />
</template>
```

## 可能的变体

文本框组件支持四个变体: `default`, (中文(简体) ), `valid`, (中文(简体) ), `invalid`,以及 `warning`。每个变体具有不同的视觉造型来表示输入状态.

### 占位符

所有带有占位符文本的变体 :

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
</script>

<template>
  <div class="bg-white p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox variant="default" placeholder="Default placeholder" />
      <Textbox variant="valid" placeholder="Valid placeholder" />
      <Textbox variant="invalid" placeholder="Invalid placeholder" />
      <Textbox variant="warning" placeholder="Warning placeholder" />
    </div>
  </div>
</template>
```

### 类型

所有具有数值的变体 :

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
</script>

<template>
  <div class="bg-white p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox variant="default" value="Default" />
      <Textbox variant="valid" value="Valid" />
      <Textbox variant="invalid" value="Invalid" />
      <Textbox variant="warning" value="Warning" />
      <Textbox disabled value="Disabled" />
    </div>
  </div>
</template>
```

### 黑暗模式

所有带有占位符的暗模式变体 :

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
</script>

<template>
  <div class="bg-gray-1000 p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox theme="dark" variant="default" placeholder="Default" />
      <Textbox theme="dark" variant="valid" placeholder="Valid" />
      <Textbox theme="dark" variant="invalid" placeholder="Invalid" />
      <Textbox theme="dark" variant="warning" placeholder="Warning" />
    </div>
  </div>
</template>
```

所有带有数值的暗模式变体:

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
</script>

<template>
  <div class="bg-gray-1000 p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox theme="dark" variant="default" value="Default" />
      <Textbox theme="dark" variant="valid" value="Valid" />
      <Textbox theme="dark" variant="invalid" value="Invalid" />
      <Textbox theme="dark" variant="warning" value="Warning" />
      <Textbox theme="dark" disabled value="Disabled" />
    </div>
  </div>
</template>
```

## 大小

文本框支持三个大小: `32`, (中文(简体) ), `40` (违约)和 `48`。 。 。 .

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
</script>

<template>
  <div class="bg-white p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox size="32" value="Size 32" />
      <Textbox size="40" value="Size 40" />
      <Textbox size="48" value="Size 48" />
    </div>
  </div>
</template>
```

暗模式 :

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
</script>

<template>
  <div class="bg-gray-1000 p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox theme="dark" size="32" value="Size 32" />
      <Textbox theme="dark" size="40" value="Size 40" />
      <Textbox theme="dark" size="48" value="Size 48" />
    </div>
  </div>
</template>
```

## 四舍五入

文本框支持一个 `rounded` 在圆角和正角之间切换道具. 在此显示大小 40px :

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
</script>

<template>
  <div class="bg-white p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox size="40" :rounded="false" value="Not rounded" />
      <Textbox size="40" :rounded="true" value="Rounded" />
    </div>
  </div>
</template>
```

暗模式 :

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
</script>

<template>
  <div class="bg-gray-1000 p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox theme="dark" size="40" :rounded="false" value="Not rounded" />
      <Textbox theme="dark" size="40" :rounded="true" value="Rounded" />
    </div>
  </div>
</template>
```

## 选项

文本框支持可选元素的各种组合. 左右有标签的大小 :

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
import { IconShapeLightningBolt } from '@cypress-design/vue-icon'
</script>

<template>
  <div class="bg-white p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox
        :divider="true"
        size="32"
        label-left="Label left"
        label-right="Label right"
        value="Size 32"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        size="40"
        label-left="Label left"
        label-right="Label right"
        value="Size 40"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        variant="valid"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        variant="invalid"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        variant="warning"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        disabled
        :divider="true"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="disabled"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :rounded="true"
        :divider="true"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
    </div>
  </div>
</template>
```

暗模式 :

```vue
<script lang="ts" setup>
import Textbox from '@cypress-design/vue-textbox'
import { IconShapeLightningBolt } from '@cypress-design/vue-icon'
</script>

<template>
  <div class="bg-gray-1000 p-4 rounded">
    <div class="flex flex-col gap-4">
      <Textbox
        :divider="true"
        theme="dark"
        size="32"
        label-left="Label left"
        label-right="Label right"
        value="Size 32"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        theme="dark"
        size="40"
        label-left="Label left"
        label-right="Label right"
        value="Size 40"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        theme="dark"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        theme="dark"
        variant="valid"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        theme="dark"
        variant="invalid"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :divider="true"
        theme="dark"
        variant="warning"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        disabled
        :divider="true"
        theme="dark"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="disabled"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
      <Textbox
        :rounded="true"
        theme="dark"
        :divider="true"
        size="48"
        label-left="Label left"
        label-right="Label right"
        value="Size 48"
        :icon-left="IconShapeLightningBolt"
        :icon-right="IconShapeLightningBolt"
      />
    </div>
  </div>
</template>
```

## 模板参考文件

Textbox 组件支持模板 refs,允许您直接访问基本的输入元素 :

```vue
<template>
  <div>
    <Textbox ref="inputRef" placeholder="Type here..." />
    <button @click="handleFocus">Focus Input</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import Textbox from '@cypress-design/vue-textbox'

const inputRef = ref<InstanceType<typeof Textbox> | null>(null)

const handleFocus = () => {
  // Access the input element through the component instance
  const input = inputRef.value?.$el?.querySelector('input')
  input?.focus()
}
</script>
```

这对于:

-   方案重点投入
-   访问输入方法 `select()`, (中文(简体) ), `setSelectionRange()`
-   与需要直接DOM访问的第三方图书馆合并

## 键盘事件处理器

Textbox 组件支持键盘事件处理器进行高级交互:

```vue
<template>
  <Textbox
    placeholder="Press Enter..."
    @keydown="handleKeyDown"
    @keyup="handleKeyUp"
  />
</template>

<script setup lang="ts">
import Textbox from '@cypress-design/vue-textbox'

const handleKeyDown = (e: KeyboardEvent) => {
  if (e.key === 'Enter') {
    console.log('Enter pressed')
  }
}

const handleKeyUp = (e: KeyboardEvent) => {
  console.log('Key released:', e.key)
}
</script>
```

### 可用的键盘事件

-   **@ 键下**: 键被按下时已开火
-   **@ 键盘@ label**: 键被放出时被放出

## 常见输入属性

文本框组件支持所有标准的 HTML 输入属性. 这包括:

### 窗体属性

-   **只读**: 使输入只读
-   **所需经费**: 标记窗体验证所需的输入
-   **名称**: 提交表格的输入名称
-   **表单**: 有窗体元素的关联输入

### 验证属性

-   **最大长度**: 最大字符数
-   **分长**: 最小字符数
-   **模式**: 用于验证的正则表达式模式
-   **标题**: 校验错误时显示的工具提示文本

### 其他属性

-   **只读**: 只读的别名
-   **选项卡**: 标签顺序
-   **自动补全**: 自动完成行为
-   **拼写检查**: 启用/禁用拼写检查

示例

```vue
<Textbox
  placeholder="Username"
  name="username"
  required
  maxlength="20"
  minlength="3"
  pattern="[a-zA-Z0-9]+"
  title="Username must be 3-20 alphanumeric characters"
/>
```

## 实际世界使用案例

### 带有验证的窗体输入

```vue
<template>
  <div>
    <Textbox
      type="email"
      placeholder="Email"
      v-model="email"
      @blur="validateEmail"
      :variant="error ? 'invalid' : 'default'"
      :aria-describedby="error ? 'email-error' : undefined"
    />
    <div v-if="error" id="email-error">{{ error }}</div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import Textbox from '@cypress-design/vue-textbox'

const email = ref('')
const error = ref('')

const validateEmail = () => {
  if (!email.value.includes('@')) {
    error.value = 'Invalid email address'
  } else {
    error.value = ''
  }
}
</script>
```

### 用键盘快捷键搜索输入

```vue
<template>
  <Textbox
    ref="inputRef"
    :icon-left="IconShapeLightningBolt"
    placeholder="Search (press / to focus)"
    @keydown="handleKeyDown"
  />
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'
import Textbox from '@cypress-design/vue-textbox'
import { IconShapeLightningBolt } from '@cypress-design/vue-icon'

const inputRef = ref<InstanceType<typeof Textbox> | null>(null)

const handleKeyDown = (e: KeyboardEvent) => {
  if (e.key === 'Escape') {
    const input = inputRef.value?.$el?.querySelector('input')
    input?.blur()
  }
}

onMounted(() => {
  const handleKeyPress = (e: KeyboardEvent) => {
    if (
      e.key === '/' &&
      e.target !== inputRef.value?.$el?.querySelector('input')
    ) {
      e.preventDefault()
      const input = inputRef.value?.$el?.querySelector('input')
      input?.focus()
    }
  }

  window.addEventListener('keydown', handleKeyPress)
  onUnmounted(() => {
    window.removeEventListener('keydown', handleKeyPress)
  })
})
</script>
```

### 用 Debouncing 控制输入

```vue
<template>
  <div>
    <Textbox v-model="value" placeholder="Search..." />
    <p>Searching for: {{ debouncedValue }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue'
import Textbox from '@cypress-design/vue-textbox'

const value = ref('')
const debouncedValue = ref('')

let timeoutId: ReturnType<typeof setTimeout>

watch(value, (newValue) => {
  clearTimeout(timeoutId)
  timeoutId = setTimeout(() => {
    debouncedValue.value = newValue
  }, 300)
})
</script>
```

## 道具

(props段将由vue-docgen-cli自动生成)

## 常见问题

### @cypress-design/vue-textbox 是什么？

安装

### 如何安装 @cypress-design/vue-textbox？

在项目目录运行 npm install @cypress-design/vue-textbox，或使用 pnpm add / yarn add / bun add。

### @cypress-design/vue-textbox 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cypress-design/vue-textbox 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cypress-design/vue-textbox 可以商用吗？

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

### @cypress-design/vue-textbox 的下载量有多少？

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

### @cypress-design/vue-textbox 还在维护吗？

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