Hướng dẫn ACF (Advanced Custom Fields) trong WordPress từ A-Z



Hướng dẫn ACF (Advanced Custom Fields) trong WordPress từ A-Z

Cách tạo Field Group, gọi Field, Repeater, Flexible Content, Tab, Options Page và code PHP thực chiến cho theme WordPress — cập nhật cho ACF 6.x.
ACF Free & PRO get_field() / the_field() Repeater & Flexible Content ACF Blocks (Gutenberg) Local JSON

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...

Không cần biết SQL
Field group tạo qua giao diện kéo-thả, dữ liệu tự lưu vào bảng wp_postmeta.
Linh hoạt hiển thị
Chỉ hiện field khi cần (Conditional Logic), gom nhóm bằng Tab/Group, lặp bằng Repeater.
Đồng bộ qua Local JSON
Field group có thể export ra file .json để đưa vào Git, đồng bộ giữa các môi trường dev/staging/production.
Tương thích Gutenberg
ACF Blocks cho phép tạo block Gutenberg tùy biến, dùng field ACF làm dữ liệu đầu vào.
Khi nào nên dùng ACF? Khi bạn cần dữ liệu có cấu trúc lặp lại nhiều lần trên site (ví dụ: mỗi bài "Dịch vụ" cần Giá, Thời gian thực hiện, Ảnh trước/sau) mà việc gõ tay trong content editor sẽ khó kiểm soát và khó style đồng nhất.

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.
Lưu ý về license PRO Từ ACF 6.x, một số field nâng cao (Repeater, Flexible Content, Gallery, Options Page, Clone) chỉ hoạt động đầy đủ khi có license PRO hợp lệ được kích hoạt trong Custom Fields → Updates. Nếu dùng bản free/nulled không rõ nguồn gốc, các field này có thể hiển thị nhưng không được hỗ trợ cập nhật bảo mật.

3. Tạo Field Group qua giao diện

  1. Vào Custom Fields → Add New.
  2. Đặt tên Field Group, ví dụ: Thông tin dịch vụ.
  3. 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).
  4. Chọn Field Type phù hợp (Text, Image, Repeater...).
  5. 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.
  6. Bấm Save Changes. Field group sẽ xuất hiện khi soạn bài viết thuộc Post Type đó.
Mẹo đặt tên Field Name Luôn dùng tiếng Anh không dấu, snake_case (vd: 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 TypeDùng đểFree/PRO
Text / TextareaChuỗi ngắn, đoạn mô tảFree
Number / RangeGiá, số lượng, phần trămFree
Image / FileChọn ảnh/tệp từ Media LibraryFree
GalleryNhiều ảnh (before/after, album)PRO
True/FalseBật/tắt tính năng (checkbox đơn)Free
Select / Checkbox / RadioDanh sách lựa chọn cố địnhFree
Link / URL / EmailLiên kết ngoài, nút CTAFree
Relationship / Post ObjectLiên kết tới bài viết khác (vd: bài liên quan)Free
GroupGom nhiều field con thành 1 nhóm dữ liệuFree
RepeaterLặp lại 1 nhóm field nhiều lần (vd: danh sách bước quy trình)PRO
Flexible ContentXây trang dạng "kéo khối" (section linh hoạt)PRO
TabKhông lưu dữ liệu — chỉ chia field thành các tab trong giao diện adminFree

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
<?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
<?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
<?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() vs get_field() Dùng 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
<?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>';
}
?>
Vì sao dùng Group thay vì để field rời? Group giúp code sạch hơn khi có nhiều nhóm field lặp lại ý nghĩa (vd: "Địa chỉ HCM" và "Địa chỉ Vũng Tàu" đều có field con giống nhau), đồng thời tránh trùng field name giữa các nhóm.

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
<?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
<?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;
?>
Lưu ý Không được gọi 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
<?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;
?>
Ứng dụng thực tế Rất phù hợp cho trang chủ hoặc landing page dịch vụ (như Pensilia) — admin có thể tự kéo thêm section "Ưu đãi", "Trước - Sau", "Đánh giá khách hàng" theo thứ tự tùy ý mà không cần dev can thiệp lại code.

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.

PHP – đăng ký bằng code
// 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',
),
Ghi nhớ quan trọng Vì Tab không lưu dữ liệu, bạn không bao giờ gọi 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 – trong functions.php
<?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
<?php
$hotline = get_field('hotline_chung', 'option');
echo '<a href="tel:' . $hotline . '">' . $hotline . '</a>';
?>
PRO only Options Page là tính năng chỉ có ở bản ACF PRO (từ phiên bản 6, Options Page yêu cầu license PRO để hoạt động đầy đủ trên môi trường production).

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 – trong functions.php hoặc file riêng
<?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
<?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;
});
?>
Lợi ích thực tế Khi copy theme sang site khác (VD: nhân bản site Pensilia cho chi nhánh mới), chỉ cần copy thư mục 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 – đăng ký block
<?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 – template-parts/block-uu-dai.php
<?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

update_field()
Ghi/cập nhật giá trị field bằng code, ví dụ khi xử lý form submit hoặc cron job.
delete_field()
Xóa giá trị field khỏi 1 post cụ thể.
get_fields()
Lấy toàn bộ field của 1 post dưới dạng mảng liên kết, tiện khi cần export/debug.
get_field_object()
Lấy toàn bộ cấu hình + giá trị field (label, choices, instructions...), hữu ích khi build field Select động.
PHP
<?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.

Ứng dụng thực tế Rất hữu dụng cho landing page dịch vụ nhiều biến thể — ví dụ chỉ hiện field "Số buổi liệu trình" khi loại dịch vụ là "Gói liệu trình", ẩn đi khi là "Dịch vụ 1 lần".

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 alt lấ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([...]);
#ACF#WordPress#CustomFields #Repeater#FlexibleContent#Gutenberg #PHP#OptionsPage

Đăng nhận xét

Mới hơn Cũ hơn

POST ADS1

POST ADS 2