wp-interactivity-api

Tổng quan về skill wp-interactivity-api

Skill này làm gì

Skill wp-interactivity-api giúp bạn xây dựng hoặc gỡ lỗi các tính năng WordPress Interactivity API mà không phải đoán mò về directive, cấu trúc store hay cách nối server/client. Skill này đặc biệt hữu ích khi bạn đang làm việc với markup data-wp-*, @wordpress/interactivity, viewScriptModule hoặc các hàm wp_interactivity_*() và cần một lộ trình thực tế từ một tương tác bị lỗi đến một giải pháp chạy được.

Skill này dành cho ai

Hãy dùng wp-interactivity-api skill nếu bạn đang làm Frontend Development trong một block, theme hoặc plugin WordPress và cần UI tương tác vẫn hoạt động sạch sau lần render đầu tiên. Đây là lựa chọn rất phù hợp khi bạn đã có sẵn repo và cần lần ra vì sao hydration thất bại, vì sao một directive không kích hoạt, hoặc cách cấu trúc đúng một vùng tương tác mới.

Vì sao đáng cài đặt

Giá trị chính là tăng tốc quyết định: skill này cho bạn biết nên tìm gì, đầu vào nào quan trọng, và cách tách biệt giữa cách tiếp cận ở cấp block, cấp theme và kiểu tăng cường cho plugin. Nhờ vậy, wp-interactivity-api guide hữu ích hơn một prompt chung chung vì nó phản ánh đúng các ràng buộc thực tế của WordPress 6.9+ và cách API này được nối dây.

Cách sử dụng skill wp-interactivity-api

Cài đặt và khoanh đúng phạm vi

Dùng mẫu wp-interactivity-api install từ điểm vào của directory, rồi áp dụng skill trong một phiên agent có filesystem, với bash và Node sẵn sàng. Repo ghi nhận khả năng tương thích với WordPress 6.9+ và, trong một số workflow, cả WP-CLI; nếu môi trường của bạn không thể kiểm tra file dự án hoặc chạy lệnh WordPress, kết quả sẽ yếu hơn.

Cung cấp đúng đầu vào ban đầu

wp-interactivity-api usage hoạt động tốt nhất khi bạn cung cấp:

• repo root
• đầu ra triage từ wp-project-triage
• bề mặt bị ảnh hưởng: frontend, editor, hoặc cả hai
• phiên bản WordPress và mọi ràng buộc về module/build

Prompt yếu là: “Fix the Interactivity API.”
Prompt tốt hơn là: “Debug why data-wp-on--click does not fire in this block on the frontend, WordPress 6.9, module scripts enabled, triage attached, and the issue only appears after navigation.”

Đọc các file này trước

Bắt đầu với SKILL.md, sau đó mở:

• references/directives-quickref.md để xem tên directive và các mốc tìm kiếm
• references/debugging.md để xem checklist lỗi
• references/server-side-rendering.md để xem phần thiết lập phía PHP và quy tắc hydration

Nếu bạn đang cân nhắc skill này có hợp với nhiệm vụ hiện tại hay không, ba file đó sẽ cho thấy workflow thực tế nhanh hơn nhiều so với việc chỉ nhìn cây thư mục.

Làm theo workflow thực tế

Skill này được tổ chức quanh một chuỗi đơn giản:

1. phát hiện cách dùng sẵn có bằng cách tìm data-wp-interactive, @wordpress/interactivity và viewScriptModule
2. xác định namespace của store và liệu markup có đang chờ đúng tên đó hay không
3. kiểm tra context được render từ server và initial state
4. xem root element, view script module và event directives có cùng xuất hiện trong HTML đã render hay không
5. thu hẹp phạm vi cho đến khi cô lập được directive hỏng hoặc đường dẫn state sai

Với block tương tác mới, hãy ưu tiên official scaffold template thay vì tự bịa cấu trúc từ đầu.

FAQ về skill wp-interactivity-api

Đây chỉ dành cho gỡ lỗi thôi à?

Không. wp-interactivity-api skill bao quát cả công việc build lẫn debug. Nó đặc biệt hữu ích khi bạn cần quyết định nên thêm interactivity bằng block viewScriptModule, tăng cường markup có sẵn trong plugin, hay nối hành vi ở cấp theme theo cách vẫn hydrate đúng.

Nó khác gì một prompt bình thường?

Một prompt bình thường thường bỏ qua các chi tiết đặc thù của WordPress vốn thật sự quyết định thành công: đặt tên directive, khớp namespace của store, server-side context, và các thay đổi hành vi của WordPress 6.9. Skill này tích hợp sẵn các bước kiểm tra đó, giúp giảm những lần thử sai vô ích và buộc agent đọc đúng file ngay từ đầu.

Có thân thiện với người mới không?

Có, nếu bạn mô tả được mục tiêu và chỉ đúng vùng repo cho agent. Đây không phải tutorial để học toàn bộ API từ đầu, nhưng nó giúp người mới tránh các lỗi áp dụng phổ biến nhất: thiếu interactive root, namespace không khớp, và dùng sai đường render.

Khi nào không nên dùng?

Đừng dùng cho công việc UI JavaScript không liên quan đến WordPress Interactivity API, hoặc khi tính năng của bạn hoàn toàn tĩnh và không cần directive được render từ server. Nó cũng không phù hợp nếu bạn không thể kiểm tra file repo thật, vì skill này dựa vào chi tiết markup và tích hợp PHP/JS đặc thù của repo.

Cách cải thiện skill wp-interactivity-api

Cung cấp ngữ cảnh nguồn chính xác hơn

Kết quả tốt nhất đến từ việc cho thấy bề mặt block, theme hoặc plugin hiện tại cùng directive hay function chính xác mà bạn muốn được review. Hãy đưa vào các đoạn trích quanh data-wp-interactive, data-wp-context và namespace store tương ứng để agent có thể đối chiếu ý định với cách triển khai thay vì phải suy đoán.

Nói rõ kiểu lỗi, không chỉ mô tả triệu chứng

Với wp-interactivity-api skill, câu “button không làm gì cả” là quá mơ hồ. Đầu vào tốt hơn nên nêu lỗi quan sát được và hành vi mong đợi: “click handler đã được gắn nhưng state không cập nhật sau server render,” hoặc “hydration chạy ở lần load đầu nhưng lỗi sau client-side navigation.” Điều đó giúp phân biệt lỗi directive với lỗi khởi tạo state hoặc tải module.

Yêu cầu đầu ra theo kiểu đọc repo, rồi lặp lại

Một workflow tốt cho wp-interactivity-api guide là yêu cầu:

• nguyên nhân gốc khả dĩ nhất
• chính xác file nào cần kiểm tra tiếp
• thay đổi mã tối thiểu
• rủi ro tương thích với WordPress 6.9

Sau đó lặp lại với kết quả đầu tiên trong tay. Nếu vấn đề liên quan đến server rendering, hãy kèm PHP liên quan và HTML đã render. Nếu liên quan đến xử lý sự kiện, hãy kèm markup directive và file actions của store. Cách này biến skill từ một công cụ tìm kiếm thành một checklist triển khai thực sự dùng được.