Livewire 中文文档

主题

#[Json] ​

#[Json] 属性将操作标记为 JSON 端点，直接将数据返回给 JavaScript。验证错误会触发带有结构化错误数据的 Promise 拒绝。这非常适合被 JavaScript 消费而不是在 Blade 中渲染的操作。

基本用法 ​

将 #[Json] 属性应用于任何返回数据供 JavaScript 消费的操作方法：

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

use Livewire\Attributes\Json;
use Livewire\Component;
use App\Models\Post;

new class extends Component {
    #[Json] // [tl! highlight]
    public function search($query)
    {
        return Post::where('title', 'like', "%{$query}%")
            ->limit(10)
            ->get();
    }
};
blade
<div x-data="{ query: '', posts: [] }">
    <input
        type="text"
        x-model="query"
        x-on:input.debounce="$wire.search(query).then(data => posts = data)"
    >

    <ul>
        <template x-for="post in posts">
            <li x-text="post.title"></li>
        </template>
    </ul>
</div>

search() 方法直接将文章返回给 Alpine，在那里它们被存储在 posts 数组中并在客户端渲染。

处理响应 ​

JSON 方法在成功时解析返回值，在验证失败时拒绝：

成功时：

js
let data = await $wire.search('query')
// data = [ { id: 1, title: '...' }, ...]

验证失败时：

js
try {
    let data = await $wire.save()
} catch (e) {
    // e.status = 422
    // e.errors = { name: ['The name field is required.'] }
}

或使用 .catch()：

js
$wire.save()
    .then(data => {
        // Handle success
        console.log(data)
    })
    .catch(e => {
        if (e.status === 422) {
            // Handle validation errors
            console.log(e.errors)
        }
    })

错误拒绝结构 ​

当 Promise 被拒绝时，错误对象有以下结构：

js
{
    status: 422,    // HTTP status code (422 for validation errors)
    body: null,     // Raw response body (null for validation errors)
    json: null,     // Parsed JSON (null for validation errors)
    errors: {...}   // Validation errors object
}

对于 HTTP 错误（500 等），结构相同但有实际的响应数据：

js
{
    status: 500,
    body: '<html>...</html>',
    json: null,
    errors: null
}

行为 ​

#[Json] 属性自动应用两种行为：

  1. 跳过渲染 - 组件在操作完成后不重新渲染，因为响应被 JavaScript 消费
  2. 异步运行 - 操作并行执行而不阻塞其他请求

这些行为符合你对 API 风格端点的期望。

何时使用 ​

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

  • 构建动态搜索/自动完成 - 为下拉列表或建议列表获取结果
  • 将数据加载到 JavaScript - 填充图表、地图或其他 JS 驱动的 UI
  • 使用 JS 处理提交表单 - 当你想在 JavaScript 中处理成功/错误状态时
  • 与第三方库集成 - 为管理自己渲染的库提供数据

验证错误是隔离的

JSON 方法的验证错误只通过 Promise 拒绝返回。它们不会出现在 $wire.$errors 或组件的错误包中。这是有意的——JSON 方法是自包含的，不影响组件的渲染状态。

另请参阅 ​