---
name: "Input"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.5.10" }
title: "Input - 输入框"
---

## Input

> [VERSION] @ray-js/ray >= 0.5.10

### 描述

输入框组件，支持多种输入类型和键盘配置。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `value` | `string` | 否 | - | 输入框的内容 |
| `type` | `"text" \| "number" \| "digit"` | 否 | `"text"` | 输入类型 |
| `name` | `string` | 否 | - | 表单控件名称，提交表单时作为键名 |
| `password` | `boolean` | 否 | - | 是否为密码输入框 |
| `placeholder` | `string` | 否 | - | 输入框为空时占位符 |
| `placeholderStyle` | `any \| string` | 否 | - | 占位符的样式 |
| `disabled` | `boolean` | 否 | - | 是否禁用 |
| `maxLength` | `number` | 否 | `140` | 最大输入长度，设置为 -1 的时候不限制最大长度 |
| `confirmType` | `"send" \| "search" \| "next" \| "go" \| "done"` | 否 | `"done"` | 设置键盘右下角按钮的文字，仅在 type='text' 时生效 |
| `onInput` | `(event: InputInputEvent) => void` | 否 | - | 键盘输入时触发 |
| `onConfirm` | `(event: InputConfirmEvent) => void` | 否 | - | 点击完成按钮时触发 |
| `onFocus` | `(event: InputFocusEvent) => void` | 否 | - | 输入框聚焦时触发 |
| `onBlur` | `(event: InputBlurEvent) => void` | 否 | - | 输入框失去焦点时触发 |

### 引用对象

##### `interface` InputInputEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"input"` | 事件类型 |
| `detail` | `InputInputDetail` | 事件数据 |
| `value` | `string` | 输入框当前值 |

##### `interface` InputConfirmEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"confirm"` | 事件类型 |
| `detail` | `InputValueDetail` | 事件数据 |

##### `interface` InputFocusEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"focus"` | 事件类型 |
| `detail` | `InputValueDetail` | 事件数据 |

##### `interface` InputBlurEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"blur"` | 事件类型 |
| `detail` | `InputValueDetail` | 事件数据 |

##### `interface` InputInputDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `value` | `string` | 输入框内容 |
| `cursor` | `number` | 光标位置 |
| `keyCode` | `number` | 键值 |

##### `interface` BaseEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `string` | 事件类型 |
| `timeStamp` | `number` | 页面打开到触发事件所经过的毫秒数 |
| `target` | `Target` | 触发事件的源组件 |
| `currentTarget` | `Target` | 当前组件的一些属性值集合 |
| `mark` | `any` | 事件标记数据 |

##### `interface` InputValueDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `value` | `string` | 输入框内容 |

##### `interface` Target

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 事件源组件的id |
| `dataset` | `Record<string, unknown>` | 事件源组件上的 `dataset` 自定义属性组成的集合 |


### 示例代码

#### 基础用法

```tsx
import React from 'react';
import { Input, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <Input
        placeholder="请输入内容"
        onInput={(e) => console.log('输入:', e.detail.value)}
      />
    </View>
  );
}
```

#### 不同类型

```tsx
import React, { useState } from 'react';
import { Input, View, Text } from '@ray-js/ray';

export default function () {
  const [textValue, setTextValue] = useState('');
  const [numberValue, setNumberValue] = useState('');
  const [passwordValue, setPasswordValue] = useState('');

  return (
    <View style={{ padding: '20px' }}>
      <View style={{ marginBottom: '16px' }}>
        <Text>文本输入:</Text>
        <Input
          type="text"
          placeholder="请输入文本"
          value={textValue}
          onInput={(e) => setTextValue(e.detail.value)}
          style={{ marginTop: '8px' }}
        />
      </View>
      <View style={{ marginBottom: '16px' }}>
        <Text>数字输入:</Text>
        <Input
          type="number"
          placeholder="请输入数字"
          value={numberValue}
          onInput={(e) => setNumberValue(e.detail.value)}
          style={{ marginTop: '8px' }}
        />
      </View>
      <View style={{ marginBottom: '16px' }}>
        <Text>密码输入:</Text>
        <Input
          password
          placeholder="请输入密码"
          value={passwordValue}
          onInput={(e) => setPasswordValue(e.detail.value)}
          style={{ marginTop: '8px' }}
        />
      </View>
    </View>
  );
}
```

#### 输入限制与禁用

```tsx
import React from 'react';
import { Input, View, Text } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <View style={{ marginBottom: '16px' }}>
        <Text>最大长度 10:</Text>
        <Input
          maxLength={10}
          placeholder="最多输入 10 个字符"
          placeholderStyle={{ color: '#ccc', fontSize: '14px' }}
          style={{ marginTop: '8px' }}
        />
      </View>
      <View style={{ marginBottom: '16px' }}>
        <Text>禁用状态:</Text>
        <Input
          disabled
          value="不可编辑"
          style={{ marginTop: '8px' }}
        />
      </View>
      <View style={{ marginBottom: '16px' }}>
        <Text>确认按钮为搜索:</Text>
        <Input
          confirmType="search"
          placeholder="输入后点键盘搜索"
          onConfirm={(e) => console.log('确认:', e.detail.value)}
          onFocus={(e) => console.log('聚焦:', e.detail.value)}
          onBlur={(e) => console.log('失焦:', e.detail.value)}
          style={{ marginTop: '8px' }}
        />
      </View>
    </View>
  );
}
```


### 常见问题

#### 输入框是否支持点击事件，比如 tap、touch？

支持，所有的组件都支持 `tap`、`touch` 事件

#### input 如何用 js 代码清空数据？

通过`setData` 给属性 `value` 设置为空，需要保证`setData`数值有变化。

#### input 内容跳动、延迟如何处理？

可以使用防抖函数。避免 `onInput` 的时候频繁更新。

#### iOS 在输入中文的时候出现丢焦情况，怎么办？

`iOS`的`input`在`onInput`中执行`setData`会导致在输入中文的时候丢焦。① 可对`setData`执行防抖操作 ②`onInput`的时候将数据存储在
`this`下，避免一直 触发`setData`操作。

#### input 支持自动聚焦吗？（autofocus）

- 不支持自动聚焦（autofocus），必须用户行为唤起