Url

#[Url] 属性将属性值存储在 URL 的查询字符串中，允许用户分享和收藏页面的特定状态。

基本用法

将 #[Url] 属性应用到任何应在 URL 中持久化的属性上：

php

<?php // resources/views/components/user/⚡index.blade.php

use Livewire\Attributes\Computed;
use Livewire\Attributes\Url;
use Livewire\Component;
use App\Models\User;

new class extends Component {
    #[Url] // [tl! highlight]
    public $search = '';

    #[Computed]
    public function users()
    {
        return User::search($this->search)->get();
    }
};
?>

<div>
    <input type="text" wire:model.live="search" placeholder="Search users...">

    <ul>
        @foreach ($this->users as $user)
            <li wire:key="{{ $user->id }}">{{ $user->name }}</li>
        @endforeach
    </ul>
</div>

当用户在搜索框中输入「bob」时，URL 会更新为 https://example.com/users?search=bob。若他们分享该 URL 或刷新页面，搜索值会保持。

工作原理

#[Url] 属性做两件事：

写入 URL - 属性变化时，更新查询字符串
从 URL 读取 - 页面加载时，从查询字符串初始化属性

这为你的组件创建了可分享、可收藏的状态。

URL 与 Session

#[Url] 和 #[Session] 都会持久化属性值，但各有取舍：

特性	`#[Url]`	`#[Session]`
刷新后保持	✅	✅
分享 URL 时保持	✅	❌
保持 URL 整洁	❌	✅
对用户可见	✅	❌
可分享的状态	✅	❌

当你希望用户能够分享或收藏当前状态时，使用 #[Url]。当状态应为私有时，使用 #[Session]。

使用别名

使用 as 参数缩短或混淆 URL 中的属性名：

php

<?php // resources/views/components/user/⚡index.blade.php

use Livewire\Attributes\Url;
use Livewire\Component;

new class extends Component {
    #[Url(as: 'q')] // [tl! highlight]
    public $search = '';
};

URL 将显示 ?q=bob 而不是 ?search=bob。

排除值

默认情况下，Livewire 仅在值与初始值不同时添加查询参数。使用 except 可自定义此行为：

php

<?php // resources/views/components/user/⚡index.blade.php

use Livewire\Attributes\Url;
use Livewire\Component;

new class extends Component {
    #[Url(except: '')] // [tl! highlight]
    public $search = '';

    public function mount()
    {
        $this->search = auth()->user()->username;
    }
};

现在 Livewire 仅在 search 为空字符串时才将其从 URL 中排除，而不是在它等于初始用户名值时排除。

始终显示在 URL 中

要始终在 URL 中包含该参数（即使为空），请使用 keep：

php

#[Url(keep: true)] // [tl! highlight]
public $search = '';

即使值为空，URL 也始终会显示 ?search=。

可空属性

使用可空类型提示，将空查询参数视为 null 而非空字符串：

php

<?php // resources/views/components/user/⚡index.blade.php

use Livewire\Attributes\Url;
use Livewire\Component;

new class extends Component {
    #[Url]
    public ?string $search; // [tl! highlight]
};

现在 ?search= 会将 $search 设为 null 而不是 ''。

浏览器历史

默认情况下，Livewire 使用 history.replaceState() 修改 URL 而不添加浏览器历史记录。若要添加历史记录（使返回按钮恢复先前的查询值），请使用 history：

php

#[Url(history: true)] // [tl! highlight]
public $search = '';

现在点击浏览器的返回按钮会恢复先前的搜索值，而不是导航到上一页。

何时使用

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

构建搜索或筛选界面
实现分页
创建可分享的视图（地图位置、已选筛选器等）
允许用户收藏特定状态
支持通过浏览器前进/后退在状态间导航

示例：产品筛选

下面是一个使用多个 URL 参数筛选产品的实用示例：

php

<?php // resources/views/pages/⚡products.blade.php

use Livewire\Attributes\Computed;
use Livewire\Attributes\Url;
use Livewire\Component;
use App\Models\Product;

new class extends Component {
    #[Url(as: 'q')]
    public $search = '';

    #[Url]
    public $category = 'all';

    #[Url]
    public $minPrice = 0;

    #[Url]
    public $maxPrice = 1000;

    #[Url]
    public $sort = 'name';

    #[Computed]
    public function products()
    {
        return Product::query()
            ->when($this->search, fn($q) => $q->search($this->search))
            ->when($this->category !== 'all', fn($q) => $q->where('category', $this->category))
            ->whereBetween('price', [$this->minPrice, $this->maxPrice])
            ->orderBy($this->sort)
            ->paginate(20);
    }
};
?>

<div>
    <input type="text" wire:model.live="search" placeholder="Search products...">

    <select wire:model.live="category">
        <option value="all">All Categories</option>
        <option value="electronics">Electronics</option>
        <option value="clothing">Clothing</option>
    </select>

    <input type="range" wire:model.live="minPrice" min="0" max="1000">
    <input type="range" wire:model.live="maxPrice" min="0" max="1000">

    <select wire:model.live="sort">
        <option value="name">Name</option>
        <option value="price">Price</option>
        <option value="created_at">Newest</option>
    </select>

    @foreach($this->products as $product)
        <div wire:key="{{ $product->id }}">{{ $product->name }} - ${{ $product->price }}</div>
    @endforeach
</div>

用户可以分享如下 URL：

```text https://example.com/products?q=laptop&category=electronics&minPrice=500&maxPrice=1500&sort=price ```

SEO 考量

查询参数会被搜索引擎索引并包含在分析中：

利于 SEO - 每个唯一的查询组合都会创建一个可被索引的唯一 URL
分析追踪 - 追踪用户使用的筛选和搜索
可在社交媒体分享 - 分享链接时会保留查询参数

了解更多

有关 URL 查询参数的更多信息，包括 queryString() 方法和 trait 钩子，请参阅 URL 查询参数文档。

参考

php

#[Url(
    ?string $as = null,
    bool $history = false,
    bool $keep = false,
    mixed $except = null,
    mixed $nullable = null,
)]

参数	类型	默认值	说明
`$as`	`?string`	`null`	URL 中查询参数的自定义名称
`$history`	`bool`	`false`	将 URL 变更推入浏览器历史（启用返回按钮）
`$keep`	`bool`	`false`	导航离开时保留查询参数
`$except`	`mixed`	`null`	要从 URL 中排除的值
`$nullable`	`mixed`	`null`	查询参数在 URL 中缺失时使用的值

Url ​

基本用法 ​

工作原理 ​

URL 与 Session ​

使用别名 ​

排除值 ​

始终显示在 URL 中 ​

可空属性 ​

浏览器历史 ​

何时使用 ​

示例：产品筛选 ​

SEO 考量 ​

了解更多 ​

参考 ​

Url