Звіт про баг завжди однаковий: «Я видалив рядок, і після цього виділеним виявився не той». На свіжому завантаженні сторінки це не відтворюється, винятків немає, у логи нічого не потрапляє, тож тікет закривають як «не вдалося відтворити» - аж поки за тиждень він не повернеться. Причина - один відсутній атрибут, і більшість із нас прочитали про wire:key в документації як про підказку для продуктивності та пішли далі.
Навмисно відтворюємо застарілий рядок
Зберемо найменший список, який може зламатися: рядки з рахунками, у кожному - меню дій під керуванням Alpine і некероване текстове поле, плюс дія видалення на сервері. Жодного wire:key. Цей компонент зламаний так, що пройде будь-який тест, який ви, найімовірніше, для нього напишете.
<?php // resources/views/components/⚡invoice-list.blade.php
use App\Models\Invoice;
use Livewire\Attributes\Computed;
use Livewire\Component;
new class extends Component {
#[Computed]
public function invoices()
{
return Invoice::orderBy('due_at')->get();
}
public function delete(int $invoiceId): void
{
Invoice::whereKey($invoiceId)->delete();
unset($this->invoices); // Скидаємо кеш обчислюваної властивості
}
};
<div>
@foreach ($this->invoices as $invoice)
<div class="flex items-center gap-4" x-data="{ open: false }">
<span>{{ $invoice->reference }}</span>
{{-- Некероване: значення живе лише у вузлі DOM --}}
<input type="text" placeholder="Add a note">
<button x-on:click="open = ! open">Actions</button>
<div x-show="open">
<button wire:click="delete({{ $invoice->id }})">Delete</button>
</div>
</div>
@endforeach
</div>
Тепер покеруйте ним вручну. Введіть check with finance у поле нотатки третього рядка, відкрийте меню дій третього рядка, а потім видаліть другий рядок. Список перемальовується з двома рядками - і текст нотатки та відкрите меню тепер стоять на рядку, який був третім, а став другим. Дані правильні. Усе, що прив'язане до вузла DOM, - ні.
Розбираємо морфінг, який це спричинив
Livewire не замінює HTML компонента під час кожного оновлення. Він виконує морфінг (morph): обходить старе й нове дерево одночасно, порівнює кожен елемент, який трапляється, і точково змінює лише те, що відрізняється. Саме це зберігає фокус, обробники подій і значення полів між запитами - і саме це шкодить вам тут.
З трьома рядками і без ключів порівняння суто позиційне:
Старий DOM Новий HTML Що робить Livewire
───────────────────────────────────────────────────────────────────────────
row 1 (INV-1) → row 1 (INV-1) те саме, не чіпає
row 2 (INV-2, empty) → row 2 (INV-3, empty) змінює текст на місці
row 3 (INV-3, note) → - видаляє останній елемент
Livewire так і не перемістив третій рядок. Він переписав текстовий вміст другого рядка на INV-3, а потім видалив останній елемент - який якраз і був вузлом із вашою нотаткою та відкритим меню. У Livewire є крок попереднього перегляду (look-ahead), що ловить багато таких випадків, і він вставляє маркери <!--[if BLOCK]><![endif]--> навколо умов Blade, щоб відрізнити вставку від зміни, але жодне з цього не допомагає, коли список змінив порядок чи скоротився, а рядки нічим не ідентифіковано.
Від вузла DOM залежать чотири речі, тож саме вони й ламаються, кожна зі своїм баг-репортом:
- Стан компонента Alpine -
x-data ініціалізується для кожного елемента окремо, тому відкритий випадний список чи розгорнута панель переїжджає на той запис, що успадкував вузол. Це той самий життєвий цикл, через який стан модальних вікон на Alpine і wire:entangle чутливий до повторних рендерів.
- Фокус - курсор посеред набору тексту стрибає на сусідній рядок.
- Позиція прокрутки всередині комірки з прокруткою скидається або опиняється на чужому записі.
- Значення некерованих полів - усе, що не має
wire:model, є станом лише в DOM, тож воно лишається на вузлі й отримує нового власника.
Якщо ваш баг-репорт збігається з одним із цих чотирьох пунктів, перестаньте читати серверний код. Це проблема ключів.
Ключ циклу - первинний ключ моделі
Дайте кожному рядку стабільну ідентичність, і позиційний обхід перестане бути вгадуванням. Додайте wire:key у відкривальний тег першого елемента всередині циклу і збудуйте його з первинного ключа моделі.
@foreach ($this->invoices as $invoice)
<div wire:key="invoice-row-{{ $invoice->id }}" class="flex items-center gap-4" x-data="{ open: false }">
{{-- ... --}}
</div>
@endforeach
Тепер видаліть другий рядок, і Livewire зіставить invoice-row-3 з invoice-row-3, перемістить вузол, а нотатка й відкрите меню поїдуть разом із записом, якому належать.
Дві речі треба зробити правильно. Ніколи не будуйте ключ на $loop->index - це та сама позиція, на яку ви намагаєтеся відучити Livewire спиратися: вона змінюється, щойно список скорочується чи змінює порядок, тож нічого не дає. У документації про морфінг $loop->index використано в іграшковому прикладі, і цю звичку не варто переймати. І ніколи не будуйте ключ на значенні, яке користувач може редагувати: ключ з імені чи email змінюється під час збереження, тож Livewire руйнує рядок і будує його заново - це виглядає як блимання і мовчки знищує клієнтський стан цього рядка.
Префікс у кожному ключі, щоб він був унікальним на всій сторінці
Ключі порівнюються в усьому відрендереному дереві компонентів, а не в межах циклу, який їх створив. Виведіть на одній сторінці рахунки і клієнтів, дайте обом голий {{ $model->id }} як ключ - і щойно рахунок і клієнт матимуть однаковий id, у вас з'явиться дубльований ключ. А це гірше, ніж відсутність ключа, бо тепер Livewire активно зіставляє два не пов'язані між собою елементи.
<div>
@foreach ($this->invoices as $invoice)
<div wire:key="invoice-row-{{ $invoice->id }}">...</div>
@endforeach
@foreach ($this->customers as $customer)
<div wire:key="customer-row-{{ $customer->id }}">...</div>
@endforeach
</div>
Оберіть одну угоду й застосовуйте її всюди: {noun}-{context}-{id}. Це нічого не коштує, робить дублікати помітними на рев'ю і дає змогу знайти їх в інспекторі елементів: порівняйте в консолі $$('[wire\\:key]').length з розміром new Set з тих самих значень - будь-яка різниця означає колізію.
Ключі для вкладених компонентів проти застарілого серверного стану
Це найсерйозніший випадок, бо тут уже ламається не лише DOM. Кожен вкладений компонент Livewire має власні wire:id і wire:snapshot, а коли батьківський компонент рендериться повторно, він виводить для кожного дочірнього заглушку, а не його повну розмітку. Якщо в дочірніх компонентів немає ключів, Livewire може зіставити елемент дочірнього компонента, що лишився, із заглушкою чужого запису - і екземпляр компонента, який він зберігає, містить публічні властивості попереднього запису.
@foreach ($this->invoices as $invoice)
<div wire:key="invoice-row-{{ $invoice->id }}">
<livewire:invoice-status :$invoice :wire:key="'invoice-status-'.$invoice->id" />
</div>
@endforeach
Зверніть увагу на синтаксис прив'язки :wire:key у тегу компонента, а також на те, що дочірньому компоненту потрібен власний ключ, навіть якщо його обгортка вже має ключ. Компонент Livewire, вкладений глибоко в @foreach з ключами, усе одно лишається незалежним компонентом, який Livewire має зіставляти між запитами. Дві помилки, що з'являються, коли це не вдається, варто запам'ятати, бо лише тоді цей тип збою взагалі себе виказує:
Error: Component already initialized
Error: Snapshot missing on Livewire component with id: ...
І раз уже ви тут, перевірте, що дочірній компонент справді отримує дані, а не кешує їх із mount: ключі виправляють ідентичність, але коли батьківський компонент змінює значення, яке дочірній уже тримає, - це окрема проблема, яку розв'язують реактивні пропси між батьківським і дочірнім компонентами.
Обгортаємо умови й обходимо морфінг через wire:replace
Цикли - не єдине місце, де морфінгу доводиться вгадувати. Умова, що в кожній гілці рендерить структурно різні дерева, створює ту саму неоднозначність: це змінений елемент чи вставлений? Маркери морфінгу, які вставляє Livewire, здебільшого з цим справляються, але їх отримують розбором шаблонів регулярними виразами, тож вони можуть схибити. Надійне виправлення - обгорнути умову в елемент, який присутній завжди:
<div> {{-- Рендериться завжди, тож у морфінгу є стабільна опора --}}
@if ($errors->has('reference'))
<div>{{ $errors->first('reference') }}</div>
@endif
</div>
Якщо у вашому застосунку маркери створюють більше проблем, ніж розв'язують, їх можна вимкнути повністю через 'inject_morph_markers' => false у config/livewire.php - але вважайте це крайнім заходом, а не ручкою для тонкого налаштування.
Для піддерева, яке ніколи не має проходити морфінг, wire:replace каже Livewire викинути дочірні елементи і вставити натомість нові елементи з сервера. Це правильний вибір для сторонніх віджетів і користувацьких елементів (custom elements), які самі керують своїм внутрішнім життєвим циклом, - та сама проблема межі, що й під час інтеграції стороннього JavaScript з Livewire.
<div wire:replace>
<json-viewer>@json($payload)</json-viewer>
</div>
{{-- .self замінює і сам елемент, скидаючи його x-data --}}
<div x-data="{ open: false }" wire:replace.self>
...
</div>
Ключі для lazy-компонентів та islands
Відкладений рендеринг не послаблює проблему порядку, а посилює, бо список змінює форму двічі: коли рендериться заглушка і коли надходить справжній вміст. Лінивому (lazy) дочірньому компоненту в циклі ключ потрібен із тієї самої причини, що й звичайному: Livewire має знати, яка заглушка належить якому запису, перш ніж щось підставляти.
@foreach ($this->invoices as $invoice)
<livewire:invoice-breakdown
:$invoice
:wire:key="'invoice-breakdown-'.$invoice->id"
lazy
/>
@endforeach
Те саме стосується випадку, коли ви ділите сторінку на islands і ліниво завантажувані компоненти: island оновлюється незалежно, тож його ідентичність у списку має бути стабільною, інакше оновлення потрапить не туди. Якщо поки islands завантажуються, ви показуєте скелетони-заглушки, дайте заглушці й завантаженому вмісту однаковий ключ, інакше підміна стане знищенням і створенням заново, а не морфінгом.
Чотири помилки з ключами, що створюють нові баги
Додати ключі дешево, тому їх легко додати погано. Ось чотири помилки, на які я найчастіше вказую на рев'ю.
Ключі всюди. @foreach з простих <td> без Alpine, без обробників подій і без некерованих полів ключа не потребує, а ключ там лише ховає місця, де він справді потрібен. Ставте ключі на цикли, що рендерять компонент, блок x-data або будь-яке поле, яким не керує сервер.
Ключі зі змінних значень. Ключ зі slug, імені чи email змінюється, коли користувач його редагує, і змушує повністю перебудувати рядок. Будуйте ключ на id.
Дубльовані ключі. Два цикли в одному дереві компонентів, обидва з голим id як ключем, мовчки конфліктують. Livewire не завжди вас попередить - ставте префікс.
Зміна порядку без ключів. Drag-and-drop - найгірший випадок, бо неправильним стає кожен елемент одразу, а не один. Сортування перетягуванням через wire:sort без стабільних ключів просто непридатне до використання.
Ловимо відсутні ключі на рев'ю і в Pest
Зробіть правило механічним, щоб воно не залежало від чиєїсь пам'яті: кожен @foreach, що рендерить компонент Livewire, блок Alpine або некероване поле, має wire:key з префіксом. Це однорядковий grep у CI і однорядковий коментар на рев'ю.
Тест важливіший за правило, і очевидний тест якраз не працює. Перевірка першого рендеру проходить на зламаному компоненті, бо перший рендер завжди правильний - баг існує лише в морфінгу. Перевіряйте стан після мутації.
<?php
use App\Models\Invoice;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Livewire\Livewire;
uses(RefreshDatabase::class);
it('keeps a stable key on the surviving rows after a delete', function () {
$invoices = Invoice::factory()->count(3)->create();
Livewire::test('invoice-list')
->call('delete', $invoices[1]->id)
// Рядки, що лишилися, зберігають власну ідентичність, а не нову позицію
->assertSeeHtml('wire:key="invoice-row-'.$invoices[2]->id.'"')
->assertDontSeeHtml('wire:key="invoice-row-'.$invoices[1]->id.'"');
});
Будьмо чесними щодо того, що це доводить: тест перевіряє, що ключі виводяться і що вони правильні, - а саме це й можна зламати в шаблоні. Він не доводить, що браузер зберіг стан Alpine, бо жодна серверна перевірка цього не може, - для цього потрібен браузерний тест. На практиці перевірка виведених ключів ловить ту регресію, яка справді трапляється: хтось видаляє атрибут під час рефакторингу. Livewire::test() не бачить браузера, тож межу між серверним і браузерним тестом варто тримати в голові.
Підсумок
Пройдіться по кожному @foreach у застосунку, що рендерить компонент або блок Alpine, і дайте йому ключ з префіксом, збудований із первинного ключа моделі. Це займе пів дня і закриє цілу категорію баг-репортів, які зараз позначають як «не вдалося відтворити».