Statamic Antlers中Livewire组件更新URL参数后停止渲染问题

问题场景 #

我开发了PracticeLocatorRegions Livewire组件，想要实现：点击区域按钮动态筛选下方诊所列表，同时将选中区域作为URL参数支持分享。但点击按钮后组件完全停止渲染，必须刷新整页才能恢复，试过wire:click="selectRegion('{{ value }}')"和wire:click="$set('selectedRegion', '{{ value }}')"两种方式都无效。

组件代码（PHP） #

class PracticeLocatorRegions extends Component
{
    public string $selectedRegion = '';

    protected $queryString = ['selectedRegion' => ['except' => '']];

    public function mount()
    {
        $this->selectedRegion = request('selectedRegion') ?? '';
    }

    public function render(): View
    {
        $practices = Entry::whereCollection('practices');

        return view('livewire.practice-locator-regions', [
            'regions'   => $this->getRegions(),
            'practices' => $this->selectedRegion ? $practices->where('region', $this->selectedRegion) : $practices,
        ]);
    }

    public function getRegions(): array
    {
        $practices = Entry::whereCollection('practices');

        $practicesByRegion = array();

        foreach ($practices as $key => $practice) {
           $practicesByRegion[$practice['region']][$key] = $practice;
        }

        ksort($practicesByRegion);
        return array_keys($practicesByRegion);
    }

    public function selectRegion(string $region): void
    {
        $this->selectedRegion = $region;
    }
}

模板代码（Antlers） #

<!-- Begin pratice-locator-regions.antlers.html -->
<div class="container">
    <div class="flex flex-wrap justify-center">
        {{ regions }}
            <div class="p-4">
                <button wire:click="selectRegion('{{ value }}')" class="button m-4">{{ value }}</button></div>
        {{ /regions }}
    </div>
    <div>
        <ul>
        {{ practices }}
            <li>{{ title }}</li>
        {{/practices}}
        <ul>
    </div>
</div>
<!-- end pratice-locator-regions.antlers.html -->

问题根源 #

核心问题是Antlers的变量插值和Livewire的指令语法冲突：Antlers会先解析{{ value }}并替换成区域字符串，但生成的wire:click指令会因为字符串转义问题（比如区域名称包含空格或特殊字符）导致参数格式错误，触发Livewire的JS异常，最终让组件停止响应渲染。

解决方案 #

1. 修正模板的wire:click参数传递 #

改用Antlers的无转义插值语法{value}，或者用json_encode确保参数格式正确：

方式一：无转义插值

{{ regions }}
    <div class="p-4">
        <button wire:click="selectRegion('{value}')" class="button m-4">{{ value }}</button>
    </div>
{{ /regions }}

方式二：JSON编码参数

{{ regions }}
    <div class="p-4">
        <button wire:click="selectRegion({{ json_encode(value) }})" class="button m-4">{{ value }}</button>
    </div>
{{ /regions }}

2. 修复组件查询逻辑 #

当前render方法中$practices如果是查询构建器，需要调用->get()才能获取实际数据集合，否则筛选逻辑不会生效：

public function render(): View
{
    $practicesQuery = Entry::whereCollection('practices');

    // 应用区域筛选
    if ($this->selectedRegion) {
        $practicesQuery->where('region', $this->selectedRegion);
    }

    return view('livewire.practice-locator-regions', [
        'regions'   => $this->getRegions(),
        'practices' => $practicesQuery->get(), // 必须调用get()获取结果集
    ]);
}

3. 验证Livewire基础配置 #

• 确保组件在父模板中正确引入：<livewire:practice-locator-regions />
• 检查页面是否加载了Livewire的JS和CSS资源（查看页面源码确认）

4. 调试排查 #

打开浏览器开发者工具的Network标签，点击按钮后查看Livewire的XHR请求：

• 查看请求参数是否正确传递
• 查看响应是否包含错误信息，根据提示进一步修复

内容的提问来源于stack exchange，提问作者Nicholas Norton