Nếu bạn cài WooCommerce vào một theme tự code mà chưa khai báo gì, trang cửa hàng thường hiện ra mất bố cục, sản phẩm chèn ngang trang nội dung, sidebar lệch. Lý do không phải theme hỏng, mà là WooCommerce chưa được “báo” rằng theme này biết cách hiển thị cửa hàng. Bài này đi qua đúng một dòng khai báo cốt lõi, các tuỳ chọn đi kèm, cách ghi đè (override) template Woo, và vì sao nên ưu tiên hook hơn là chép file template.
Một dòng khai báo quyết định toàn bộ
Toàn bộ cơ chế nằm ở hàm add_theme_support('woocommerce'), gắn vào hook after_setup_theme trong functions.php:
function web22_add_woocommerce_support() {
add_theme_support( 'woocommerce' );
}
add_action( 'after_setup_theme', 'web22_add_woocommerce_support' );Có hai điều dễ sai. Thứ nhất là hook: phải dùng after_setup_theme, không dùng init — tài liệu WooCommerce nói rõ điều này, vì nhiều tính năng cửa hàng kiểm tra cờ hỗ trợ ở giai đoạn rất sớm. Thứ hai là hậu quả khi quên: WooCommerce mặc định coi theme của bạn “không được thiết kế cho cửa hàng” và rơi vào chế độ dự phòng bằng shortcode, dẫn tới bố cục vỡ, phần tử mất style. Đây là nguyên nhân số một khiến trang shop trông như chưa cài theme.
Truyền tham số để chỉnh kích thước ảnh và lưới sản phẩm
Tham số thứ hai của hàm là một mảng tuỳ chọn. Nó cho bạn đặt sẵn chiều rộng ảnh và cấu hình lưới sản phẩm khớp với khung lưới (grid) của theme:
function web22_add_woocommerce_support() {
add_theme_support( 'woocommerce', array(
'thumbnail_image_width' => 320,
'single_image_width' => 640,
'product_grid' => array(
'default_rows' => 3,
'min_rows' => 2,
'default_columns' => 3,
'min_columns' => 2,
'max_columns' => 5,
),
) );
}
add_action( 'after_setup_theme', 'web22_add_woocommerce_support' );Khai báo single_image_width và thumbnail_image_width giúp WooCommerce sinh đúng kích thước ảnh khi bạn tái tạo thư viện ảnh (regenerate), tránh ảnh sản phẩm bị mờ hoặc nặng. Phần product_grid ấn định số cột mặc định để lưới shop không nhảy lung tung khi đổi giao diện.
Bật thư viện ảnh sản phẩm có zoom và lightbox
Ba tính năng ảnh sản phẩm là cờ riêng, mặc định không tự bật. Thêm chúng cùng chỗ khai báo:
add_theme_support( 'wc-product-gallery-zoom' );
add_theme_support( 'wc-product-gallery-lightbox' );
add_theme_support( 'wc-product-gallery-slider' );Ba dòng này lần lượt bật phóng to khi rê chuột (zoom), mở ảnh phóng đại toàn màn hình (lightbox — hộp đèn) và trượt giữa các ảnh (slider). Nếu theme của bạn tự xử lý gallery bằng JavaScript riêng, hãy remove_theme_support đúng cờ tương ứng để tránh hai thư viện đánh nhau.
Override template Woo trong theme đúng cách
WooCommerce đi kèm bộ template mặc định trong thư mục plugins/woocommerce/templates/. Bạn không sửa trực tiếp ở đó (cập nhật plugin sẽ ghi đè mất). Thay vào đó, chép file cần đổi vào thư mục con woocommerce/ bên trong theme, giữ nguyên đường dẫn. Ví dụ muốn đổi template trang sản phẩm đơn của theme cổ điển (classic theme):
wp-content/themes/web22/woocommerce/single-product.php
wp-content/themes/web22/woocommerce/archive-product.php
wp-content/themes/web22/woocommerce/content-product.phpQuan trọng: cơ chế override này chỉ hoạt động khi theme đã khai báo add_theme_support('woocommerce'). Thiếu khai báo, WooCommerce bỏ qua thư mục woocommerce/ trong theme và bạn sẽ tưởng file mình chép vào “không ăn”.
Với theme khối (block theme — theme dựng bằng FSE), cách override khác hẳn: bạn đặt file HTML trong templates/. Một file templates/single-product.html trong theme sẽ ưu tiên hơn template Single Product mặc định của WooCommerce. Nếu bạn còn phân vân chọn hướng nào, bài so sánh block theme và classic theme phân tích kỹ điểm khác biệt.
Vì sao nên dùng hook thay vì chép template
Đây là lời khuyên thẳng từ tài liệu chính thống: bất cứ khi nào có thể, hãy dùng hook để thêm hoặc bớt nội dung thay vì override cả file template. Lý do thực dụng — file template bạn chép là một bản đông cứng tại thời điểm chép; mỗi lần WooCommerce cập nhật cấu trúc template, bạn phải tự đồng bộ lại, nếu không sẽ thiếu tính năng mới hoặc dính lỗi. Còn hook thì ít thay đổi hơn nhiều.
Các hook chính bao quanh khung hiển thị cửa hàng gồm woocommerce_before_main_content, woocommerce_after_main_content, woocommerce_before_shop_loop và woocommerce_single_product_summary. Ví dụ thêm một dòng thông báo phía trên danh sách sản phẩm mà không đụng template nào:
function web22_shop_loop_notice() {
echo '<p class="shop-notice">Miễn phí giao trong nội thành</p>';
}
add_action( 'woocommerce_before_shop_loop', 'web22_shop_loop_notice', 5 );Tham số cuối (5) là độ ưu tiên (priority) quyết định vị trí chèn so với các phần tử khác cùng hook. Nếu bạn chưa quen cách hook hoạt động, bài action và filter trong WordPress giải thích từ gốc, còn việc tổ chức code khai báo gọn gàng thì xem cách viết functions.php sạch.
Kiểm tra theme đã hỗ trợ Woo chưa
Một dòng để xác nhận, đặt tạm ở đâu đó chạy được:
if ( current_theme_supports( 'woocommerce' ) ) {
// Theme da khai bao ho tro WooCommerce
}Trong thực tế dựng theme cho khách, Web22 luôn đặt khối khai báo này ngay từ khi khởi tạo theme, kèm cờ gallery, để trang sản phẩm chạy đúng ngay từ lần cài WooCommerce đầu tiên — tránh cảnh cài xong shop vỡ rồi mới đi vá.
Câu hỏi thường gặp
Không khai báo theme support thì cửa hàng có chạy không?
Có chạy nhưng WooCommerce rơi vào chế độ dự phòng bằng shortcode, thường khiến bố cục vỡ và phần tử mất style. Khai báo một dòng là cách dứt điểm.
Override template hay dùng hook tốt hơn?
Ưu tiên hook khi chỉ cần thêm/bớt nội dung, vì hook ít thay đổi và dễ bảo trì. Chỉ override cả file khi cần đổi cấu trúc bố cục mà hook không với tới.
Theme khối có khai báo giống classic theme không?
Cờ add_theme_support('woocommerce') vẫn nên có, nhưng cách override chuyển sang đặt file HTML trong thư mục templates/ thay vì chép file PHP vào woocommerce/.
Nếu bạn muốn một theme tự code chuẩn tương thích WooCommerce ngay từ đầu, tham khảo dịch vụ phát triển WordPress của Web22 hoặc phần làm theme tuỳ biến.