Input 输入框

基础用法

受控值走 value + ptChange。ptChange 在每一次输入时触发，不是失焦才触发。

<pt-input placeholder="请输入关键词" clearable></pt-input>

尺寸与状态

<pt-input size="sm" placeholder="小"></pt-input>
<pt-input placeholder="中（默认）"></pt-input>
<pt-input size="lg" placeholder="大"></pt-input>
<pt-input invalid value="格式不对"></pt-input>
<pt-input disabled placeholder="禁用"></pt-input>

搜索框

搜索框

type="search" 内置放大镜，有值时按 Esc 清空（先 ptClear 再 ptChange("")），且不会把 Esc 冒泡给外层弹窗。给了 prefix 插槽就替换掉放大镜。

<pt-input type="search" size="sm" placeholder="小"></pt-input>
<pt-input type="search" placeholder="搜索报表" clearable></pt-input>
<pt-input type="search" size="lg" placeholder="大"></pt-input>

type="search" 是搜索框形态：

前缀位置内置放大镜（sm / md 16px、lg 20px）。它是 prefix 插槽的后备内容 —— 给了 prefix 插槽就整个换成使用方的，不会并排出现两个图标。
内部 input 标 role="searchbox"，浏览器原生的清除 ✕ 与装饰都去掉了；要清空按钮就加 clearable。
有值时按 Esc 清空，与点清空按钮同一条路径：先发 ptClear，再发 ptChange('')。这一下 Esc 会被截住，不会冒泡去关外层的弹窗 / 抽屉；值为空时 Esc 照常往外走。

清空按钮的读屏文案默认取 locale 注册表（「清空」/ "Clear"），只想改这一处时用 clear-label：

html

<pt-input type="search" clearable clear-label="清除搜索词" aria-label="搜索报表"></pt-input>

日期与时间

日期与时间

date / time / datetime-local / month / week 原样交给原生 input，值是原生格式的字符串，min / max / step 按原生语义生效。

<pt-input type="date" value="2026-09-23" min="2026-01-01"></pt-input>
<pt-input type="time" value="09:30" step="900"></pt-input>
<pt-input type="datetime-local" value="2026-09-23T09:30"></pt-input>
<pt-input type="month" value="2026-09"></pt-input>
<pt-input type="week" value="2026-W39"></pt-input>

date / time / datetime-local / month / week 原样透传给原生 input，选择器是浏览器自己的。值是原生格式的字符串（2026-09-23、09:30、2026-09-23T09:30、2026-09、2026-W39）， min / max 写同样格式，step 按原生语义计（time 以秒为单位，date 以天）。

样式定制

CSS 变量	说明
`--pt-input-radius`	圆角，默认随尺寸档位
`--pt-input-border-width`	描边宽度，默认 1px。拼进输入组时在容器上设 0，由外层统一描边

两者都可以设在任意祖先容器上，对里面所有输入框生效。

受控值

表单类组件统一 value + ptChange。

ptChange 不是原生 change

ptChange 在每一次输入时触发，不是原生 change 的「失焦才触发」。它是受控值的唯一出口，Vue 的 v-model 和 Angular 的 ngModel 都绑在它上面 —— 改成失焦才发，双向绑定会在用户打字时整段落后。

需要「提交时」语义请监听 ptBlur。

表单参与

组件是 form-associated 的，参与原生表单的提交、重置与校验：

html

<form>
  <pt-input name="email" type="email" required></pt-input>
  <pt-button type="submit">订阅</pt-button>
</form>

表单重置时回到初始值，不是空字符串 —— 与原生 <input> 的行为一致。

API

属性

