Hướng dẫn ACF (Advanced Custom Fields) trong WordPress từ A-Z
1. ACF là gì? Vì sao nên dùng
Advanced Custom Fields (ACF) là plugin cho phép bạn thêm các trường dữ liệu tùy chỉnh (custom fields) vào màn hình chỉnh sửa của Post, Page, Custom Post Type, Category, User, hoặc thậm chí một trang Options riêng — mà không cần sửa database thủ công. Thay vì nhồi nhét nội dung vào ô content chính, bạn có thể tách riêng từng phần dữ liệu có cấu trúc: giá dịch vụ, thông số kỹ thuật, banner, gallery, FAQ...
wp_postmeta.2. Cài đặt & kích hoạt ACF
- Vào Plugins → Add New, tìm "Advanced Custom Fields", cài đặt và kích hoạt (bản Free đủ dùng cho hầu hết trường hợp cơ bản).
- Nếu cần Repeater, Flexible Content, Gallery, Options Page, Clone Field ở quy mô lớn hoặc cần Block Editor nâng cao → cân nhắc bản ACF PRO (trả phí, có license).
- Sau khi kích hoạt, menu Custom Fields sẽ xuất hiện ở sidebar admin WordPress.
3. Tạo Field Group qua giao diện
- Vào Custom Fields → Add New.
- Đặt tên Field Group, ví dụ:
Thông tin dịch vụ. - Bấm Add Field, đặt Field Label (tên hiển thị) và Field Name (tên dùng trong code, viết thường, không dấu, dùng dấu gạch dưới — ví dụ
gia_dich_vu). - Chọn Field Type phù hợp (Text, Image, Repeater...).
- Kéo xuống mục Location, thiết lập điều kiện hiển thị field group này — ví dụ:
Post Type is equal to Dich_vu. - Bấm Save Changes. Field group sẽ xuất hiện khi soạn bài viết thuộc Post Type đó.
gia_tri_min), tránh đổi tên field name sau khi đã có dữ liệu thật vì dữ liệu cũ sẽ "mồ côi" trong database.
4. Các loại Field phổ biến
| Field Type | Dùng để | Free/PRO |
|---|---|---|
| Text / Textarea | Chuỗi ngắn, đoạn mô tả | Free |
| Number / Range | Giá, số lượng, phần trăm | Free |
| Image / File | Chọn ảnh/tệp từ Media Library | Free |
| Gallery | Nhiều ảnh (before/after, album) | PRO |
| True/False | Bật/tắt tính năng (checkbox đơn) | Free |
| Select / Checkbox / Radio | Danh sách lựa chọn cố định | Free |
| Link / URL / Email | Liên kết ngoài, nút CTA | Free |
| Relationship / Post Object | Liên kết tới bài viết khác (vd: bài liên quan) | Free |
| Group | Gom nhiều field con thành 1 nhóm dữ liệu | Free |
| Repeater | Lặp lại 1 nhóm field nhiều lần (vd: danh sách bước quy trình) | PRO |
| Flexible Content | Xây trang dạng "kéo khối" (section linh hoạt) | PRO |
| Tab | Không lưu dữ liệu — chỉ chia field thành các tab trong giao diện admin | Free |
5. Cách gọi Field cơ bản trong code
Đây là phần quan trọng nhất — cách lấy dữ liệu ACF ra ngoài theme (file single.php, page.php, template part...).
5.1. the_field() — in trực tiếp ra màn hình
<?php
// In trực tiếp giá trị field 'gia_dich_vu' của bài viết hiện tại
the_field('gia_dich_vu');
?>
5.2. get_field() — lấy giá trị để xử lý logic
<?php
$gia = get_field('gia_dich_vu');
if ( $gia ) {
echo '<span class="price">' . number_format($gia) . ' đ</span>';
} else {
echo 'Liên hệ để biết giá';
}
?>
5.3. Gọi field của post/page khác (không phải bài hiện tại)
<?php
// Tham số thứ 2 là Post ID cụ thể
$gia = get_field('gia_dich_vu', 123);
// Lấy field của Options Page (trang cài đặt toàn site)
$hotline = get_field('hotline_chung', 'option');
// Lấy field của Term (Category/Taxonomy)
$mo_ta_them = get_field('mo_ta_seo', 'category_5');
// Lấy field của User
$chuc_danh = get_field('chuc_danh', 'user_10');
?>
the_field() khi chỉ cần in ra ngay lập tức. Dùng get_field() khi cần kiểm tra điều kiện, format lại dữ liệu (number_format, date, nối chuỗi HTML) trước khi in ra.
6. Gọi Group Field
Field Group gom nhiều field con vào 1 "hộp" duy nhất trong admin, nhưng khi lấy dữ liệu, ACF trả về dạng mảng (array) chứa các field con bên trong.
<?php
// Giả sử Group tên là 'thong_tin_lien_he' chứa field con: dia_chi, dien_thoai
$lien_he = get_field('thong_tin_lien_he');
if ( $lien_he ) {
echo '<p>Địa chỉ: ' . $lien_he['dia_chi'] . '</p>';
echo '<p>Điện thoại: ' . $lien_he['dien_thoai'] . '</p>';
}
?>
7. Gọi Repeater Field
Repeater cho phép người dùng admin thêm nhiều "hàng" dữ liệu lặp lại — ví dụ: danh sách bước quy trình điều trị, danh sách ưu đãi... Có 2 cách phổ biến để lấy dữ liệu.
7.1. Cách dùng have_rows() / the_row() (khuyến nghị)
<?php
if ( have_rows('quy_trinh_thuc_hien') ) :
echo '<ol class="quy-trinh">';
while ( have_rows('quy_trinh_thuc_hien') ) : the_row();
$buoc = get_sub_field('ten_buoc');
$mo_ta = get_sub_field('mo_ta');
$anh = get_sub_field('hinh_anh');
echo '<li>';
if ( $anh ) {
echo '<img src="' . esc_url($anh['url']) . '" alt="' . esc_attr($buoc) . '">';
}
echo '<h4>' . esc_html($buoc) . '</h4>';
echo '<p>' . esc_html($mo_ta) . '</p>';
echo '</li>';
endwhile;
echo '</ol>';
endif;
?>
7.2. Cách dùng get_field() trả mảng (thay thế)
<?php
$rows = get_field('quy_trinh_thuc_hien'); // trả về mảng các hàng
if ( $rows ) :
foreach ( $rows as $row ) :
echo '<li>' . esc_html($row['ten_buoc']) . '</li>';
endforeach;
endif;
?>
get_sub_field() bên ngoài vòng lặp have_rows() — hàm này chỉ hoạt động bên trong ngữ cảnh "đang duyệt 1 hàng" của Repeater/Flexible Content.
8. Gọi Flexible Content
Flexible Content giống Repeater nhưng cho phép mỗi "hàng" là 1 kiểu layout khác nhau — phù hợp để xây trang dạng kéo-thả section (banner, text-image, testimonial, FAQ...) mà không cần page builder.
<?php
if ( have_rows('noi_dung_trang') ) :
while ( have_rows('noi_dung_trang') ) : the_row();
if ( get_row_layout() == 'banner' ) :
$tieu_de = get_sub_field('tieu_de');
$anh_nen = get_sub_field('anh_nen');
echo '<section class="banner" style="background-image:url(' . $anh_nen['url'] . ')">';
echo '<h2>' . esc_html($tieu_de) . '</h2></section>';
elseif ( get_row_layout() == 'text_hinh_anh' ) :
$noi_dung = get_sub_field('noi_dung');
$anh = get_sub_field('hinh_anh');
echo '<section class="text-image">';
echo '<img src="' . $anh['url'] . '">';
echo $noi_dung . '</section>';
endif;
endwhile;
endif;
?>
9. Tab Field & tổ chức giao diện
Tab là field đặc biệt: không lưu dữ liệu, chỉ có tác dụng chia các field phía sau nó thành từng tab riêng trong màn hình soạn thảo, giúp admin dễ nhìn khi field group có nhiều field.
// Cấu trúc field trong mảng khi đăng ký local field group
array(
'key' => 'field_tab_1',
'label' => 'Thông tin chung',
'type' => 'tab',
),
array(
'key' => 'field_ten_dv',
'label' => 'Tên dịch vụ',
'name' => 'ten_dich_vu',
'type' => 'text',
),
array(
'key' => 'field_tab_2',
'label' => 'SEO & Hiển thị',
'type' => 'tab',
),
array(
'key' => 'field_meta_desc',
'label' => 'Meta Description',
'name' => 'meta_description',
'type' => 'textarea',
),
get_field('field_tab_1') ngoài front-end — chỉ gọi field name của các field con nằm bên trong tab đó như bình thường.
10. Options Page (cài đặt toàn site)
Dùng khi cần các field áp dụng cho toàn bộ website thay vì 1 bài viết cụ thể — ví dụ: hotline chung, địa chỉ các chi nhánh, mã Facebook Pixel, banner mặc định.
<?php
if( function_exists('acf_add_options_page') ) {
acf_add_options_page(array(
'page_title' => 'Cài đặt Website',
'menu_title' => 'Cài đặt Website',
'menu_slug' => 'cai-dat-website',
'capability' => 'edit_posts',
'redirect' => false,
));
}
?>
Sau đó tạo Field Group mới, ở mục Location chọn Options Page is equal to Cài đặt Website. Khi lấy dữ liệu:
<?php
$hotline = get_field('hotline_chung', 'option');
echo '<a href="tel:' . $hotline . '">' . $hotline . '</a>';
?>
11. Đăng ký Field Group bằng PHP + Local JSON
Thay vì tạo field group hoàn toàn qua giao diện (dễ mất khi đổi hosting/migrate), dân dev thường đăng ký field group bằng code PHP và bật Local JSON để version control (Git) được, đồng thời tăng tốc độ load do ACF đọc JSON thay vì query database.
11.1. Đăng ký field group bằng acf_add_local_field_group()
<?php
add_action('acf/init', function() {
if ( ! function_exists('acf_add_local_field_group') ) return;
acf_add_local_field_group(array(
'key' => 'group_dich_vu',
'title' => 'Thông tin dịch vụ',
'fields' => array(
array(
'key' => 'field_gia_dv',
'label' => 'Giá dịch vụ',
'name' => 'gia_dich_vu',
'type' => 'number',
),
array(
'key' => 'field_thoi_gian',
'label' => 'Thời gian thực hiện',
'name' => 'thoi_gian_thuc_hien',
'type' => 'text',
),
),
'location' => array(
array(
array(
'param' => 'post_type',
'operator' => '==',
'value' => 'dich_vu',
),
),
),
));
});
?>
11.2. Bật Local JSON (đồng bộ khi tạo field qua giao diện)
<?php
add_filter('acf/settings/save_json', function( $path ) {
return get_stylesheet_directory() . '/acf-json';
});
add_filter('acf/settings/load_json', function( $paths ) {
unset( $paths[0] );
$paths[] = get_stylesheet_directory() . '/acf-json';
return $paths;
});
?>
acf-json — toàn bộ field group tự động xuất hiện, không cần tạo lại thủ công.
12. ACF Blocks cho Gutenberg
ACF cho phép tạo Custom Block cho trình soạn thảo Gutenberg, dùng field ACF làm nguồn dữ liệu — rất hữu ích khi muốn admin tự kéo-thả các khối nội dung có style riêng vào bài viết.
<?php
add_action('acf/init', function() {
if ( function_exists('acf_register_block_type') ) {
acf_register_block_type(array(
'name' => 'khoi-uu-dai',
'title' => __('Khối ưu đãi'),
'render_template' => 'template-parts/block-uu-dai.php',
'category' => 'formatting',
'icon' => 'megaphone',
'mode' => 'edit',
));
}
});
?>
<?php
$tieu_de = get_field('tieu_de_uu_dai');
$noi_dung = get_field('noi_dung_uu_dai');
?>
<div class="block-uu-dai">
<h3><?php echo esc_html( $tieu_de ); ?></h3>
<div><?php echo $noi_dung; ?></div>
</div>
13. Các hàm ACF hữu ích khác
<?php
// Ghi dữ liệu bằng code, ví dụ tăng biến đếm lượt xem
$luot_xem = (int) get_field('luot_xem', $post_id);
update_field('luot_xem', $luot_xem + 1, $post_id);
// Lấy toàn bộ field của 1 post
$all_fields = get_fields( $post_id );
print_r( $all_fields );
?>
14. Conditional Logic
Cho phép field chỉ hiện ra khi 1 field khác thỏa điều kiện — ví dụ: chỉ hiện field "Link video" khi field "Loại banner" được chọn là Video. Thiết lập ngay trong giao diện tạo field, mục Conditional Logic, không cần viết thêm code JS.
15. Tối ưu hiệu năng & SEO khi dùng ACF
- Luôn escape dữ liệu khi in ra:
esc_html(),esc_url(),esc_attr()để tránh lỗi XSS và giữ HTML hợp lệ cho SEO. - Với field ảnh, luôn thêm
altlấy từ field riêng hoặc field label, không để trống — ảnh có alt text tốt giúp SEO hình ảnh và Accessibility. - Bật Local JSON giúp giảm số query database khi load field group, cải thiện tốc độ trang.
- Với nội dung quan trọng cho SEO (mô tả dịch vụ, FAQ), nên cân nhắc dùng field Wysiwyg hoặc Textarea thay vì Repeater quá sâu — Googlebot đọc HTML render cuối cùng, không quan trọng field nằm ở đâu trong ACF, miễn là HTML render ra có cấu trúc heading (H2, H3) hợp lý.
- Tránh Repeater/Flexible Content lồng quá nhiều tầng — vừa khó bảo trì, vừa có thể ảnh hưởng tốc độ query nếu dữ liệu lớn.
16. Lỗi thường gặp (FAQ)
Gọi get_field() nhưng luôn trả về null/rỗng?
Kiểm tra: (1) Field Name gõ có đúng chính xác chữ hoa/thường không, (2) đang gọi field trong đúng ngữ cảnh Loop (biến $post toàn cục có đúng bài viết đang hiển thị không), (3) field group có Location Rule khớp với post type/trang hiện tại không.
Repeater/Options Page không hoạt động sau khi lên production?
Đây thường là do license PRO chưa được kích hoạt trên domain đó. Vào Custom Fields → Updates để kiểm tra và nhập license key hợp lệ.
Ảnh từ field Image trả về URL hay Array?
Tùy vào cấu hình Return Format khi tạo field (Array, URL, hoặc ID). Nếu chọn Array, phải truy cập qua $anh['url']; nếu chọn URL, biến đã là chuỗi URL sẵn — dùng trực tiếp không cần ['url'].
Muốn field group chỉ hiện ở 1 trang cụ thể (không phải cả Post Type)?
Ở mục Location, chọn rule Page is equal to [Tên trang cụ thể] thay vì Post Type is equal to Page.
Có nên tạo field group hoàn toàn bằng code thay vì giao diện?
Với site nhỏ, tạo qua giao diện + bật Local JSON là đủ. Với site lớn, nhiều môi trường (dev/staging/production) hoặc cần đưa lên Git, nên đăng ký hẳn bằng acf_add_local_field_group() để kiểm soát version tốt hơn.
17. Cheat sheet tổng hợp
In field ra màn hình
the_field('ten_field');Lấy giá trị để xử lý
get_field('ten_field');Lấy field của post khác
get_field('x', $post_id);Lấy field Options Page
get_field('x', 'option');Lấy field trong Group
get_field('nhom')['field_con'];Duyệt Repeater
have_rows() / the_row() / get_sub_field()Duyệt Flexible Content
get_row_layout() trong vòng lặp have_rows()Ghi dữ liệu bằng code
update_field('x', $value, $post_id);Lấy tất cả field 1 post
get_fields($post_id);Đăng ký field group bằng code
acf_add_local_field_group([...]);