声明

!重要提醒: 在绝大多数情况下在应用程序中都不应该直接使用Input组件, 而应使用TextInput等其它封装好组件. Input组件存在的目的是用于创建自定义的输入组件, 它提供共享的样式和功能. 它没有被设计用于直接使用.

Input组件是一个多态组件, 因此并不一定渲染为input元素(虽然大多数情况下如此). 它可以渲染为任意元素, 同时具有输入的外观.

@rtdui/*中的 TextInput,NumberInput, Textarea, JsonInput, Select等等具有输入外观的组件都是基于Input组件构建的.

功能

Input组件提供了共享的样式和功能.

左侧和右侧节

Input组件支持 leftSection 和 rightSection 属性. 可以在输入框左右两侧自定义的渲染任意内容. 两侧的内容会被绝对定位分别放置到包裹容器的两侧.

• leftSection / rightSection属性
  React.ReactNode 类型, 渲染自定义内容
• leftSectionWidth / rightSectionWidth属性
  输入元素会使用paddingLeft和paddingRight为左右两侧的留出空间. 由于左右两侧是自定义的内容, 输入元素的padding大小未知. 因此需要使用leftSectionWidth和rightSectionWidth属性指明宽度.
• leftSectionPointerEvents / rightSectionPointerEvents属性
  控制CSS的pointer-events值.
  大多数情况, 你只想在左或右侧渲染一个图标, 这种情况下应该忽略左或右侧元素的指针事件, 防止干扰到输入元素. 这是默认设置.
  如果左或右侧是一个按钮, 则不应该忽略指针事件, 此时可以设置leftSectionPointerEvents/rightSectionPointerEvents为"auto"

pointer属性

不同的渲染元素应具有不同的鼠标形态. 比如, input元素应该是输入形态, select元素应该是手指形态.

由于Input组件是多态的, 因此无法确定鼠标应具有的形态, Input组件的pointer属性用于指明是否将鼠标显示为手指形态.

error以及error样式

Input组件的error属性可以是任意的React内容.

多态

Input组件是一个多态组件, as属性的默认值为input, 可以设置为任意元素

---

Input子组件

Input附带了一组子组件:

• Input.Wrapper 封装组件
  Input.Wrapper内部已经包含了Input.Label,Input.Error,Input.Description组件.
  Input.Wrapper使用垂直布局模式, 这种布局模式适用于绝大多数场景, 无论是移动端还是PC端.
• Input.Placeholder 当输入不是input或原生不支持placeholder属性时, 用于模拟原生占位内容
  Input.Placeholder应当作为Input的孩子元素
• Input.Label 用于脱离Input.Wrapper独立的显示标签内容
• Input.Error 用于脱离Input.Wrapper独立的显示错误内容
• Input.Description 用于脱离Input.Wrapper独立的显示帮助或描述内容

注意正确的使用:

import { Input, TextInput } from "@rtdui/core";

// Incorrect usage, input is not accessible
function Incorrect() {
  return (
    <Input.Wrapper label="Input label">
      <Input />
    </Input.Wrapper>
  );
}

// Use InputBase or TextInput instead of Input everywhere you want to use Input,
// it is accessible by default and includes Input.Wrapper
function Correct() {
  return <InputBase label="Input label" description="Input description" />;
}

---

InputBase 组件

InputBase组件是用Input.Wrapper和Input正确封装好了的组件, 所有高层的输入组件(如:TextInput,NumberInput,JsonInput,Textarea,Select等)都基于InputBase构建的.

InputBase组件也是一个多态组件.

你可以基于InputBase组件构建自己的输入组件.

InputBase组件的inputWrapperOrder属性(会传递给Input.Wrapper)用于配置label, input, error 和 description顺序. 默认顺序为: ["label", "description", "input", "error"]

tips: 不必指定所有部分, 可以只指定需要的部分, 未指定部分或者未指定对应的属性值都不会渲染.

---

自定义布局

当Input.Wrapper的垂直布局不满足你的要求时, Input.Label, Input.Description, Input.Error 和 Input.Placeholder组件可用于构建自定义的表单布局.

比如下面的例子使用按钮作为输入, 标签和输入使用水平布局模式, 由于按钮不支持placeholder特性, 因此还使用了Input.Placeholder模拟占位内容: