@ fiscozen/ 输入

Vue 3 应用程序的灵活输入组件库,主要包括图标支持,验证状态,多变体,以及带有数字格式的专门货币输入.

特征

• 多重输入类型: 文本、密码、电子邮件、电话号码、电话、 url
• 图标支持: 左右图标(静态或可点击按钮)
• 审定国: 有视觉反馈的错误和有效状态
• 两个备选案文: 普通和浮动标签演示文稿
• 两个环境: 前台和后台(不同高地和样式)
• 货币投入: 具有地方意识数字格式的专门组件
• 完全无障碍: ARIA属性,键盘导航,屏幕阅读器支持
• 可自定义: 标签、图标、帮助文本和错误消息的槽
• 类型脚本: 具有类型脚本定义的完整类型安全

安装

npm install @fiscozen/input

构成部分

此套件输出三个组件:

• FzInput - 有标签、图标和验证状态的标准输入
• FzCurrencyInput - 有数字格式和验证的专门货币输入
• FzInputLabel - FzInput的标签行,带有所需的星号, truncate 还有一个 aside 右侧的文本; FzSelection 也可以。 直接用它来构建一个自己的领域

基本用途

Fz 输入

<script setup lang="ts">
import { FzInput } from '@fiscozen/input'
import { ref } from 'vue'

const email = ref('')
</script>

<template>
  <FzInput label="Email" type="email" v-model="email" />
</template>

FzCurrent 输入

<script setup lang="ts">
import { FzCurrencyInput } from '@fiscozen/input'
import { ref } from 'vue'

const amount = ref<number | undefined>(undefined)
</script>

<template>
  <FzCurrencyInput label="Amount" v-model="amount" />
</template>

道具

FzInput 支持软件

FzCurrent 输入道具

FzCurrency Input 扩展了 FzInput 道具(但 type, (中文(简体) ), modelValue, (中文(简体) ), rightIcon, (中文(简体) ), rightIconSize, (中文(简体) ), rightIconVariant, (中文(简体) ), rightIconButton, (中文(简体) ), rightIconButtonVariant, (中文(简体) ), rightIconAriaLabel, (中文(简体) ), rightIconClass, (中文(简体) ), secondRightIcon, (中文(简体) ), secondRightIconClass, (中文(简体) ), secondRightIconVariant, (中文(简体) ), secondRightIconButton, (中文(简体) ), secondRightIconButtonVariant, (中文(简体) ), secondRightIconAriaLabel)并补充:

说明数字 : rightIcon 财务报告和审定财务报表 secondRightIcon fzCurrencyInput中没有道具。 仅 valid 复选标记图标可以在步骤控件旁显示.

槽数

备选案文

正常( 默认)

输入字段内带有上方标签和占位符的标准输入.

<FzInput label="Email" type="email" placeholder="Enter your email" v-model="email" />

浮动标签

当焦点或输入有值时,浮动标签变体将占位符移动到输入上方.

<FzInput 
  label="Email" 
  variant="floating-label" 
  placeholder="Enter your email" 
  v-model="email" 
/>

环境

输入支持决定其高度和样式的两个环境:

• 前台办公室 (默认):较大的间隔
• 后台办公室: 紧凑相距

<template>
  <FzInput label="Frontoffice (Default)" environment="frontoffice" v-model="value1" />
  <FzInput label="Backoffice" environment="backoffice" v-model="value2" />
</template>

说明编号: size 道具被贬. 使用 environment 换句话说.

输入类型

文本

<FzInput label="Name" type="text" v-model="name" />

密码

<FzInput label="Password" type="password" v-model="password" />

电子邮件

<FzInput label="Email" type="email" required v-model="email" />

数目

<FzInput label="Age" type="number" v-model="age" />

电话

<FzInput 
  label="Phone" 
  type="tel" 
  pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}" 
  v-model="phone" 
/>

網址

<FzInput label="Website" type="url" v-model="website" />

