Input

Input 是纯 GPUI、支持 IME 的单行文本输入。编辑状态由调用方持有的 Entity<InputState> 保存；组件不引入 Root、Provider 或注册流程。

基础用法

Basic 只包含稳定 ID、状态、placeholder 与可访问名称。

正在加载组件预览...

在独立页面打开

pub(super) struct InputBasicDemo {
    state: gpui::Entity<InputState>,
}

impl InputBasicDemo {
    pub(super) fn new(cx: &mut Context<PreviewApp>) -> Self {
        Self {
            state: cx.new(|cx| InputState::new("", cx)),
        }
    }

    fn input(&self) -> Input {
        Input::new("name-input", self.state.clone())
            .placeholder("请输入名称")
            .aria_label("名称")
    }
}

输入类型

Search

InputType::Search 提供搜索语义；搜索图标、clear 与 Enter 提交由现有组合能力显式组成。

正在加载组件预览...

在独立页面打开

let example = div()
    .flex()
    .flex_col()
    .gap(px(10.))
    .child(
        Input::new("typed-search-input", self.search.clone())
            .input_type(InputType::Search)
            .placeholder(placeholder)
            .aria_label(label)
            .prefix(Icon::new(IconName::Search))
            .clearable(InputClear::new(clear))
            .on_submit_in(cx, move |this, value, _, cx| {
                this.input_demo.search_status = match language {
                    PreviewLang::ZhCn => format!("已搜索：{value}"),
                    PreviewLang::EnUs => format!("Searched: {value}"),
                }
                .into();
                cx.notify();
            }),
    )
    .child(status);

Password

Password 默认按 grapheme 使用固定字符掩码。示例由宿主控制显隐状态，并用 Eye/EyeOff IconButton 提供随状态变化的可访问名称、Tooltip 与 selected/toggled 语义。

正在加载组件预览...

在独立页面打开

let revealed = self.password_revealed;
let action_label = if revealed { hide } else { show };
let action_icon = if revealed {
    IconName::EyeOff
} else {
    IconName::Eye
};
let example = Input::new("password-input", self.password.clone())
    .input_type(InputType::Password)
    .password_revealed(revealed)
    .aria_label(input_label)
    .suffix(
        IconButton::new("password-reveal", action_icon)
            .variant(IconButtonVariant::Ghost)
            .size(ComponentSize::Xs)
            .selected(revealed)
            .aria_label(action_label)
            .tooltip(action_label)
            .on_click_in(cx, |this, _, window, cx| {
                this.input_demo.password_revealed = !this.input_demo.password_revealed;
                let focus = this.input_demo.password.read(cx).focus_handle().clone();
                window.focus(&focus, cx);
                cx.notify();
            }),
    );

隐藏态允许粘贴，但禁止复制和剪切；显示态恢复普通复制和剪切。显隐切换不会改变真实 value、选区、IME 或撤销历史，也不会发送 Changed。隐藏与显示都保持 PasswordInput 角色。

Email、Phone 与 Url

正在加载组件预览...

在独立页面打开

let example = div()
    .flex()
    .flex_col()
    .gap(px(8.))
    .child(
        Input::new("email-input", self.email.clone())
            .input_type(InputType::Email)
            .aria_label(email),
    )
    .child(
        Input::new("phone-input", self.phone.clone())
            .input_type(InputType::Phone)
            .aria_label(phone),
    )
    .child(
        Input::new("url-input", self.url.clone())
            .input_type(InputType::Url)
            .aria_label(url),
    );

这些类型只提供正确语义，不会自动验证、格式化或过滤字符；业务校验仍由宿主负责。

InputType	AccessKit 角色	额外行为
Text	TextInput	默认普通单行文本。
Search	SearchInput	不自动添加图标、clear 或提交逻辑。
Password	PasswordInput	默认安全掩码；可受控显示。
Email	EmailInput	无自动邮箱校验。
Phone	PhoneNumberInput	无自动格式化或字符过滤。
Url	UrlInput	无自动 URL 校验。

组合能力

Prefix、suffix 与 clear

