输入框（Input）

Element-UI 的输入框组件允许用户通过鼠标或键盘输入字符。输入框为受控组件，总是显示与 Vue 绑定值同步的内容。通过简单的属性配置，可以实现多种功能和样式。

提示

输入框（Input）组件官方文档：https://element.eleme.cn/#/zh-CN/component/input (opens new window)

输入框是受控组件

• 受控组件：Element-UI 的输入框组件是受控组件，这意味着它总是显示绑定到 Vue 的 v-model 的值。
• 值同步机制：在 Element-UI 中，如果没有使用 v-model 绑定输入框的变量，就必须手动处理 input 事件来更新输入框的值。否则，输入框的显示内容不会自动改变。
• 不支持 v-model 修饰符：输入框组件不支持 v-model 修饰符，如 .lazy、.number、.trim 等。因此，开发者需要手动处理输入事件来确保值的同步。

1. 输入框基本用法

基本语法：在 Vue 组件中使用 <el-input> 标签即可创建一个输入框。

<template>
  <el-input v-model="inputValue" placeholder="请输入内容"></el-input>
</template>

<script>
export default {
  data() {
    return {
      inputValue: '' // 输入框的初始值
    };
  }
};
</script>

• 同步机制：通过 v-model 绑定的变量 inputValue 控制输入框的内容。用户输入时，inputValue 的值会自动更新。

Input 属性

参数	说明	类型	可选值	默认值
type	类型	string	text，textarea 和其他原生 input 的 type 值	text
value / v-model	绑定值	string / number	—	—
maxlength	原生属性，最大输入长度	number	—	—
minlength	原生属性，最小输入长度	number	—	—
show-word-limit	是否显示输入字数统计，只在 type = "text" 或 type = "textarea" 时有效	boolean	—	false
placeholder	输入框占位文本	string	—	—
clearable	是否可清空	boolean	—	false
show-password	是否显示切换密码图标	boolean	—	false
disabled	禁用	boolean	—	false
size	输入框尺寸，只在 type!="textarea" 时有效	string	medium / small / mini	—
prefix-icon	输入框头部图标	string	—	—
suffix-icon	输入框尾部图标	string	—	—
rows	输入框行数，只对 type="textarea" 有效	number	—	2
autosize	自适应内容高度，只对 type="textarea" 有效	boolean / object	{ minRows: 2, maxRows: 6 }	false
autocomplete	原生属性，自动补全	string	on, off	off
name	原生属性	string	—	—
readonly	原生属性，是否只读	boolean	—	false
max	原生属性，设置最大值	—	—	—
min	原生属性，设置最小值	—	—	—
step	原生属性，设置输入字段的合法数字间隔	—	—	—
resize	控制是否能被用户缩放	string	none, both, horizontal, vertical	—
autofocus	原生属性，自动获取焦点	boolean	true, false	false
form	原生属性	string	—	—
label	输入框关联的 label 文本	string	—	—
tabindex	输入框的 tabindex	string	—	—
validate-event	输入时是否触发表单的校验	boolean	—	true

Input 插槽

名称	说明
prefix	输入框头部内容，只对 type="text" 有效
suffix	输入框尾部内容，只对 type="text" 有效
prepend	输入框前置内容，只对 type="text" 有效
append	输入框后置内容，只对 type="text" 有效

Input 事件

事件名称	说明	回调参数
blur	在 Input 失去焦点时触发	(event: Event)
focus	在 Input 获得焦点时触发	(event: Event)
change	仅在输入框失去焦点或用户按下回车时触发	(value: string / number)
input	在 Input 值改变时触发	(value: string / number)
clear	在点击由 clearable 属性生成的清空按钮时触发	—

Input 方法

方法名	说明	参数
focus	使 input 获取焦点	—
blur	使 input 失去焦点	—
select	选中 input 中的文字	—

2. 输入框示例

基础输入框

通过 v-model 绑定值来实时更新输入框内容。

<template>
  <el-input v-model="inputValue" placeholder="请输入内容"></el-input>
</template>

<script>
export default {
  data() {
    return {
      inputValue: '' // 输入框的初始值
    };
  }
};
</script>

带清除按钮的输入框

使用 clearable 属性为输入框添加清除按钮。

<template>
  <el-input v-model="inputValue" clearable placeholder="可清空的输入框"></el-input>
</template>

带图标的输入框

使用 prefix-icon 和 suffix-icon 属性为输入框添加图标。

<template>
  <el-input
    v-model="inputValue"
    prefix-icon="el-icon-search"
    suffix-icon="el-icon-edit"
    placeholder="带图标的输入框"
  ></el-input>
</template>

密码框

使用 show-password 属性为输入框添加密码切换功能。

<template>
  <el-input
    type="password"
    v-model="password"
    show-password
    placeholder="请输入密码"
  ></el-input>
</template>

<script>
export default {
  data() {
    return {
      password: '' // 初始密码
    };
  }
};
</script>