国家

需求

所需的输入显示标签旁边的星号( *)并设置所需的本地属性 .

<FzInput label="Email" type="email" required v-model="email" />

已禁用

已禁用输入会阻止用户交互,并应用变音的造型.

<FzInput label="Disabled Input" disabled v-model="value" />

错误

出错状态显示红色边框,并通过出错位置显示出错误消息.

<FzInput label="Email" type="email" :error="hasError" v-model="email">
  <template #errorMessage>Please enter a valid email address</template>
</FzInput>

有效

有效状态显示右侧的绿色检查标记图标 .

<FzInput label="Email" type="email" :valid="isValid" v-model="email" />

只读

只读输入会阻止编辑,但保持可聚焦和可见.

<FzInput label="Read-only Value" readonly v-model="readonlyValue" />

带有图标

左边图标

<FzInput 
  label="Date" 
  leftIcon="calendar-lines" 
  v-model="date" 
/>

右图标

<FzInput 
  label="Search" 
  rightIcon="magnifying-glass" 
  v-model="search" 
/>

右图标为按钮

右侧图标可以作为可点击按钮提供(用于密码能见度切换,清除按钮等).

<template>
  <FzInput 
    label="Password" 
    :type="passwordType"
    rightIcon="eye"
    :rightIconButton="true"
    rightIconButtonVariant="secondary"
    rightIconAriaLabel="Toggle password visibility"
    @fzinput:right-icon-click="togglePasswordVisibility"
    v-model="password" 
  />
</template>

<script setup>
import { ref } from 'vue'

const passwordType = ref('password')
const password = ref('')

const togglePasswordVisibility = () => {
  passwordType.value = passwordType.value === 'password' ? 'text' : 'password'
}
</script>

可访问的可点击图标

当图标可以点击时,请提供 leftIconAriaLabel 或者说 rightIconAriaLabel 用于键盘访问:

<FzInput 
  label="Search" 
  leftIcon="magnifying-glass"
  leftIconAriaLabel="Open search options"
  @fzinput:left-icon-click="openSearchOptions"
  v-model="search" 
/>

两个图标

<FzInput 
  label="Amount" 
  leftIcon="dollar-sign" 
  rightIcon="credit-card" 
  v-model="amount" 
/>

帮助文本和错误消息

帮助文本

当没有出错时,请在输入下方显示帮助文本.

<FzInput label="Username" v-model="username">
  <template #helpText>
    Username must be between 3 and 20 characters
  </template>
</FzInput>

错误消息

当错误道具属实时,错误消息会显示在输入下方.

<FzInput label="Email" type="email" :error="hasError" v-model="email">
  <template #errorMessage>
    Please enter a valid email address
  </template>
</FzInput>

自定义标签

您可以使用标签槽提供自定义标签内容 .

<FzInput v-model="value">
  <template #label>
    <strong>Custom Label</strong> with <em>formatting</em>
  </template>
</FzInput>

实例

带有验证的表格

<template>
  <form @submit.prevent="handleSubmit">
    <FzInput 
      label="Email" 
      type="email" 
      required 
      :error="errors.email"
      v-model="form.email"
    >
      <template #errorMessage v-if="errors.email">
        {{ errors.email }}
      </template>
    </FzInput>
    
    <FzInput 
      label="Password" 
      type="password" 
      required 
      :error="errors.password"
      v-model="form.password"
    >
      <template #errorMessage v-if="errors.password">
        {{ errors.password }}
      </template>
    </FzInput>
    
    <button type="submit">Submit</button>
  </form>
</template>

<script setup>
import { ref } from 'vue'

const form = ref({
  email: '',
  password: ''
})

const errors = ref({
  email: null,
  password: null
})

const handleSubmit = () => {
  // Validation logic
}
</script>

有可见度的密码切换