三个能力保持独立：slot 子组件拥有自己的角色、焦点与事件；InputClear 复用 IconButton，并强制调用方提供可访问名称。

正在加载组件预览...

在独立页面打开

let example = Input::new("affix-input", self.affixes.clone())
    .aria_label(label)
    .prefix(Icon::new(IconName::Search))
    .clearable(InputClear::new(clear).tooltip(clear))
    .suffix(div().text_size(px(12.)).child("⌘ K"));

Input Group

把相同尺寸的 Button 放入 attached_suffix，即可得到共用外框、全高操作区与主题分隔线。

正在加载组件预览...

在独立页面打开

let example = Input::new("search-input", self.search_text.clone())
    .size(ComponentSize::Md)
    .placeholder(placeholder)
    .aria_label(label)
    .attached_suffix(
        Button::new("search-button")
            .label(label)
            .variant(ButtonVariant::Ghost)
            .size(ComponentSize::Md)
            .on_click(|_, _, _| {
                // 执行搜索。
            }),
    );

外观与状态

正在加载组件预览...

在独立页面打开

let example = div().flex().flex_col().gap(px(8.)).children(
    [
        InputVariant::Outline,
        InputVariant::Filled,
        InputVariant::Borderless,
        InputVariant::Underline,
    ]
    .into_iter()
    .zip(self.variants.iter().cloned())
    .enumerate()
    .map(|(index, (variant, state))| {
        Input::new(("input-variant", index), state)
            .variant(variant)
            .aria_label(format!("{variant:?} Input"))
    }),
);

Outline 是默认完整边框；Filled 使用填充表面；Borderless 保留焦点与错误反馈；Underline 只显示底线。

正在加载组件预览...

在独立页面打开

let example = div().flex().flex_col().gap(px(8.)).children(
    [
        ComponentSize::Xs,
        ComponentSize::Sm,
        ComponentSize::Md,
        ComponentSize::Lg,
    ]
    .into_iter()
    .zip(self.sizes.iter().cloned())
    .enumerate()
    .map(|(index, (size, state))| {
        Input::new(("input-size", index), state)
            .size(size)
            .aria_label(format!("{size:?} Input"))
    }),
);

ComponentSize::{Xs, Sm, Md, Lg} 的高度分别为 24、32、36、40 px。Input 默认填满父容器宽度，文本 viewport 可收缩并水平滚动。

正在加载组件预览...

在独立页面打开

let example = div()
    .flex()
    .flex_col()
    .gap(px(8.))
    .child(
        Input::new("input-invalid", self.invalid.clone())
            .invalid(true)
            .aria_label("Invalid Input"),
    )
    .child(
        Input::new("input-read-only", self.read_only.clone())
            .read_only(true)
            .aria_label("Read-only Input"),
    )
    .child(
        Input::new("input-disabled", self.disabled.clone())
            .disabled(true)
            .aria_label("Disabled Input"),
    );

invalid、read_only 与 disabled 均由宿主显式传入。disabled 离开普通 Tab 顺序并拒绝输入、选区和 SetValue；read-only 仍可聚焦、选择和复制普通文本，但拒绝修改。

IME 与语义事件

正在加载组件预览...

在独立页面打开

let example = div()
    .flex()
    .flex_col()
    .gap(px(10.))
    .child(
        Input::new("observable-input", self.observable.clone())
            .aria_label(label)
            .placeholder(placeholder)
            .on_change_in(cx, |this, value, _, cx| {
                this.input_demo.observable_status = format!("Changed: {value}").into();
                cx.notify();
            })
            .on_submit_in(cx, |this, value, _, cx| {
                this.input_demo.observable_status = format!("Submitted: {value}").into();
                cx.notify();
            })
            .on_focus_in(cx, |this, _, cx| {
                this.input_demo.observable_status = "Focused".into();
                cx.notify();
            })
            .on_blur_in(cx, |this, _, cx| {
                this.input_demo.observable_status = "Blurred".into();
                cx.notify();
            }),
    )
    .child(status);