可自适应文本高度的文本域

使用 type="textarea" 创建一个多行文本输入框，并设置行数和自适应内容高度。

<template>
  <el-input
    type="textarea"
    v-model="textareaValue"
    :rows="4"
    placeholder="请输入多行内容"
    autosize
  ></el-input>
</template>

<script>
export default {
  data() {
    return {
      textareaValue: '' // 文本域的初始值
    };
  }
};
</script>

显示字数限制

使用 show-word-limit 属性显示输入字数统计。

<template>
  <el-input
    type="text"
    v-model="inputValue"
    maxlength="10"
    show-word-limit
    placeholder="最多输入 10 个字符"
  ></el-input>
</template>

使用插槽指定前置或后置内容

通过 prepend 和 append 插槽可以在输入框中增加前置或后置内容。

<template>
  <el-input v-model="inputValue" placeholder="请输入内容">
    <template #prepend>http://</template>
    <template #append>.com</template>
  </el-input>
</template>

<script>
export default {
  data() {
    return {
      inputValue: '' // 输入框的初始值
    };
  }
};
</script>

不使用 v-model 的情况

• 如果没有使用 v-model，则需要手动处理 input 事件来更新输入框的值。否则，输入框中的内容不会变化。

<template>
  <el-input
    :value="inputValue"
    @input="handleInput"
    placeholder="请输入内容"
  ></el-input>
</template>

<script>
export default {
  data() {
    return {
      inputValue: '' // 手动更新的变量
    };
  },
  methods: {
    handleInput(value) {
      this.inputValue = value; // 手动更新变量
      console.log('当前输入值:', value);
    }
  }
};
</script>

• 自动同步：使用 v-model 会自动处理 input 事件，使输入框内容和绑定变量始终保持同步。
• 手动处理：不使用 v-model 时，必须通过 input 事件手动更新绑定变量，以实现输入框内容的更新。

3. 可带输入建议的输入框（Autocomplete）

Autocomplete 是一个带有输入建议功能的输入框组件，允许用户在输入时获取建议列表。该组件通常用于搜索框、地址输入等需要快速输入的场景。

Autocomplete 属性

参数	说明	类型	可选值	默认值
placeholder	输入框占位文本	string	—	—
disabled	禁用	boolean	—	false
value-key	输入建议对象中用于显示的键名	string	—	value
value	必填值，输入绑定值	string	—	—
debounce	获取输入建议的去抖延时	number	—	300
placement	菜单弹出位置	string	top / top-start / top-end / bottom / bottom-start / bottom-end	bottom-start
fetch-suggestions	返回输入建议的方法，仅当你的输入建议数据 resolve 时，通过调用 callback(data:[]) 来返回它	Function(queryString, callback)	—	—
popper-class	Autocomplete 下拉列表的类名	string	—	—
trigger-on-focus	是否在输入框 focus 时显示建议列表	boolean	—	true
select-when-unmatched	在输入没有任何匹配建议的情况下，按下回车是否触发 select 事件	boolean	—	false
label	输入框关联的 label 文本	string	—	—
prefix-icon	输入框头部图标	string	—	—
suffix-icon	输入框尾部图标	string	—	—
hide-loading	是否隐藏远程加载时的加载图标	boolean	—	false
popper-append-to-body	是否将下拉列表插入至 body 元素。在下拉列表的定位出现问题时，可将该属性设置为 false	boolean	—	true
highlight-first-item	是否默认突出显示远程搜索建议中的第一项	boolean	—	false

Autocomplete 插槽

名称	说明
prefix	输入框头部内容
suffix	输入框尾部内容
prepend	输入框前置内容
append	输入框后置内容

Autocomplete 限定范围的插槽

名称	说明
—	自定义输入建议，参数为 { item }

Autocomplete 事件

事件名称	说明	回调参数
select	点击选中建议项时触发	选中建议项
change	在 Input 值改变时触发	(value: string / number)

Autocomplete 方法

方法名	说明	参数
focus	使 input 获取焦点	—

4. 可带输入建议的输入框示例

Autocomplete 是一个带有输入建议功能的输入框组件。可以通过绑定数据源和配置方法，实现多种形式的输入建议交互。

• 激活即列出输入建议：在输入框获得焦点时，立即显示所有可用的输入建议。
• 输入后匹配输入建议：用户输入内容后，根据输入内容动态匹配和显示建议列表。

数据绑定

• 绑定值 (v-model)：用于绑定输入框的当前值。通过 v-model，输入框的内容会实时同步到绑定的数据变量中。
• 输入建议数据源：在组件的 data 中定义数据源，如 restaurants 数组，存储所有可供选择的建议项。

事件触发

• fetch-suggestions 方法：每当用户输入内容时，该方法被调用，用于根据输入内容动态筛选建议项。方法通过回调函数 cb 将匹配的结果传递给组件进行显示。
• 选择建议项的事件 (@select)：当用户从建议列表中选择某项时，触发 select 事件，并返回所选项的详细信息。