<template>
  <FzInput 
    label="Password" 
    :type="showPassword ? 'text' : 'password'"
    rightIcon="eye"
    :rightIconButton="true"
    @fzinput:right-icon-click="togglePassword"
    v-model="password" 
  />
</template>

<script setup>
import { ref } from 'vue'

const password = ref('')
const showPassword = ref(false)

const togglePassword = () => {
  showPassword.value = !showPassword.value
}
</script>

搜索输入

<FzInput 
  label="Search" 
  leftIcon="magnifying-glass" 
  rightIcon="xmark"
  :rightIconButton="true"
  @fzinput:right-icon-click="clearSearch"
  v-model="searchQuery" 
/>

输入最大长度

<FzInput 
  label="PIN" 
  type="text" 
  maxlength="4" 
  pattern="[0-9]{4}"
  v-model="pin" 
/>

FzCurrent 输入

FzInput上建有数字格式化,验证,和步控的专用货币输入组件. 使用 Intl 格式化值。 Number Format 有本地意识分离器 .

特征

• 本地化数字格式化( 小数和千个分隔符)
• 最小/最大值约束
• 以箭头按钮进行量化
• 智能贴面解析( 自动发现小数/ 千位分隔符)
• 可配置的小数位数

基本用途

<script setup lang="ts">
import { FzCurrencyInput } from '@fiscozen/input'
import { ref } from 'vue'

const amount = ref<number | undefined>(undefined)
</script>

<template>
  <FzCurrencyInput 
    label="Amount" 
    v-model="amount" 
    :min="0" 
    :max="1000" 
  />
</template>

带步控件

步控(arrow 按钮)在FzCurrency Input中总是可见. 默认步骤为 1,但可以定制.

<FzCurrencyInput 
  label="Quantity" 
  v-model="quantity" 
  :step="5"
/>

随步量化

何时 forceStep ,值会自动四舍五入到最接近的多步.

<FzCurrencyInput 
  label="Quantity" 
  v-model="quantity" 
  :step="4"
  :forceStep="true"
/>

受敏/最大限制

<FzCurrencyInput 
  label="Price" 
  v-model="price" 
  :min="0" 
  :max="9999.99"
  :minimumFractionDigits="2"
  :maximumFractionDigits="2"
/>

有有效状态

在步骤控件旁显示有效的检查标记图标 .

<FzCurrencyInput 
  label="Amount" 
  v-model="amount" 
  :valid="isValid"
/>

货币输入行为

• 格式化: 数值采用Intl格式。 带有地语设置的数字格式( 默认为“ it- IT ”)
• 粘贴处理: 自动检测和剖析各种编号格式(例如"1.234,56","1,234.56")
• 步骤控制:箭头按钮总是可见(默认步骤=1). 支持键盘访问( Enter/ Space to active)
• 步骤量化: 当 forceStep 正确, 数值自动四舍五入到最接近的多步
• 空值: 当 nullOnEmpty 真实, 空输入转换为无效而不是 0
• 有效状态: 可以在步骤控件旁显示有效的检查标记图标
• 右图标数字 : rightIcon 财务报告和审定财务报表 secondRightIcon 道具没有。 仅 valid 图标被支持.

v- 型号行为

频率 输入使用 a 类型断言 模式:

• 接受数字 : number | string | undefined 作为投入
• 输出: 永远 number | undefined (从来没有) string(中文(简体) )

类型

本部分接受 number | string | undefined 作为输入,但 总是发出 number | undefined. Strings是自动解析的(意大利格式:"1.234,56"~1234.56)并内部转换为数字.

折旧警告

字符串值被贬值 并将在未来的版本中删除。 使用字符串时显示控制台警告 。 请使用 number | undefined 而不是类型安全和未来的相容性.

建议使用

<script setup lang="ts">
import { ref } from 'vue'

// ✅ Recommended: number | undefined (future-proof)
const amount = ref<number | undefined>(undefined)
</script>

<template>
  <FzCurrencyInput label="Amount" v-model="amount" />
</template>

