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 方法在成功时以返回值 resolve，在验证失败时 reject：

成功时：

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

验证失败时：

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

或使用 .catch()：

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

错误拒绝结构

promise 被拒绝时，错误对象具有如下结构：

{
    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 等），结构相同，但包含实际的响应数据：

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

行为

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

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

这些行为与 API 风格端点的预期一致。

何时使用

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

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

WARNING

验证错误是隔离的

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

另请参阅

Actions — 了解如何调用方法并接收返回值
Validation — Livewire 组件的服务端验证
Async Attribute — 并行运行操作而不阻塞
Renderless Attribute — 操作后跳过重新渲染

Json ​

基本用法 ​

处理响应 ​

错误拒绝结构 ​

行为 ​

何时使用 ​

另请参阅 ​