#Input 输入框
输入单行文本,如姓名、邮箱或搜索关键词。
#基础用法
使用 FormField 为输入框提供名称;占位文字不能替代标签。
basic.tsx
import { Form, FormField, Input } from '@ifhover/leaf-ui';
export function InputBasic() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="项目名称">
<Input name="project" placeholder="为你的项目起个名字" />
</FormField>
</Form>
);
}
#示例
#前后缀
通过 prefix 和 suffix 补充图标或文字。它们作为装饰内容处理,可交互操作应放在输入框外。
affixes.tsx
import { Form, FormField, Input } from '@ifhover/leaf-ui';
import { Search } from 'lucide-react';
export function InputAffixes() {
return (
<Form layout="vertical">
<FormField label="搜索项目">
<Input prefix={<Search />} placeholder="输入关键词" />
</FormField>
<FormField label="域名">
<Input suffix=".com" placeholder="example" />
</FormField>
</Form>
);
}
#密码输入
设置 type="password" 隐藏输入内容。通过 visible 和 onVisibleChange 控制可见状态,visibilityIcon 自定义切换图标,visibilityToggle={false} 隐藏切换按钮。
password.tsx
import { Form, FormField, Input } from '@ifhover/leaf-ui';
import { Eye, EyeOff } from 'lucide-react';
import { useState } from 'react';
export function InputPassword() {
const [visible, setVisible] = useState(false);
return (
<Form layout="vertical">
<FormField label="密码">
<Input type="password" placeholder="请输入密码" autoComplete="new-password" />
</FormField>
<FormField label="受控密码">
<Input
type="password"
defaultValue="leaf-garden"
visible={visible}
onVisibleChange={setVisible}
visibilityIcon={(shown) => (shown ? <EyeOff size={16} /> : <Eye size={16} />)}
/>
</FormField>
<FormField label="无切换按钮">
<Input type="password" placeholder="不展示切换按钮" visibilityToggle={false} />
</FormField>
</Form>
);
}
#清除内容
设置 allowClear 显示清除按钮。清除会触发 onChange,输入值变为空字符串。
clear.tsx
import { Form, FormField, Input, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function InputClear() {
const [value, setValue] = useState('Leaf Garden');
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="项目名称">
<Input value={value} onChange={(event) => setValue(event.target.value)} allowClear />
</FormField>
<Text tone="muted" role="status">
当前内容:{value || '未填写'}
</Text>
</Form>
);
}
#字数统计
使用 showCount 显示或自定义统计,搭配 maxLength 限制输入长度。
count.tsx
import { Form, FormField, Input } from '@ifhover/leaf-ui';
export function InputCount() {
return (
<Form layout="vertical">
<FormField label="默认统计">
<Input defaultValue="Leaf Garden" showCount maxLength={30} />
</FormField>
<FormField label="自定义统计">
<Input defaultValue="Leaf" showCount={(value) => `${value.length} 字`} />
</FormField>
</Form>
);
}
#尺寸
提供 sm、md 和 lg 三种尺寸。
sizes.tsx
import { Form, FormField, Input } from '@ifhover/leaf-ui';
export function InputSizes() {
return (
<Form layout="vertical">
<FormField label="小">
<Input size="sm" placeholder="项目名称" />
</FormField>
<FormField label="中">
<Input size="md" placeholder="项目名称" />
</FormField>
<FormField label="大">
<Input size="lg" placeholder="项目名称" />
</FormField>
</Form>
);
}
#状态
disabled 禁用交互,readOnly 保留可读内容但禁止编辑。status 只显示校验外观,不执行校验;错误信息可通过 FormField 提供。
states.tsx
import { Form, FormField, Input } from '@ifhover/leaf-ui';
export function InputStates() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="只读">
<Input defaultValue="Leaf Garden" readOnly />
</FormField>
<FormField label="禁用">
<Input disabled placeholder="暂时不可编辑" />
</FormField>
<FormField label="错误" error="项目名称不能为空。">
<Input placeholder="请输入项目名称" />
</FormField>
<FormField label="警告">
<Input status="warning" defaultValue="已经存在相似名称" />
</FormField>
</Form>
);
}
#受控输入与回车
通过 value 和 onChange 管理内容。onPressEnter 在按下 Enter 时触发;输入法组合输入中或键盘事件已被阻止时不会触发。
controlled.tsx
import { Form, FormField, Input, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function InputControlled() {
const [value, setValue] = useState('');
const [submitted, setSubmitted] = useState('');
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="输入并回车">
<Input
value={value}
placeholder="输入后按 Enter"
onChange={(event) => setValue(event.target.value)}
onPressEnter={() => setSubmitted(value)}
/>
</FormField>
<Text tone="muted" role="status">
已提交:{submitted || '等待输入'}
</Text>
</Form>
);
}
#搜索输入
InputSearch 在点击搜索按钮或按 Enter 时通过 onSearch 返回输入内容。
search.tsx
import { Form, FormField, InputSearch, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function InputSearchDemo() {
const [query, setQuery] = useState('');
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="搜索项目">
<InputSearch placeholder="输入关键词" enterButton="搜索" onSearch={setQuery} />
</FormField>
<Text tone="muted" role="status">
搜索内容:{query || '未搜索'}
</Text>
</Form>
);
}
#输入组合
使用 InputGroup 连接相邻控件,并为组合中的每个输入分别提供名称。
group.tsx
import { Form, FormField, Input, InputGroup, Select } from '@ifhover/leaf-ui';
import { useId } from 'react';
export function InputGroupDemo() {
const protocolId = useId();
const domainId = useId();
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="网址" htmlFor={domainId}>
<InputGroup aria-label="网址">
<Select
id={protocolId}
aria-label="协议"
style={{ width: 110 }}
defaultValue="https"
options={[
{ value: 'https', label: 'https://' },
{ value: 'http', label: 'http://' },
]}
/>
<Input id={domainId} aria-label="域名" placeholder="example.com" />
</InputGroup>
</FormField>
</Form>
);
}
#API
#Input API
#表单接入
设置 name 可通过 FormData 读取值。非受控字段随表单重置恢复初始值,受控字段需同步重置应用状态。表单标签、帮助与错误的接入见 Form。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
size | 'sm' | 'md' | 'lg' | 'md' | 输入框尺寸 |
status | 'error' | 'warning' | — | 校验状态 |
prefix / suffix | ReactNode | — | 输入内容前后的装饰性内容 |
onPressEnter | KeyboardEventHandler<HTMLInputElement> | — | 按下回车时触发 |
type | HTMLInputTypeAttribute | 'text' | 输入方式,密码使用 'password' |
visibilityToggle | boolean | true | 密码输入框展示切换按钮 |
visible / defaultVisible | boolean | false | 受控密码可见状态 / 初始状态 |
onVisibleChange | (visible: boolean) => void | — | 密码可见状态变化 |
visibilityIcon | (visible: boolean) => ReactNode | — | 自定义密码切换图标 |
value / defaultValue | string | number | readonly string[] | — | 受控值 / 非受控初始值 |
onChange | ChangeEventHandler<HTMLInputElement> | — | 从 event.target.value 读取内容 |
disabled / readOnly | boolean | false | 禁用 / 只读 |
ref | Ref<HTMLInputElement> | — | 输入框引用 |
allowClear | boolean | false | 展示清除按钮 |
onClear | () => void | — | 清除后触发;onChange 同样触发 |
showCount | boolean | ((value: string, maxLength?: number) => ReactNode) | false | 展示或自定义字数统计 |
#InputSearchProps API
搜索输入框的提交行为与操作参数。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
size | 'sm' | 'md' | 'lg' | 'md' | 输入框尺寸。 |
status | 'error' | 'warning' | — | 显示状态 |
prefix | ReactNode | — | 前置内容 |
suffix | ReactNode | — | 后置内容 |
allowClear | boolean | false | 显示清除按钮 |
onClear | () => void | — | 清除输入后触发 |
showCount | boolean | ((value: string, maxLength?: number) => ReactNode) | false | 显示字数,可自定义渲染 |
visibilityToggle | boolean | true | 显示密码切换按钮 |
visible | boolean | — | 受控的密码可见状态 |
defaultVisible | boolean | false | 初始密码可见状态 |
onVisibleChange | (visible: boolean) => void | — | 密码可见状态变化 |
visibilityIcon | (visible: boolean) => ReactNode | — | 自定义密码切换图标 |
onPressEnter | KeyboardEventHandler<HTMLInputElement> | — | 按下 Enter 时触发 |
onSearch | (value: string) => void | — | 搜索或按 Enter 时触发 |
loading | boolean | false | 加载状态 |
enterButton | ReactNode | — | 搜索按钮文字,省略时展示图标 |
#InputGroupProps API
组合多个输入相关控件的参数。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
compact | boolean | — | 连接相邻控件 |