Steven Richardson เขียนเรื่องนี้ไว้ละเอียดจากบั๊กที่หลายคนน่าจะเคยเจอ คือผู้ใช้แจ้งว่าลบแถวหนึ่งแล้วแถวที่เลือกไว้กลายเป็นแถวอื่น ลองรีเฟรชหน้าใหม่ก็ไม่เจอ log ก็ไม่มี error สุดท้ายก็ปิดเรื่องไปว่าทำซ้ำไม่ได้ โพสต์นี้สรุปว่าทำไมถึงเกิด และใส่ wire:key ยังไงให้หายขาด
ลบแถวที่สองแล้วโน้ตของแถวที่สามย้ายขึ้นมา
ลองนึกถึงหน้ารายการใบแจ้งหนี้ที่ทำด้วย Livewire แต่ละแถวมีเมนูที่เปิดปิดด้วย Alpine (x-data="{ open: false }") มีช่องจดโน้ตที่ไม่ได้ผูก wire:model และมีปุ่มลบที่เรียก wire:click="delete(...)" ทั้งลิสต์ไม่มี wire:key เลย
ทีนี้ผู้ใช้พิมพ์โน้ตในแถวที่สามว่า "รอฝ่ายบัญชีเช็ค" เปิดเมนูของแถวนั้นค้างไว้ แล้วกดลบแถวที่สอง ผลคือแถวที่สามขยับขึ้นมาเป็นแถวที่สองตามปกติ แต่โน้ตกับเมนูที่เปิดค้างไปอยู่ผิดแถว ข้อมูลจากฐานข้อมูลถูกหมด ส่วนที่ผิดคือของที่ติดอยู่กับ DOM ของแถวนั้น
component แบบนี้ผ่าน test ที่เราน่าจะเขียนได้ทุกตัว เพราะ HTML ที่ server ส่งมาถูกต้องเสมอ ปัญหาเกิดตอนที่ browser เอา HTML ใหม่ไปแปะทับของเดิม
Livewire อัปเดตหน้าด้วยการ morph DOM
ทุกครั้งที่ component render ใหม่ Livewire จะเดินไล่ DOM เก่ากับ HTML ใหม่ไปพร้อมกัน แล้วแก้เฉพาะจุดที่ต่าง วิธีนี้เรียกว่า morph และเป็นเหตุผลที่ช่องที่กำลังพิมพ์ไม่หลุด focus และ event listener ไม่หายระหว่าง request
ถ้าแถวไม่มีอะไรบอกว่าเป็นแถวไหน Livewire ก็จับคู่ตามตำแหน่งได้อย่างเดียว ในตัวอย่างข้างบนจึงเกิดแบบนี้
| DOM เดิม | HTML ใหม่ | สิ่งที่ Livewire ทำ |
|---|---|---|
| แถว 1 (INV-1) | แถว 1 (INV-1) | เหมือนเดิม ไม่แตะ |
| แถว 2 (INV-2 ไม่มีโน้ต) | แถว 2 (INV-3) | แก้ข้อความในแถวเดิมเป็น INV-3 |
| แถว 3 (INV-3 มีโน้ต) | ไม่มีแล้ว | ลบ element สุดท้ายทิ้ง |
แถวที่สามไม่ได้ขยับขึ้นมาเลย Livewire เขียนข้อความของแถวที่สองใหม่ให้เป็น INV-3 แล้วลบ element ตัวสุดท้ายทิ้ง ตัวที่ถูกลบคือตัวที่มีโน้ตกับเมนูเปิดค้างอยู่นั่นเอง
state สี่อย่างที่ติดอยู่กับ DOM และ component ลูกที่หนักกว่า
ของที่อยู่กับ element ใน browser และพังแบบเดียวกันนี้มีสี่อย่าง
- state ของ Alpine ใน
x-dataเช่นเมนูหรือ dropdown ที่เปิดอยู่ - focus เช่นกำลังพิมพ์อยู่แล้ว cursor กระโดดไปอีกแถว
- ตำแหน่ง scroll ใน cell ที่เลื่อนได้
- ค่าของ input ที่ไม่ได้ผูก
wire:model
ถ้าบั๊กที่ได้รับแจ้งตรงกับข้อใดข้อหนึ่ง ผู้เขียนแนะนำให้หยุดไล่โค้ดฝั่ง server ไปเลย เพราะแทบแน่นอนว่าเป็นเรื่องของ key
กรณีที่หนักกว่าคือลิสต์ที่ render Livewire component ลูกในแต่ละแถว component ลูกมี wire:id และ snapshot ของตัวเอง ตอน parent render ใหม่ Livewire ส่งแค่ตัวแทนของลูกแต่ละตัวมา ไม่ได้ส่ง HTML ทั้งหมด ถ้าไม่มี key ลูกตัวที่รอดอาจถูกจับคู่กับตัวแทนของ record อื่น ลูกตัวนั้นก็จะถือ public property ของ record ก่อนหน้าต่อไป คราวนี้ข้อมูลฝั่ง server ก็ผิดด้วย ไม่ใช่แค่หน้าจอ
ใช้ primary key ของ model เป็น key และใส่ prefix
ใส่ wire:key ที่ element แรกในลูป โดยใช้ id ของ model
@foreach ($this->invoices as $invoice)
<div wire:key="invoice-row-{{ $invoice->id }}" x-data="{ open: false }">
{{-- ... --}}
</div>
@endforeach
key ต้องไม่ซ้ำกันทั้ง component ไม่ใช่แค่ในลูปเดียว ถ้าหน้าเดียวมีสองลูปที่ใช้ id เปล่า ๆ เป็น key ใบแจ้งหนี้เลข 5 กับลูกค้าเลข 5 ก็จะได้ key เดียวกัน ผู้เขียนบอกว่าแบบนี้แย่กว่าไม่ใส่ key เสียอีก จึงควรใส่ prefix ตามชื่อของสิ่งนั้นเสมอ เช่น invoice-row-5 กับ customer-row-5 ผู้เขียนใช้รูปแบบ {ชื่อ}-{บริบท}-{id}
ตัวอย่างใน เอกสารของ Livewire ใช้ id เปล่า ๆ อย่าง :wire:key="$todo->id" ซึ่งใช้ได้ถ้าหน้านั้นมีลิสต์เดียว แต่พอหน้าโตขึ้นจนมีหลายลิสต์ การมี prefix ไว้ตั้งแต่แรกช่วยกันการชนได้
วิธีเช็คว่ามี key ซ้ำในหน้าหรือเปล่า ให้เปิด console ใน browser แล้วเทียบจำนวน element ที่มี wire:key กับจำนวนค่าที่ไม่ซ้ำกัน ถ้าสองตัวเลขไม่เท่ากันก็แปลว่ามีตัวที่ชน
component ลูกต้องมี key ของตัวเองด้วย
แม้ div ที่ครอบจะมี key แล้ว component ลูกก็ยังต้องมี key ของตัวเอง สังเกตว่าบน tag ของ component ใช้ :wire:key แบบมี colon นำหน้า
@foreach ($this->invoices as $invoice)
<div wire:key="invoice-row-{{ $invoice->id }}">
<livewire:invoice-status :$invoice :wire:key="'invoice-status-'.$invoice->id" />
</div>
@endforeach
ถ้าลืม key ของลูก error ที่เห็นใน console มักเป็น Component already initialized หรือ Snapshot missing on Livewire component with id: ... เห็นสองข้อความนี้เมื่อไหร่ ให้ไปดู key ในลูปก่อน
component ลูกที่โหลดแบบ lazy ก็ต้องมี key เหมือนกัน เพราะลิสต์เปลี่ยนรูปสองรอบ คือตอนแสดง placeholder กับตอนได้ของจริง และ placeholder กับเนื้อหาจริงควรใช้ key เดียวกัน ไม่อย่างนั้น Livewire จะทำลายแล้วสร้าง element ใหม่แทนการ morph
key แบบไหนที่ทำให้ปัญหาแย่ลง
$loop->indexคือตำแหน่งของแถว ซึ่งเป็นสิ่งที่เราอยากให้ Livewire เลิกใช้ ใส่ไว้ก็เหมือนไม่ได้ใส่- ค่าที่ผู้ใช้แก้ได้ เช่นชื่อ อีเมล หรือ slug พอผู้ใช้บันทึกแล้ว key เปลี่ยน แถวนั้นจะถูกรื้อแล้วสร้างใหม่ หน้าจอกระพริบและ state ฝั่ง browser หาย
- key ซ้ำกันในหน้า Livewire ไม่ได้เตือนทุกครั้ง จึงต้องกันด้วย prefix
- ใส่ key ทุกลูป ตารางที่มีแต่
<td>ธรรมดา ไม่มี Alpine ไม่มี input และไม่มี component ลูก ไม่จำเป็นต้องมี key การใส่ทุกที่ทำให้มองไม่ออกว่าลูปไหนสำคัญจริง
ลูปที่ต้องมี key คือลูปที่ render Livewire component, block ที่มี x-data หรือ input ที่ server ไม่ได้คุม ส่วนลิสต์ที่ลากเรียงได้ (wire:sort) ต้องมี key เสมอ เพราะทุกแถวขยับพร้อมกัน ถ้าไม่มี key ก็ผิดหมดทุกแถว
เงื่อนไข @if กับส่วนที่ไม่ต้อง morph
นอกจากลูปแล้ว block @if ที่โผล่และหายไปก็ทำให้ morph จับคู่ผิดได้ Livewire พยายามช่วยโดยแทรก comment ครอบ block ของ Blade ไว้ แต่ใช้ regex แยก template จึงพลาดได้บ้าง ทางที่ชัวร์กว่าคือครอบด้วย element ที่มีอยู่เสมอ
<div>
@if ($errors->has('reference'))
<div>{{ $errors->first('reference') }}</div>
@endif
</div>
ส่วน widget จาก library อื่นที่จัดการ DOM เอง ใส่ wire:replace ให้ Livewire แทนที่ทั้งก้อนแทนการ morph ได้ ถ้าอยากให้ state ของ Alpine รีเซ็ตทุกครั้งที่ render ใหม่ ก็ใส่ wire:replace.self ที่ element ที่มี x-data
test ฝั่ง server เช็คได้แค่ว่า key ยังอยู่
test ที่ดูแค่ HTML รอบแรกจะผ่านเสมอ แม้ component จะไม่มี key เพราะรอบแรกถูกต้องทุกครั้ง บั๊กเกิดตอน morph เท่านั้น ผู้เขียนจึงแนะนำให้ test เรียก action ลบก่อน แล้วค่อยเช็คว่าแถวที่เหลือยังมี key ตาม id ของตัวเอง และ key ของแถวที่ลบหายไปแล้ว
test แบบนี้บอกได้ว่า template ยังส่ง key ที่ถูกต้องออกมา ซึ่งเป็นส่วนที่พังบ่อยที่สุดในงานจริง เช่นมีคนลบ attribute ทิ้งตอน refactor แต่บอกไม่ได้ว่า browser เก็บ state ของ Alpine ไว้ถูกแถว ถ้าอยากรู้ส่วนนั้นต้องใช้ browser test
ผู้เขียนแนะนำให้ตั้งเป็นกฎของทีมไปเลยว่าทุก @foreach ที่ render component, Alpine block หรือ input ที่ไม่ผูก wire:model ต้องมี wire:key แบบมี prefix ไล่เช็คโปรเจกต์ที่มีอยู่ใช้เวลาแค่บ่ายเดียว แต่ปิดบั๊กกลุ่ม "ทำซ้ำไม่ได้" ได้ทั้งกลุ่ม
ตัวอย่างโค้ดเต็มและ FAQ อ่านต่อได้ที่บทความของ Steven Richardson