激活即列出输入建议

当用户点击或聚焦输入框时，自动显示所有可用的输入建议。

<template>
  <el-row class="demo-autocomplete">
    <el-col :span="12">
      <div class="sub-title">激活即列出输入建议</div>
      <el-autocomplete
        class="inline-input"
        v-model="state1"
        :fetch-suggestions="querySearch"
        placeholder="请输入内容"
        @select="handleSelect"
      ></el-autocomplete>
    </el-col>
  </el-row>
</template>

<script>
export default {
  data() {
    return {
      restaurants: [], // 存储餐馆信息
      state1: ''       // 输入框的绑定值
    };
  },
  methods: {
    querySearch(queryString, cb) {
      // 如果没有输入内容，显示所有餐馆；否则，进行过滤
      const results = queryString ? this.restaurants.filter(this.createFilter(queryString)) : this.restaurants;
      cb(results); // 通过回调返回结果
    },
    createFilter(queryString) {
      // 创建一个过滤函数，根据输入的字符串进行过滤
      return (restaurant) => {
        return restaurant.value.toLowerCase().includes(queryString.toLowerCase());
      };
    },
    loadAll() {
      // 返回所有餐馆数据
      return [
        { "value": "三全鲜食（北新泾店）", "address": "长宁区新渔路144号" },
        { "value": "Hot honey 首尔炸鸡（仙霞路）", "address": "上海市长宁区淞虹路661号" },
        { "value": "新旺角茶餐厅", "address": "上海市普陀区真北路988号创邑金沙谷6号楼113" },
        // 省略其他数据...
      ];
    },
    handleSelect(item) {
      console.log('选中项:', item); // 打印选中的餐馆信息
    }
  },
  mounted() {
    this.restaurants = this.loadAll(); // 加载餐馆数据
  }
};
</script>

• 数据初始化：在 mounted 生命周期钩子中，调用 loadAll 方法初始化 restaurants 数据。
• fetch-suggestions 方法：每次输入或激活输入框时被调用，根据输入内容过滤数据并通过回调 cb 返回结果。
• @select 事件：用户选择建议项时触发，参数 item 包含选中项的详细信息。

输入后匹配输入建议

仅在用户输入内容时，根据输入内容显示匹配的建议列表。

<template>
  <el-row class="demo-autocomplete">
    <el-col :span="12">
      <div class="sub-title">输入后匹配输入建议</div>
      <el-autocomplete
        class="inline-input"
        v-model="state2"
        :fetch-suggestions="querySearch"
        placeholder="请输入内容"
        :trigger-on-focus="false"
        @select="handleSelect"
      ></el-autocomplete>
    </el-col>
  </el-row>
</template>

<script>
export default {
  data() {
    return {
      restaurants: [], // 存储餐馆信息
      state2: ''       // 输入框的绑定值
    };
  },
  methods: {
    querySearch(queryString, cb) {
      // 根据输入内容进行过滤
      const results = queryString ? this.restaurants.filter(this.createFilter(queryString)) : this.restaurants;
      cb(results); // 通过回调返回结果
    },
    createFilter(queryString) {
      // 创建一个过滤函数，根据输入的字符串进行过滤
      return (restaurant) => {
        return restaurant.value.toLowerCase().includes(queryString.toLowerCase());
      };
    },
    loadAll() {
      // 返回所有餐馆数据
      return [
        { "value": "三全鲜食（北新泾店）", "address": "长宁区新渔路144号" },
        { "value": "Hot honey 首尔炸鸡（仙霞路）", "address": "上海市长宁区淞虹路661号" },
        { "value": "新旺角茶餐厅", "address": "上海市普陀区真北路988号创邑金沙谷6号楼113" },
        // 省略其他数据...
      ];
    },
    handleSelect(item) {
      console.log('选中项:', item); // 打印选中的餐馆信息
    }
  },
  mounted() {
    this.restaurants = this.loadAll(); // 加载餐馆数据
  }
};
</script>

• 数据初始化：在 mounted 生命周期钩子中，调用 loadAll 方法初始化 restaurants 数据。
• fetch-suggestions 方法：每次输入或激活输入框时被调用，根据输入内容过滤数据并通过回调 cb 返回结果。
• @select 事件：用户选择建议项时触发，参数 item 包含选中项的详细信息。

总结

• 多样化的输入框类型：Element-UI 提供了普通文本框、密码框、文本域等多种输入框类型。
• 灵活的属性和事件：通过 v-model 绑定值，支持输入框的实时更新，同时提供丰富的属性来定制输入框的行为和样式。
• 输入建议功能：通过 Autocomplete 组件，可以实现输入建议功能，提升用户体验。
• 自定义内容：通过插槽可以在输入框中添加自定义的前置、后置内容以及图标。