Nhảy đến nội dung

Giới thiệu

Các khối nội dung có thể tái sử dụng được sử dụng trên nhiều trang khác nhau.

Thông tin thêm về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/category/blocks

🎯 Mô-đun này làm gì?​

Mô-đun Blocks cho phép bạn sử dụng các thành phần nội dung tái sử dụng (khối) chứa các tập hợp thuộc tính và có thể được sử dụng trên nhiều trang và trang sản phẩm - như tiêu đề, chân trang, banner, đánh giá, hoặc bất kỳ nội dung nào lặp lại.

Hãy nghĩ về nó như những viên gạch LEGO cho trang web của bạn - bạn tạo một khối một lần, và tái sử dụng nó ở bất cứ đâu bạn cần. Thay đổi khối một lần, và nó sẽ tự động cập nhật ở mọi nơi.

📖 Giải thích đơn giản​

Hãy tưởng tượng bạn đang xây dựng một trang web với:

  • 🔝 Tiêu đề - logo, menu điều hướng (giống nhau trên mọi trang)
  • 🔽 Chân trang - thông tin liên hệ, liên kết mạng xã hội (giống nhau trên mọi trang)
  • 📢 Banner khuyến mãi - ưu đãi đặc biệt (xuất hiện trên nhiều trang)
  • ⭐ Đánh giá - nhận xét của khách hàng (được tái sử dụng ở nhiều nơi)
  • 📞 Mẫu liên hệ - xuất hiện trên nhiều trang

