让开源，少一点语言距离。
npm包中文文档

@cypress-design/vue-textbox

中文文档
1.0.1发布于 2026/02/03MITTypeScriptESM + CJS零依赖近 30 天下载 4997

安装

中文使用文档
中文原文
文档目录21 节
  1. 安装
  2. 使用量
  3. 可能的变体
  4. 占位符
  5. 类型
  6. 黑暗模式
  7. 大小
  8. 四舍五入
  9. 选项
  10. 模板参考文件
  11. 键盘事件处理器
  12. 可用的键盘事件
  13. 常见输入属性
  14. 窗体属性
  15. 验证属性
  16. 其他属性
  17. 实际世界使用案例
  18. 带有验证的窗体输入
  19. 用键盘快捷键搜索输入
  20. 用 Debouncing 控制输入
  21. 道具

文本框

安装

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

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

或者用纱线

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

使用量

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

<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。每个变体具有不同的视觉造型来表示输入状态.

占位符

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

<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>

类型

所有具有数值的变体 :

<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>

黑暗模式

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

<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>

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

<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。 。 。 .

<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>

暗模式 :

<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 :

<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>

暗模式 :

<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>

选项

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

<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>

暗模式 :

<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,允许您直接访问基本的输入元素 :

<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 组件支持键盘事件处理器进行高级交互:

<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 输入属性. 这包括:

窗体属性

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

验证属性

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

其他属性

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

示例

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

实际世界使用案例

带有验证的窗体输入

<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>

用键盘快捷键搜索输入

<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 控制输入

<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 共发布 1 个版本，首次发布于 2026/02/03；过去 12 个月发布了 1 个版本。

版本发布日期距今
1.0.1latest2026/02/039 个月前

关于 @cypress-design/vue-textbox 的常见问题

@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 和提交记录判断。