折旧用法(仍在施工)

<script setup lang="ts">
import { ref } from 'vue'

// ⚠️ Deprecated: string (still works but shows warning)
// Strings are parsed and converted to numbers internally
const amount = ref<string>("1234,56")
</script>

<template>
  <FzCurrencyInput label="Amount" v-model="amount" />
</template>

说明: 当使用字符串时, 组件将:

1. 显示调用控制台警告
2. 使用意大利格式解析字符串( 点=千, 逗号=小数)
3. 内部转换为数字
4. 总是发出一个 number | undefined 价值

移徙指南

如果您正在使用字符串, 请移到数字 :

<!-- Before (deprecated) -->
<script setup lang="ts">
const amount = ref<string>("1234,56")
</script>

<!-- After (recommended) -->
<script setup lang="ts">
const amount = ref<number | undefined>(1234.56)
// or
const amount = ref<number | undefined>(undefined)
</script>

无障碍

FzInput和FzCurrencyInput完全可以访问,符合WCAG 2.1 AA标准:

• ARIA 属性: 适当的aria- required, aria-invalid, aria-disabled, aria-labelledby, aria-descriptableby (英语)
• 键盘导航: 完整的键盘支持(Tab, Enter, Space, Arrow 键)
• 屏幕阅读器: 错误消息和帮助文本与输入有适当的关联
• 重点管理: 有适当对比的可见重点指标
• 语义 HTML: 具有适当标签关联的原生输入元素
• 错误通知: 错误消息使用角色=“ 提醒” 用于即时屏幕阅读器通知

ARIA 属性

• 需要的义和团: 设置为"真"或"假"(Vue 3相容性的字符串值)
• 无效: 当错误道具属实时设定为“ true”
• 离子障碍: 当禁用道具属实时设置为" true"
• 阿里亚-标签by: 提供标签道具时与标签元素的链接
• 阿里亚语描述: 当前帮助文本或错误消息的链接

错误消息可访问性

错误消息以 role="alert" 以确保屏幕阅读器在显示时立即宣布.

行为和概念

标签对 Slot 优先级

当两者 label 提供了道具和标签插槽,插槽优先:

<FzInput label="This won't show">
  <template #label>This will show instead</template>
</FzInput>

右边图标显示顺序

该组件支持三种可以同时显示的右侧图标:

1. valid 检查标记 (当 valid 道具为 true) - 先显示
2. secondRightIcon (提供时) - 显示于第二
3. rightIcon (提供时) - 显示第三

所有三个图标都可以同时可见,从左到右都按这个顺序出现.

浮动标签占位符行为

在浮动标签变体中:

• 当输入为空且不突出重点时:占位符在输入上方显示为浮动文本
• 当输入有值或焦点时:占位符移动到输入上方
• 普通占位符属性隐藏于此模式

图标按钮大小映射

右图标按钮使用比输入小的尺寸来保持视觉平衡:

• 输入大小 sm — 图标按钮大小 xs
• 输入大小 md — 图标按钮大小 sm
• 输入大小 lg — 图标按钮大小 md

页:1

输入类型行为

不同的输入类型提供了不同的键盘布局和验证:

• 电子邮件: 触发移动设备上的电子邮件键盘
• 电话: 移动设备上的触发数键盘
• 编号: 允许带有自旋器控制的数值输入
• 密码: 面具输入字符
• url 密码: 验证 URL 格式

货币输入格式

FzCurrency Input 使用 Intl. Number Format 用于本地化意识格式化. 格式格式格式格式 :

• 浏览器语言设置
• 最小和最大分数
• 十进制和千分法公约

用货币输入粘贴处理

货币输入使用智能heuristic分析粘贴值:

• 多个不同的分隔符: 最右边是小数分隔符
• 多个相同分隔符:千分隔符
• 单位分隔符, 后面为 < 3 位数: 小数分隔符
• 3+位数之后的单位分隔符:模糊,使用默认格式