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

Giới thiệu

Xử lý việc gửi biểu mẫu và lấy dữ liệu biểu mẫu.

Thông tin thêm về các biểu mẫu trong bảng điều khiển quản trị OneEntry: https://doc.oneentry.cloud/docs/category/forms

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

Mô-đun FormData cho phép bạn gửi các biểu mẫu do người dùng điền (biểu mẫu liên hệ, khảo sát, đăng ký) đến OneEntry và lấy, cập nhật hoặc xóa dữ liệu đã gửi để phân tích, báo cáo và quản lý.

Hãy coi nó như là trình quản lý gửi biểu mẫu của bạn - người dùng gửi biểu mẫu, bạn lưu trữ chúng trong OneEntry, và lấy chúng bất cứ khi nào bạn cần xem phản hồi, tạo báo cáo hoặc phân tích dữ liệu.

🚀 Bắt đầu nhanh​

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


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

Xây dựng nội dung từ cấu hình của biểu mẫu và gửi nó:

// 1. Fetch the form to read its module config.
const form = await Forms.getFormByMarker("contact_form");
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// 2. Submit the user's input.
const response = await FormData.postFormsData({
  formIdentifier: "contact_form",
  formModuleConfigId,
  moduleEntityIdentifier,
  replayTo: null,
  status: "sent",
  formData: [
    { marker: "name", type: "string", value: "Jack" },
  ],
});

console.log(response);

Để đọc các lần gửi sau này, gọi getFormsDataByMarker(marker, formModuleConfigId, body?, isExtended?, langCode?, offset?, limit?).

✨ Khái niệm chính​

Dữ liệu biểu mẫu là gì?​

Dữ liệu biểu mẫu là thông tin mà người dùng gửi qua một biểu mẫu. Mỗi lần gửi được xây dựng từ một mảng formData của các đối tượng trường (marker, type, value) cộng với các định danh cấu hình của biểu mẫu.

Cấu trúc nội dung gửi​

postFormsData chấp nhận một IBodyPostFormData:

const body = {
  formIdentifier: 'contact_form', // Form marker
  formModuleConfigId: 9,          // Module config ID (from the form)
  moduleEntityIdentifier: 'blog', // Module entity identifier (from the form)
  replayTo: null,                 // Email address to reply to (optional)
  status: 'sent',                 // Submission status (optional)
  formData: [                     // Form fields
    { marker: 'name', type: 'string', value: 'Test' },
  ],
};

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

Gửi yêu cầu cấu hình của biểu mẫu​

Trước khi gửi, bạn cần ba giá trị, tất cả đều được đọc từ chính biểu mẫu:

  1. Định danh biểu mẫu (formIdentifier) — định danh văn bản của biểu mẫu
  2. formModuleConfigId — từ moduleFormConfigs của biểu mẫu
  3. moduleEntityIdentifier — từ moduleFormConfigs của biểu mẫu
const form = await Forms.getFormByMarker('contact_form');
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

Lưu trữ các giá trị này để bạn không phải lấy lại biểu mẫu trong mỗi lần gửi.

Các trường formData​

Mỗi mục trong mảng formData mô tả một trường:

  • marker — phải khớp với một trường marker từ định nghĩa biểu mẫu
  • type — loại trường (được sử dụng cho xác thực và xử lý tệp)
  • value — đầu vào của người dùng

Các trường loại file / image / groupOfImages được tải lên tự động thông qua mô-đun FileUploading khi bạn truyền một File/FileList/Blob làm value.

Trạng thái gửi​

Sử dụng trường status để theo dõi trạng thái gửi. "sent" là giá trị điển hình cho các lần gửi mới; bạn có thể sau đó chuyển một lần gửi sang trạng thái đã được xem/xóa với updateFormsDataStatusByid().

Cập nhật và xóa các lần gửi​

Các lần gửi không phải là bất biến. Người dùng đã xác thực có thể thay đổi hoặc xóa chúng:

  • updateFormsDataByid(id, body) — chỉnh sửa một lần gửi đã lưu theo id 🔐
  • updateFormsDataStatusByid(id, body) — chỉ thay đổi trạng thái của một lần gửi theo id 🔐
  • deleteFormsDataByid(id) — xóa một lần gửi theo id 🔐

Đọc các lần gửi​

getFormsDataByMarker trả về các lần gửi cho một biểu mẫu. Phân trang qua kết quả với offset / limit, và thu hẹp với body yêu cầu (ví dụ: status, dateFrom, dateTo, userIdentifier).

Tìm kiếm các lần gửi theo nghĩa​