属性	Attribute	类型	默认值	说明
`ariaLabelText`	`aria-label`	`string \| undefined`	`—`	无障碍名称：原生 HTML 里写 aria-label，React / Vue / Angular 包装层里属性名是 ariaLabelText。没有可见 label 时必须给。
`autocomplete`	`autocomplete`	`string \| undefined`	`—`	透传给原生 input 的 autocomplete（如 "email"、"one-time-code"、"off"），浏览器据此决定自动填充。
`clearLabel`	`clear-label`	`string \| undefined`	`—`	清空按钮的无障碍名称。不传时取 locale 注册表里的 `input.clear`（「清空」/ "Clear"），只想改这一处的说法时用它，不必 registerLocale() 覆盖全局（docs/component-api.md §11）。
`clearable`	`clearable`	`boolean`	`false`	显示清空按钮（有值且可编辑时才出现）
`disabled`	`disabled`	`boolean`	`false`	禁用。只反映使用方自己写的值：外层原生 `<fieldset disabled>`、pt-field / pt-field-set 的禁用另经继承通道生效，不改写它
`inheritedDisabled`	`inherited-disabled`	`boolean`	`false`	外层 pt-field / pt-field-set 下发的禁用。内部继承通道：由它们以 attribute 维护，不建议使用方直接写。有效禁用是 `disabled` 与它的并集；父元素只写这一条、不碰 `disabled`，读 `el.disabled` 得到的始终是使用方自己写的值
`inheritedInvalid`	`inherited-invalid`	`boolean`	`false`	外层 pt-field 下发的出错态。内部继承通道：由 pt-field 维护，不建议使用方直接写。有效出错是 `invalid` 与它的并集
`inheritedRequired`	`inherited-required`	`boolean`	`false`	外层 pt-field 下发的必填。内部继承通道：由 pt-field 维护，不建议使用方直接写。有效必填是 `required` 与它的并集
`inputmode`	`inputmode`	`"decimal" \| "email" \| "none" \| "numeric" \| "search" \| "tel" \| "text" \| "url" \| undefined`	`—`	透传给原生 input 的 inputmode，决定移动端弹出哪种虚拟键盘（如 numeric、tel）。只影响键盘，不限制输入内容。
`invalid`	`invalid`	`boolean`	`false`	出错态。校验信息由使用方展示，组件只负责视觉、aria-invalid 与表单校验状态（customError）
`max`	`max`	`number \| string \| undefined`	`—`	type="number" 与日期类（date / time / datetime-local / month / week）的最大值，透传给原生 input。日期类写对应格式的字符串（如 "2026-01-01"、"09:00"）。属性形式传进来的是字符串，所以类型也接受 string。
`maxlength`	`maxlength`	`number \| undefined`	`—`	最大字符数，透传给原生控件：超出后浏览器不再接受键入，程序赋的 value 不受限。它不进宿主的表单校验状态（那里只看 required / invalid）。
`min`	`min`	`number \| string \| undefined`	`—`	type="number" 与日期类（date / time / datetime-local / month / week）的最小值，透传给原生 input。日期类写对应格式的字符串（如 "2026-01-01"、"09:00"）。属性形式传进来的是字符串，所以类型也接受 string。值超出 min / max 或不合 step 时，宿主在外层表单里同样判为无效（form.checkValidity() 为 false），与原生 input 一致。
`minlength`	`minlength`	`number \| undefined`	`—`	最小字符数，透传给原生控件。同 maxlength，它不进宿主的表单校验状态
`name`	`name`	`string \| undefined`	`—`	提交表单时的字段名
`placeholder`	`placeholder`	`string \| undefined`	`—`	占位文案
`readonly`	`readonly`	`boolean`	`false`	只读：能聚焦、能选中复制，不能改。与 disabled 不同，值照常随表单提交
`required`	`required`	`boolean`	`false`	必填：值为空时表单校验报 valueMissing，并标注 aria-required
`size`	`size`	`"lg" \| "md" \| "sm"`	`'md'`	尺寸档位
`step`	`step`	`number \| string \| undefined`	`—`	type="number" 与日期类的步进值（方向键增减的粒度），透传给原生 input。日期类按原生语义计：time / datetime-local 以秒为单位，date 以天、month 以月、week 以周。属性形式传进来的是字符串，所以类型也接受 string。
`type`	`type`	`"date" \| "datetime-local" \| "email" \| "month" \| "number" \| "password" \| "search" \| "tel" \| "text" \| "time" \| "url" \| "week"`	`'text'`	输入类型
`value`	`value`	`string`	`''`	当前值

事件

事件	detail 类型	说明
`ptBlur`	`void`	内部控件失去焦点。需要「提交时」语义的场景监听它，而不是把 ptChange 改成失焦才发
`ptChange`	`string`	值变化。每次输入都会触发，不是失焦才触发，详见组件说明
`ptClear`	`void`	点了清空按钮
`ptFocus`	`void`	内部控件获得焦点

方法

方法	说明
`select() => Promise<void>`
`setFocus(options?: FocusOptions) => Promise<void>`

插槽

名称	说明
`prefix`	输入区前的图标或文案。type="search" 时替换掉内置的放大镜
`suffix`	输入区后的图标或文案

可定制的内部元素（`::part()`）

part	说明
`base`	外层描边容器（与 field 同一元素）
`clear`	清空按钮
`field`	外层描边容器
`input`	内部的 input 元素

CSS 变量

变量	说明
`--pt-input-border-width`	描边宽度，默认 1px。组合进输入组时设 0 由外层容器统一描边
`--pt-input-focus-ring`	聚焦时描边容器的 box-shadow，默认 1px 焦点色（出错态为 2px 30% 危险色）。输入组里设 none，由外层容器画焦点环
`--pt-input-padding-inline`	描边容器的左右内边距，默认取控件档位（12 / 8 / 16px）。输入组里设 0，由外层容器留白
`--pt-input-radius`	圆角，默认取控件档位（md / lg 为 --pt-radius-md，sm 为 --pt-radius-sm）

Input 输入框 ​

搜索框 ​

日期与时间 ​

样式定制 ​

受控值 ​

表单参与 ​

API ​

属性

事件

方法

插槽

可定制的内部元素（::part()）