Chuyển đến nội dung chính

Giới thiệu

Quản lý các trang web và màn hình ứng dụng di động với nội dung động.

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

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

Mô-đun Pages cho phép bạn lấy và quản lý các trang (cho các trang web) hoặc màn hình (cho các ứng dụng di động) với tất cả nội dung của chúng - tiêu đề, nội dung HTML/thông thường, khả năng hiển thị và các thuộc tính tùy chỉnh. Bạn tạo các trang trong bảng điều khiển quản trị OneEntry và lấy chúng một cách động trong ứng dụng của bạn, vì vậy việc thay đổi nội dung trong quản trị sẽ có hiệu lực ngay mà không cần triển khai lại.

🚀 Bắt đầu nhanh​

Khởi tạo mô-đun từ defineOneEntry:


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

Lấy một trang đơn lẻ theo URL (đánh dấu) của nó và đọc các trường của nó:

// Fetch the "about" page in English.
const page = await Pages.getPageByUrl("about", "en_US");

console.log(page.id, page.localizeInfos.title);
console.log("Visible:", page.isVisible);

// Custom fields you defined live in attributeValues.
console.log(page.attributeValues);

Hầu hết các phương thức đọc đều có hình dạng tương tự: một định danh (url hoặc id) cộng với một langCode. Xem Bảng Tham Chiếu Nhanh bên dưới để biết đầy đủ.

✨ Khái niệm chính​

Trang là gì?​

Một trang là một thực thể nội dung đại diện cho:

  • Web: Một trang trên trang web của bạn (ví dụ: /about, /contact)
  • Di động: Một màn hình trong ứng dụng của bạn (ví dụ: Màn hình Hồ sơ, Màn hình Cài đặt)

Mỗi trang chứa:

  • Nội dung - tiêu đề và nội dung HTML/thông thường thông qua localizeInfos
  • URL - pageUrl, đánh dấu trang được sử dụng cho định tuyến và tra cứu
  • Khả năng hiển thị - cờ isVisible
  • Thuộc tính tùy chỉnh - bất kỳ trường bổ sung nào bạn định nghĩa trong attributeValues (meta SEO được mô hình hóa như các thuộc tính tùy chỉnh, không phải là một trường tích hợp sẵn)
  • Địa phương hóa - nội dung đa ngôn ngữ

Các loại trang​

OneEntry hỗ trợ các loại trang khác nhau (type), phổ biến nhất là:

LoạiGiá trị typeVí dụ Sử Dụng
Trang Thông Thườngcommon_pageGiới thiệu, Liên hệ, Điều khoản
Trang Danh Mụccatalog_pageCác danh mục trong danh mục
Trang Ngoàiexternal_pageLiên kết đến các URL bên ngoài
Trang Lỗierror_pageTrang 404 / Không tìm thấy

Danh sách đầy đủ các loại có sẵn thông qua mô-đun GeneralTypes.

Cấu trúc phân cấp trang​

Các trang được tổ chức trong một cây thông qua parentId (các trang cấp cao nhất có parentId: null):

📁 Company
  ├─ About Us
  ├─ Team
  └─ Careers

📁 Products
  ├─ Product Category 1
  │   ├─ Product A
  │   └─ Product B
  └─ Product Category 2

Bạn có thể lấy các trang gốc với getRootPages() và đi xuống với getChildPagesByParentUrl().

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

Hai cách để xác định các trang​

Phương phápKhi nào sử dụngVí dụ
Theo URLNgười dùng truy cập trang cụ thểgetPageByUrl("about")
Theo IDTham chiếu nội bộgetPageById(123)

Thực tiễn tốt nhất: pageUrl là một đánh dấu ổn định - nó không phải là một đường dẫn định tuyến Next.js. Truyền đánh dấu OneEntry (ví dụ: "about"), không phải /en/about.

Cấu trúc trang​

Mỗi trang có các trường chính sau:

{
  "id": 9,
  "parentId": 8,
  "pageUrl": "blog1",
  "depth": 1,
  "localizeInfos": {
    "title": "Blog 1",
    "menuTitle": "Blog 1",
    "htmlContent": "",
    "plainContent": ""
  },
  "isVisible": true,
  "blocks": [],
  "type": "common_page",
  "templateIdentifier": null,
  "attributeSetIdentifier": null,
  "attributeValues": {},
  "isSync": false
}

Địa phương hóa​

Các trang hỗ trợ nhiều ngôn ngữ - yêu cầu một langCode khác để lấy cùng một trang bằng ngôn ngữ khác.

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

Thêm bất kỳ trường nào vào các trang bằng cách sử dụng AttributesSets - tác giả/ngày/tags bài viết blog, hình ảnh hero trang đích, meta SEO, và nhiều hơn nữa. Đọc chúng từ page.attributeValues. Tìm hiểu thêm: AttributesSets Module.

Khả năng hiển thị​

Sử dụng cờ isVisible để kiểm soát các trang nào được hiển thị cho người dùng - lọc cho isVisible: true trong môi trường sản xuất.

📊 Bảng Tham Chiếu Nhanh - Các Phương Pháp Thông Dụng​

Phương phápChức năngKhi nào sử dụng
getPages()Lấy tất cả các trangXây dựng sitemap, liệt kê tất cả các trang
getRootPages()Lấy tất cả các trang cấp cao (gốc)Xây dựng điều hướng cấp cao
getChildPagesByParentUrl()Lấy các trang con theo URL chaĐi xuống cây của một phần
getBlocksByPageUrl()Lấy các đối tượng PositionBlock cho một trang theo URLHiển thị các khối nội dung trang
getConfigPageByUrl()Lấy cài đặt cho một trang theo URLĐọc cài đặt hiển thị theo trang
getPageById()Lấy một trang đơn lẻ theo IDTham chiếu nội bộ
getPageByUrl()Lấy một trang đơn lẻ theo URLHiển thị một trang trên một đường dẫn
searchPage()Tìm kiếm nhanh các trangTìm kiếm các trang theo tiêu đề

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

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

  • pageUrl - đánh dấu trang được sử dụng cho định tuyến (ví dụ: "about"). Đối với người dùng và ổn định trên các môi trường.
  • id - định danh số. Được sử dụng cho các tham chiếu nội bộ.

Làm thế nào để tôi xây dựng điều hướng từ các trang?​

Sử dụng getRootPages() cho các mục cấp cao và getChildPagesByParentUrl() để đi xuống cây, hoặc sử dụng mô-đun Menus dành riêng cho các cấu trúc điều hướng được quản lý.

Làm thế nào để tôi thêm metadata SEO vào một trang?​

SEO không phải là một trường tích hợp sẵn - mô hình tiêu đề/meta mô tả/v.v. như các thuộc tính tùy chỉnh trong một AttributesSet, sau đó đọc chúng từ page.attributeValues.

🎓 Thực tiễn tốt nhất​

  • Sử dụng pageUrl (đánh dấu) cho định tuyến - không bao giờ mã hóa cứng một đường dẫn định tuyến của framework như URL.
  • Lọc theo isVisible: true cho môi trường sản xuất.
  • Lưu cache các trang để giảm số lần gọi API; xử lý các lỗi 404 (trang không tìm thấy) một cách hợp lý.
  • Đọc dữ liệu tùy chỉnh từ attributeValues thay vì giả định các trường tích hợp sẵn.

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