getFormsDataByVectorSearch(body, langCode, offset, limit) thực hiện một tìm kiếm ngữ nghĩa (vector) trên các lần gửi: bạn truyền một queryText bằng ngôn ngữ tự nhiên và nhận lại các bản ghi phù hợp với nó về nghĩa, không phải theo từ khóa.

Các bản ghi của nó sử dụng một loại khác với phần còn lại của mô-đun - IFormDataSearchEntity thay vì IFormDataEntity. Cả hai đều mang id, formIdentifier, time và formData, nhưng thực thể tìm kiếm còn tiết lộ thêm các trường kiểm duyệt và người gửi của bản ghi gốc:

TrườngLoạiÝ nghĩa
status'sent' | 'banned' | 'deleted' | 'moderation' | 'approved'Trạng thái kiểm duyệt của bản ghi
ipstringĐịa chỉ IP mà biểu mẫu được gửi từ đó
fingerprintstringDấu vân tay thiết bị của người gửi
isUserAdminbooleanLiệu một quản trị viên đã gửi bản ghi
userIdentifierstringAi đã gửi biểu mẫu
entityIdentifierstringThực thể mà bản ghi thuộc về
parentIdnumberBản ghi dữ liệu biểu mẫu cha

📊 Bảng tham khảo nhanh​

Phương thứcMô tảTrường hợp sử dụng
postFormsData()Gửi dữ liệu biểu mẫu mớiNgười dùng gửi biểu mẫu liên hệ
getFormsDataByMarker()Lấy các lần gửi cho biểu mẫu cụ thểXem tất cả các lần gửi biểu mẫu liên hệ
updateFormsDataByid() 🔐Cập nhật một lần gửi biểu mẫu theo idChỉnh sửa một lần gửi đã lưu
updateFormsDataStatusByid() 🔐Cập nhật trạng thái của một lần gửi theo idĐánh dấu là đã xử lý/xóa
deleteFormsDataByid() 🔐Xóa một lần gửi biểu mẫu theo idXóa một lần gửi
getFormsDataByVectorSearch()Tìm kiếm ngữ nghĩa (vector) cho dữ liệu biểu mẫuTìm các lần gửi theo nghĩa, không phải từ khóa

🔐 các phương thức yêu cầu xác thực người dùng — xem AuthProvider. postFormsData() và getFormsDataByMarker() là công khai.

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

Làm thế nào để tôi gửi một biểu mẫu?​

Lấy biểu mẫu với Forms.getFormByMarker(), đọc formModuleConfigId và moduleEntityIdentifier từ moduleFormConfigs của nó, xây dựng nội dung, sau đó gọi FormData.postFormsData(body). Xem phần Bắt đầu nhanh ở trên.

Tôi có thể cập nhật hoặc xóa dữ liệu biểu mẫu đã gửi không?​

Có. Các lần gửi có thể được thay đổi hoặc xóa thông qua SDK (các thao tác này yêu cầu xác thực người dùng):

  • updateFormsDataByid() — chỉnh sửa một lần gửi đã lưu theo id
  • updateFormsDataStatusByid() — chỉ thay đổi trạng thái của một lần gửi theo id
  • deleteFormsDataByid() — xóa một lần gửi theo id

Làm thế nào để tôi xử lý việc tải lên tệp trong các biểu mẫu?​

Truyền một File / FileList / Blob làm value của trường và postFormsData() sẽ tải lên cho bạn, hoặc tải lên riêng biệt với mô-đun FileUploading và bao gồm các URL đã trả về trong formData.

Làm thế nào để tôi lọc các lần gửi theo ngày?​

Truyền dateFrom và dateTo trong body yêu cầu của getFormsDataByMarker().

Làm thế nào để tôi phân trang qua tất cả các lần gửi?​

Sử dụng các tham số offset và limit của getFormsDataByMarker().

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

  • Lưu trữ cấu hình của biểu mẫu (formModuleConfigId, moduleEntityIdentifier) để tránh việc lấy lại biểu mẫu trong mỗi lần gửi.
  • Xác thực các trường bắt buộc ở phía client trước khi gửi; OneEntry cũng xác thực ở phía server.
  • Phân trang các lần đọc với offset / limit thay vì lấy tất cả cùng một lúc.
  • Tham chiếu các biểu mẫu bằng marker, không phải bằng ID số.
  • Sử dụng trường status (và updateFormsDataStatusByid) để tổ chức các lần gửi.
  • Xử lý lỗi với try/catch và kiểm tra hình dạng trả về của IError.

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