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

Giới thiệu

Lấy các biểu mẫu động với việc gửi và thu thập dữ liệu theo thời gian thực.

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

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

Mô-đun Forms cho phép bạn lấy các biểu mẫu - biểu mẫu liên hệ, khảo sát, đăng ký, biểu mẫu phản hồi - để bạn có thể hiển thị chúng trong ứng dụng của mình. Bạn xây dựng các biểu mẫu trong bảng điều khiển quản trị OneEntry; SDK sẽ lấy cấu trúc của chúng (các trường, bộ xác thực, nhãn địa phương hóa) một cách động. Việc thu thập các phản hồi thực tế được xử lý bởi mô-đun FormsData.

🚀 Bắt đầu nhanh​

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


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

Lấy một biểu mẫu duy nhất theo dấu hiệu của nó và đọc các trường của nó:

// Fetch the "contact_form" form structure.
const form = await Forms.getFormByMarker("contact_form", "en_US");

console.log(form.identifier, form.localizeInfos.title);

// Render each field from the form's attributes.
form.attributes.forEach((field) => {
  console.log(field.marker, field.type, field.localizeInfos.title);
});

Để liệt kê mọi biểu mẫu (phân trang), sử dụng getAllForms(langCode, offset, limit), trả về một đối tượng { total, items }.

✨ Khái niệm chính​

Biểu mẫu là gì?​

Một biểu mẫu (IFormsEntity) là một cách có cấu trúc để thu thập thông tin từ người dùng:

  • Các trường (attributes) - các phần tử đầu vào, mỗi phần tử là một thuộc tính với một type (string, text, file, list, …)
  • Bộ xác thực (validators) - các quy tắc theo trường (bắt buộc, độ dài chuỗi, định dạng email)
  • Cấu trúc - bố cục và nhãn địa phương hóa được định nghĩa trong bảng điều khiển quản trị OneEntry
  • Phản hồi - các phản hồi của người dùng, được gửi và lấy qua mô-đun FormsData

Các loại trường biểu mẫu​

Mỗi trường có type là một AttributeType. Các giá trị phổ biến:

Loại (AttributeType)Mô tảVí dụ sử dụng
stringVăn bản ngắn một dòngTên, Tiêu đề, Thành phố
text / textWithHeaderVăn bản nhiều dòngTin nhắn, Bình luận, Tiểu sử
integer / real / floatĐầu vào sốTuổi, Số lượng, Giá cả
date / dateTime / timeBộ chọn ngày & giờNgày sinh, Ngày sự kiện
listDropdown / chọn nhiều từ các tùy chọnQuốc gia, Danh mục
radioButtonLựa chọn đơn từ các tùy chọnKích thước, Kế hoạch
file / imageTải lên tệp / hình ảnhSơ yếu lý lịch, Ảnh, Tài liệu
groupOfImagesNhiều hình ảnhThư viện
entityTham chiếu đến một thực thể khácSản phẩm hoặc trang liên kết

Lưu ý: Email là một trường string với emailInspectionValidator được kích hoạt — không có loại trường email riêng biệt.

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

Cấu trúc biểu mẫu​

Mỗi biểu mẫu (IFormsEntity) mang một id, một identifier (dấu hiệu), một type tùy chọn ('order' | 'sing_in_up' | 'collection' | 'data' | 'rating' | null), localizeInfos (tiêu đề, thông điệp thành công, …) và một mảng attributes của các trường. Mỗi trường có một marker, type, localizeInfos, và một đối tượng validators:

{
  "marker": "email",
  "type": "string",
  "localizeInfos": { "title": "Email" },
  "validators": {
    "requiredValidator": { "strict": true },
    "emailInspectionValidator": true,
    "stringInspectionValidator": { "stringMin": 5, "stringMax": 100, "stringLength": 0 }
  }
}

Các bộ xác thực phổ biến:

  • requiredValidator — { strict: boolean }, trường phải được điền
  • stringInspectionValidator — { stringMin, stringMax, stringLength }, ràng buộc độ dài văn bản
  • emailInspectionValidator — boolean, bắt buộc định dạng email
  • defaultValueValidator — giá trị mặc định cộng với văn bản lỗi tùy chọn

Bộ xác thực có thể mở rộng — các loại bộ xác thực bổ sung có thể được trả về bởi API.

Các biểu mẫu được tạo trong bảng điều khiển quản trị​

SDK được sử dụng để lấy các biểu mẫu (và, thông qua mô-đun FormsData, gửi dữ liệu) — không phải để tạo hoặc chỉnh sửa các biểu mẫu. Để xây dựng hoặc thay đổi một biểu mẫu, hãy sử dụng bảng điều khiển quản trị OneEntry: mở phần Biểu mẫu, thêm các trường, cấu hình các quy tắc xác thực và kích hoạt biểu mẫu.

📊 Bảng tham khảo nhanh - Phương thức​

Phương thứcChức năngKhi nào sử dụng
getAllForms()Lấy tất cả các biểu mẫu (phân trang)Liệt kê tất cả các biểu mẫu có sẵn
getFormByMarker()Lấy biểu mẫu theo dấu hiệuLấy biểu mẫu cụ thể trong mã

Cả hai phương thức đều công khai — không yêu cầu xác thực người dùng.

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

Làm thế nào để tôi tạo hoặc chỉnh sửa các biểu mẫu?​

Các biểu mẫu được tạo và chỉnh sửa trong bảng điều khiển quản trị OneEntry (phần Biểu mẫu), không qua SDK. SDK chỉ lấy cấu trúc biểu mẫu và gửi dữ liệu.

Tôi có thể tải lên tệp với các biểu mẫu không?​

Có. Thêm một trường file / image / groupOfImages vào biểu mẫu của bạn; các phản hồi có tệp được xử lý bởi FormData.postFormsData(), tự động tải chúng qua mô-đun FileUploading. Xem mô-đun FormsData.

Các biểu mẫu có thể có các trường điều kiện (hiện/ẩn dựa trên các trường khác) không?​

Không trực tiếp trong SDK — thực hiện logic hiển thị/ẩn trong giao diện người dùng của riêng bạn dựa trên các giá trị trường của biểu mẫu đã lấy.

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

  • Tham chiếu các biểu mẫu theo identifier (dấu hiệu) của chúng, không phải theo ID số.
  • Hiển thị các trường và trạng thái yêu cầu từ validators của mỗi trường để giao diện người dùng của bạn khớp với xác thực phía máy chủ.
  • Sử dụng try/catch xung quanh các lần lấy và xử lý hình dạng trả về IError.

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