Thay vì sao chép nội dung này vào mỗi trang:

  • ✅ Tạo một lần dưới dạng một Khối
  • ✅ Chèn khối ở bất cứ đâu bạn cần
  • ✅ Cập nhật ở một nơi → thay đổi tự động ở mọi nơi
  • ✅ Giữ cho nội dung của bạn DRY (Don't Repeat Yourself)

Ví dụ thực tế:

Không có Blocks (sao chép-dán):

  • Cập nhật chân trang → Chỉnh sửa 50 trang thủ công ❌
  • Thêm liên kết mạng xã hội → Cập nhật ở mọi nơi ❌
  • Nội dung không nhất quán trên các trang ❌

Với Blocks (có thể tái sử dụng):

  • Cập nhật khối chân trang → Thay đổi trên tất cả 50 trang ngay lập tức ✅
  • Thêm liên kết mạng xã hội → Cập nhật một lần ✅
  • Luôn nhất quán ✅

✨ Khái niệm chính​

Khối là gì?​

Một khối là một thành phần nội dung tái sử dụng chứa:

  • Nội dung - Văn bản, hình ảnh, liên kết, bất kỳ dữ liệu nào
  • Thuộc tính - Các trường tùy chỉnh bạn định nghĩa
  • Đánh dấu - Định danh duy nhất để tham chiếu
  • Trạng thái - Hoạt động, nháp, đã lưu trữ

Khả năng tái sử dụng của khối​

Các khối có thể:

  • ✅ Được sử dụng trên nhiều trang và nếu các khối được cập nhật, chúng sẽ được cập nhật ở mọi nơi
  • ✅ Được địa phương hóa (nội dung khác nhau theo ngôn ngữ)

📋 Những điều bạn cần biết​

Thực hành tốt nhất: Luôn sử dụng đánh dấu trong mã của bạn (chúng không bao giờ thay đổi).

Cấu trúc khối​

Mỗi khối có các trường chính này:

{
  id: 3, // unique ID
  localizeInfos: { // block localized data
    title: 'Block', // block localized title
  },
  version: 0, // block version
  position: 1, // block position in array of blocks
  identifier: 'block', // block identifier
  type: 'common_block', // block type
  templateIdentifier: null, // template identifier
  isVisible: true, // visibility
  attributeValues: {}, // block attributes
}

Thuộc tính tùy chỉnh​

Các khối sử dụng AttributesSets cho các trường tùy chỉnh:

Ví dụ:

  • Khối chân trang: văn bản bản quyền, liên kết mạng xã hội, thông tin liên hệ
  • Banner hero: tiêu đề, phụ đề, nút CTA, hình ảnh nền
  • Đánh giá: tên tác giả, ảnh, trích dẫn, đánh giá
  • Mẫu liên hệ: cấu hình các trường, văn bản nút gửi

Tìm hiểu thêm: Xem AttributesSets Module

📊 Bảng tham khảo nhanh - Các phương thức phổ biến​

Phương thứcChức năngKhi nào sử dụng
getBlocks()Lấy tất cả các khối (phân trang, lọc)Liệt kê tất cả các khối có sẵn
getBlockByMarker()Lấy khối theo đánh dấuLấy khối cụ thể trong mã
searchBlock()Tìm kiếm các khốiLấy các khối
getFrequentlyOrderedProducts()Sản phẩm thường xuyên được đặt hàng"Thường được đặt cùng nhau"
getCartComplement()"Hoàn thành giỏ hàng của bạn" theo ngữ cảnh giỏ hàngBán chéo từ giỏ hàng
getCartComplementByProductIds()"Hoàn thành giỏ hàng của bạn" theo productIdsBán chéo cho các sản phẩm đã cho
getCartSimilar()"Tương tự như giỏ hàng" theo ngữ cảnh giỏ hàngCác lựa chọn thay thế cho các mặt hàng trong giỏ hàng
getCartSimilarByProductIds()"Tương tự như giỏ hàng" theo productIdsCác lựa chọn thay thế cho các sản phẩm đã cho
getWishlistSimilar()"Tương tự như danh sách mong muốn" theo danh sách mong muốnCác lựa chọn thay thế cho các mặt hàng trong danh sách mong muốn
getWishlistSimilarByProductIds()"Tương tự như danh sách mong muốn" theo productIdsCác lựa chọn thay thế cho các sản phẩm đã cho
getPersonalRecommendations()Đề xuất cá nhânDòng sản phẩm cá nhân hóa
getRecentlyViewed()Sản phẩm đã xem gần đâyWidget "Đã xem gần đây"
getRepeatPurchase()Sản phẩm cho lần mua lạiWidget "Mua lại"
getTrending()Sản phẩm đang thịnh hànhWidget "Thịnh hành ngay bây giờ"
getSlides()Cây slide của khối sliderHiển thị một slider/carousel

🧩 Các loại khối​

type của một khối (cái gọi là BlockType) xác định những gì nó hiển thị. Ngoài các loại cơ bản (common_block, product_block, similar_products_block, form, và các loại khác), các loại khối sản phẩm & cá nhân hóa sau đây có sẵn:

Loại khốiPhương thức
frequently_ordered_blockgetFrequentlyOrderedProducts()
trending_blockgetTrending()
recently_viewed_blockgetRecentlyViewed()
repeat_purchase_blockgetRepeatPurchase()
slider_blockgetSlides()
personal_recommendations_blockgetPersonalRecommendations()
cart_complement_blockgetCartComplement() / getCartComplementByProductIds()
cart_similar_blockgetCartSimilar() / getCartSimilarByProductIds()
wishlist_similar_blockgetWishlistSimilar() / getWishlistSimilarByProductIds()

Các khối cá nhân hóa (đã xem gần đây, mua lại, đề xuất cá nhân, giỏ hàng/danh sách mong muốn) được điều khiển bởi hoạt động của người dùng và hoạt động cho cả người dùng đã xác thực và khách (xem Chế độ khách).

❓ Câu hỏi thường gặp (FAQ)​

Sự khác biệt giữa Blocks và Pages là gì?​

  • Pages/Product Pages - Các trang hoàn toàn tự chứa với URL (ví dụ: /about) mà bạn có thể thêm các khối và các thành phần trang khác có thể được tái sử dụng trên nhiều trang.
  • Blocks - Các thành phần tái sử dụng được chèn vào các trang (ví dụ, chân trang)

Hãy nghĩ về nó như:

  • Trang = Tài liệu đầy đủ
  • Khối = Đoạn văn bạn tái sử dụng trong nhiều tài liệu

Làm thế nào để tôi cập nhật nội dung của một khối?​

Cập nhật nó trong OneEntry bảng điều khiển quản trị:

  1. Đi đến phần Blocks
  2. Tìm khối của bạn (ví dụ, "Chân trang")
  3. Chỉnh sửa thuộc tính
  4. Lưu

Tất cả các trang sử dụng khối đó sẽ tự động cập nhật! ✨

Tôi có nên tạo nhiều khối nhỏ hay ít khối lớn?​

Nhiều khối nhỏ là tốt hơn:

✅ Tốt (nhỏ, tập trung):

- header_logo
- header_navigation
- footer_copyright
- footer_social_links

❌ Tránh (quá lớn):

- entire_page_layout (contains everything)

Tại sao? Các khối nhỏ dễ tái sử dụng và bảo trì hơn.

Làm thế nào để tôi hiển thị/ẩn các khối một cách có điều kiện?​

Kiểm tra trường isVisible

Tôi có thể tạo khối một cách động qua API không?​

SDK chỉ đọc. Để tạo khối, hãy sử dụng bảng điều khiển quản trị OneEntry.

Làm thế nào để tôi xử lý các khối bị thiếu một cách nhẹ nhàng?​

Luôn sử dụng try/catch

💡 Lưu ý quan trọng​

Thực hành tốt nhất về Đánh dấu Khối​

✅ Tên đánh dấu tốt:

  • Mô tả: global_footer, homepage_hero
  • Sử dụng dấu gạch dưới: contact_form
  • Chữ thường: promo_banner
  • Chỉ định phạm vi: global_header so với blog_header

❌ Tên đánh dấu xấu:

  • Chung chung: block1, content
  • Khoảng trắng: my block
  • Trộn lẫn chữ hoa chữ thường: MyBlock, ProMoBanner

Bộ nhớ đệm các khối​

Các khối thay đổi hiếm khi → hãy lưu chúng vào bộ nhớ đệm!

🎓 Thực hành tốt nhất​

  • Tạo các khối nhỏ, tập trung (trách nhiệm đơn lẻ)
  • Sử dụng các đánh dấu mô tả (footer, không phải block1)
  • Lưu các khối vào bộ nhớ đệm để giảm số lần gọi API
  • Xử lý các khối bị thiếu một cách nhẹ nhàng (try/catch)
  • Tài liệu hóa mục đích của từng khối
  • Giữ cấu trúc khối nhất quán
  • Kiểm tra các thay đổi khối trước khi xuất bản
  • Sử dụng statusId để xem trước các thay đổi

Định nghĩa của mô-đun Blocks​


const { Blocks } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Tài liệu liên quan​