Livewire 中文文档

主题

#[Modelable] ​

#[Modelable] 属性指定子组件中的一个属性，可以使用 wire:model 从父组件绑定到它。

基本用法 ​

将 #[Modelable] 属性应用于子组件中的属性以使其可绑定：

php
<?php // resources/views/components/⚡todo-input.blade.php

use Livewire\Attributes\Modelable;
use Livewire\Component;

new class extends Component {
    #[Modelable] // [tl! highlight]
    public $value = '';
};
?>

<div>
    <input type="text" wire:model="value">
</div>

现在父组件可以像绑定任何其他输入元素一样绑定到这个子组件：

php
<?php // resources/views/components/⚡todos.blade.php

use Livewire\Component;

new class extends Component {
    public $todo = '';

    public function addTodo()
    {
        // Use $this->todo here...
    }
};
?>

<div>
    <livewire:todo-input wire:model="todo" /> <!-- [tl! highlight] -->

    <button wire:click="addTodo">Add Todo</button>
</div>

当用户在 todo-input 组件中输入时，父组件的 $todo 属性会自动更新。

工作原理 ​

没有 #[Modelable]，你需要手动处理父子之间的双向通信：

php
// Without #[Modelable] - manual approach
<livewire:todo-input
    :value="$todo"
    @input="todo = $event.value"
/>

#[Modelable] 属性通过允许 wire:model 直接在组件上工作来简化这一点。

构建可重用的输入组件 ​

#[Modelable] 非常适合创建感觉像原生 HTML 输入的自定义输入组件：

php
<?php // resources/views/components/⚡date-picker.blade.php

use Livewire\Attributes\Modelable;
use Livewire\Component;

new class extends Component {
    #[Modelable]
    public $date = '';
};
?>

<div>
    <input
        type="date"
        wire:model="date"
        class="border rounded px-3 py-2"
    >
</div>
blade
{{-- Usage in parent --}}
<livewire:date-picker wire:model="startDate" />
<livewire:date-picker wire:model="endDate" />

修饰符 ​

父组件可以使用 wire:model 修饰符，它们会按预期工作：

blade
{{-- Live updates on every keystroke --}}
<livewire:todo-input wire:model.live="todo" />

{{-- Update on blur --}}
<livewire:todo-input wire:model.blur="todo" />

{{-- Debounce updates --}}
<livewire:todo-input wire:model.live.debounce.500ms="todo" />

示例：自定义富文本编辑器 ​

这是一个更复杂的富文本编辑器组件示例：

php
<?php // resources/views/components/⚡rich-editor.blade.php

use Livewire\Attributes\Modelable;
use Livewire\Component;

new class extends Component {
    #[Modelable]
    public $content = '';
};
?>

<div>
    <div
        x-init="
            // Initialize your rich text editor library here
            editor.on('change', () => {
                $wire.content = editor.getContent()
            })
        "
    >
        <!-- Rich text editor UI -->
    </div>
</div>
blade
{{-- Usage --}}
<livewire:rich-editor wire:model="postContent" />

限制 ​

每个组件只能有一个可模型化属性

目前 Livewire 每个组件只支持单个 #[Modelable] 属性，所以只有第一个会被绑定。

何时使用 ​

在以下情况使用 #[Modelable]：

  • 创建可重用的输入组件（日期选择器、颜色选择器、富文本编辑器）
  • 构建需要与 wire:model 配合使用的表单组件
  • 将第三方 JavaScript 库包装为 Livewire 组件
  • 创建具有特殊验证或格式化的自定义输入

了解更多 ​

有关父子通信和数据绑定的更多信息，请参阅嵌套组件文档。