x-model

x-model 允许你将输入元素的值绑定到 Alpine 数据。

以下是一个简单的示例，演示如何使用 x-model 将文本字段的值绑定到 Alpine 中的数据。

<div x-data="{ message: '' }">
    <input type="text" x-model="message">

    <span x-text="message"></span>
</div>

现在，当用户在文本字段中键入时，message 的值将反映在 <span> 标签中。

x-model 是双向绑定的，意味着它既可以"设置"也可以"获取"。除了更改数据外，如果数据本身发生变化，元素也会反映该变化。

我们可以使用与上面相同的示例，但这次添加一个按钮来更改 message 属性的值。

<div x-data="{ message: '' }">
    <input type="text" x-model="message">

    <button x-on:click="message = 'changed'">Change Message</button>
</div>

Change Message

现在，当点击 <button> 时，输入元素的值将立即更新为 "changed"。

x-model 适用于以下输入元素：

• <input type="text">
• <textarea>
• <input type="checkbox">
• <input type="radio">
• <select>
• <input type="range">

文本输入

<input type="text" x-model="message">

<span x-text="message"></span>

尽管上述代码片段中没有包含，但如果没有父元素定义 x-data，则无法使用 x-model。→ 阅读更多关于 x-data

文本域输入

<textarea x-model="message"></textarea>

<span x-text="message"></span>

复选框输入

单个复选框（布尔值）

<input type="checkbox" id="checkbox" x-model="show">

<label for="checkbox" x-text="show"></label>

多个复选框绑定到数组

<input type="checkbox" value="red" x-model="colors">
<input type="checkbox" value="orange" x-model="colors">
<input type="checkbox" value="yellow" x-model="colors">

Colors: <span x-text="colors"></span>

Colors:

单选输入

<input type="radio" value="yes" x-model="answer">
<input type="radio" value="no" x-model="answer">

Answer: <span x-text="answer"></span>

Answer:

选择输入

单选

<select x-model="color">
    <option>Red</option>
    <option>Orange</option>
    <option>Yellow</option>
</select>

Color: <span x-text="color"></span>

Red Orange Yellow

Color:

带占位符的单选

<select x-model="color">
    <option value="" disabled>Select A Color</option>
    <option>Red</option>
    <option>Orange</option>
    <option>Yellow</option>
</select>

Color: <span x-text="color"></span>

Select A Color Red Orange Yellow

Color:

多选

<select x-model="color" multiple>
    <option>Red</option>
    <option>Orange</option>
    <option>Yellow</option>
</select>

Colors: <span x-text="color"></span>

Red Orange Yellow

Color:

动态填充的选择选项

<select x-model="color">
    <template x-for="color in ['Red', 'Orange', 'Yellow']">
        <option x-text="color"></option>
    </template>
</select>

Color: <span x-text="color"></span>

Color:

范围输入

<input type="range" x-model="range" min="0" max="1" step="0.1">

<span x-text="range"></span>

修饰符

.lazy

在文本输入中，默认情况下，x-model 会在每次按键时更新属性。通过添加 .lazy 修饰符，可以强制 x-model 输入仅在用户焦点离开输入元素时才更新属性。

这对于实时表单验证等场景非常有用，你可能希望在用户"跳出"字段后才显示输入验证错误。

<input type="text" x-model.lazy="username">
<span x-show="username.length > 20">The username is too long.</span>

.change

.change 仅在输入失去焦点且其值已更改（原生 change 事件）时同步数据。这在功能上等同于 .lazy。

<input type="text" x-model.change="username">

.blur

.blur 在输入失去焦点时同步数据，无论值是否已更改。

<input type="text" x-model.blur="email">

.enter

.enter 在用户按下 Enter 键时同步数据。这对于搜索字段非常有用，你希望仅在用户明确提交时才触发操作。

<input type="text" x-model.enter="search">

注意：.enter 不会阻止默认行为。如果输入位于表单内，表单仍会提交。

组合事件修饰符

.change、.blur 和 .enter 修饰符可以组合使用，以在多个事件上同步。当你想为用户提供提交数据的灵活性时，这非常有用。

<!-- 在 blur 或 enter 时同步 -->
<input type="text" x-model.blur.enter="search" placeholder="Press Enter or click away">

<!-- 在 change、blur 或 enter 时同步 -->
<input type="text" x-model.change.blur.enter="message">

Search:

.number

默认情况下，通过 x-model 存储在属性中的任何数据都以字符串形式存储。若要强制 Alpine 将值存储为 JavaScript 数字，请添加 .number 修饰符。

<input type="text" x-model.number="age">
<span x-text="typeof age"></span>

.boolean

默认情况下，通过 x-model 存储在属性中的任何数据都以字符串形式存储。若要强制 Alpine 将值存储为 JavaScript 布尔值，请添加 .boolean 修饰符。整数（1/0）和字符串（true/false）都是有效的布尔值。

<select x-model.boolean="isActive">
    <option value="true">Yes</option>
    <option value="false">No</option>
</select>
<span x-text="typeof isActive"></span>

.debounce

通过向 x-model 添加 .debounce，你可以轻松地对绑定输入的更新进行防抖处理。

这对于实时搜索输入等场景非常有用，这些场景在搜索属性每次更改时都会从服务器获取新数据。

<input type="text" x-model.debounce="search">

默认的防抖时间为 250 毫秒，你可以通过添加时间修饰符轻松自定义此时间：

<input type="text" x-model.debounce.500ms="search">

.throttle

与 .debounce 类似，你可以限制由 x-model 触发的属性更新，使其仅在指定的时间间隔内更新。

<input type="text" x-model.throttle="search">

默认的节流间隔为 250 毫秒，你可以通过添加时间修饰符轻松自定义此间隔：

<input type="text" x-model.throttle.500ms="search">

.fill

默认情况下，如果输入具有 value 属性，Alpine 会忽略它，并将输入的值设置为通过 x-model 绑定的属性的值。

但如果绑定的属性为空，则可以通过添加 .fill 修饰符来使用输入的 value 属性填充该属性。

<div x-data="{ message: null }">
  <input type="text" x-model.fill="message" value="This is the default message.">
</div>

程序化访问

Alpine 公开了底层工具，用于获取和设置通过 x-model 绑定的属性。这对于复杂的 Alpine 工具非常有用，这些工具可能希望覆盖默认的 x-model 行为，或者当你希望在非输入元素上允许 x-model 时。

你可以通过 x-model 绑定元素上的 _x_model 属性来访问这些工具。_x_model 有两个方法来获取和设置绑定的属性：

• el._x_model.get()（返回绑定属性的值）
• el._x_model.set()（设置绑定属性的值）

<div x-data="{ username: 'calebporzio' }">
    <div x-ref="div" x-model="username"></div>

    <button @click="$refs.div._x_model.set('phantomatrix')">
        Change username to: 'phantomatrix'
    </button>

    <span x-text="$refs.div._x_model.get()"></span>
</div>

Change username to: 'phantomatrix'