InputState::value() 始终返回真实值。用户输入、删除、显示态 cut、paste、undo、redo、IME commit 与内置 clear 仅在值实际变化时发送一次 Changed；IME preedit 保持静默。非组合状态下按 Enter 发送 Submitted。set_value、clear 与 reset 是程序化操作，不发送用户语义事件。

set_value 表示宿主同步权威值：值实际变化时会结束组合并清空旧的 undo/redo 历史，之后撤销不会跨过这次外部同步边界。clear 沿用相同语义；reset 还会重置选区、组合、滚动与布局缓存。IME 返回的 UTF-16 选区会依据更新后的完整文本归一到 grapheme 边界。

键盘与无障碍

• 左右方向键按 grapheme 移动；平台单词修饰键按词移动。Home/End、Shift 选择、Backspace/Delete、Select All 与 Undo/Redo 均可用。
• macOS 使用 Option+Backspace/Delete 按词删除、Command+Backspace/Delete 删除到行首/行尾；Windows/Linux 使用各平台已有的 Control 修饰键规则。
• 只接受明确支持的修饰键组合；未识别组合继续冒泡。
• 实际 editor 节点使用对应 InputType 角色；prefix、suffix 与 attached suffix 保持独立无障碍子树。
• AccessKit 的可选择字符单位与编辑器一致，使用扩展 grapheme；ZWJ emoji 与组合字符不会暴露字素内部停点。
• Password 隐藏态的绘制文本、无障碍 value 与 synthetic text runs 只包含掩码，不包含明文。

API

API	说明
Input::new(id, Entity<InputState>)	创建绑定稳定 ID 与调用方状态的 Input。
input_type(InputType)	设置 Text、Search、Password、Email、Phone 或 Url 语义。
password_revealed(bool)	受控 Password 显示状态；默认 false，其他类型忽略。
placeholder, aria_label, aria_description	文本与无障碍元数据。
variant, size, caret_color	视觉配置。
disabled, read_only, invalid	外部状态。
prefix, suffix, attached_suffix, clearable	可组合 slot 与内置清除。
on_change, on_submit, on_focus, on_blur	用户语义事件及 Entity 绑定 _in 版本。

Input 实现 Changeable<SharedString>、Focusable、Disableable 和 Sizable，不实现 Clickable。

主题、响应式与跨平台

Light、Dark 与 System 通过当前主题解析边框、表面、文字、placeholder、selection、caret 与状态颜色。Input 在可用宽度内收缩，slot 过多时编辑区会被压缩。组件使用 GPUI 跨平台文本与输入法接口；平台快捷键遵循 macOS 与 Windows/Linux 的各自约定。

自定义主题现在必须在 ResolvedTheme::from_tokens 构造阶段完整提供并验证所有 Input token；缺键、类型错误或无效引用会直接返回 ThemeError，不再从旧主题静默回退。迁移自定义主题时补齐四种 variant、七种 visual state 与四种 size，并把字符串访问改为不可失败的 input_state(InputVariantKind, InputVisualState) 和 input_size(ThemeSize)。

性能契约

• 正常规模：64KiB 与 1MiB；16MiB 为压力规模。
• 64KiB 更新+绘制目标 ≤4ms，1MiB 目标 ≤16.67ms；16MiB 要求线性、无 OOM，不承诺单帧完成。
• 程序化等规模替换会清空 undo/redo，不保留旧文本。普通文本绘制只 shape 包含 active target 的最多 64KiB 窗口；AccessKit 文本 run 使用流式有界分块。
• 等规模更新 allocated bytes 目标不超过输入大小 8 倍；当前 1MiB 完整更新+绘制约 1.74MB，详见 PERFORMANCE.md。
• 基准：input/state、input/render、input/interaction_and_draw；参见基准指南。

已知限制

• 仅支持单行纯文本，不提供多行、Number、Date、Time、格式化模板或内建校验消息。
• Email、Phone 与 Url 不承诺自动验证；Password 不提供自定义 mask 字符。
• slot 的业务状态、加载与错误处理由宿主负责。
• Web 预览依赖浏览器 WebGPU 与文档宿主提供的字体资源。