Giới thiệu

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

🎯 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 dữ liệu đã gửi để phân tích, báo cáo và quản lý.

Hãy nghĩ về 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.

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

Hãy tưởng tượng bạn có một biểu mẫu liên hệ trên trang web của mình. Khi người dùng điền vào:

Gửi - Người dùng nhấp vào "Gửi" → Dữ liệu biểu mẫu được gửi đến OneEntry
Lưu trữ - OneEntry lưu lại việc gửi (tên, email, tin nhắn)
Lấy - Bạn lấy các bản gửi để xem, xuất khẩu, hoặc phân tích
Quản lý - Lọc, tìm kiếm, và tổ chức phản hồi từ biểu mẫu

Quy trình làm việc thực tế:

User fills contact form
↓
postFormsData() → Saved in OneEntry
↓
getFormsDataByMarker() → OneEntry returns data
↓
Admin views submissions 

Những gì bạn có thể làm:

📤 Gửi biểu mẫu - Gửi dữ liệu do người dùng điền đến OneEntry
📥 Xem các bản gửi - Nhận tất cả phản hồi từ biểu mẫu với phân trang
🔍 Tìm kiếm các bản gửi - Tìm các bản gửi cụ thể theo dấu hiệu hoặc bộ lọc
📊 Xuất dữ liệu - Lấy các bản gửi cho báo cáo và phân tích
📧 Quản lý phản hồi - Theo dõi các bản gửi biểu mẫu ở một nơi

Các tình huống ví dụ:

Tình huống	Điều gì xảy ra
Biểu mẫu liên hệ	Người dùng gửi → Bạn nhận thông báo qua email → Xem trên bảng điều khiển
Khảo sát	Thu thập phản hồi → Xuất sang CSV → Phân tích kết quả
Đăng ký	Người dùng đăng ký → Dữ liệu được lưu trữ → Gửi email xác nhận
Phản hồi	Khách hàng để lại phản hồi → Nhóm xem xét → Phản hồi lại khách hàng

✨ 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 các biểu mẫu.

Cấu trúc gửi biểu mẫu

Mỗi bản gửi trong OneEntry có:

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

Vòng đời dữ liệu biểu mẫu

1. User fills form in browser
   ↓
2. Frontend validates input
   ↓
3. postFormsData() sends to OneEntry
   ↓
4. OneEntry validates & stores form data submission
   ↓
5. Notifications sent (email, webhook)
   ↓
6. Admin retrieves with getFormsDataByMarker()
   ↓
7. Review, export, or respond

Các trường hợp sử dụng phổ biến

Trường hợp sử dụng	Mô tả	Ví dụ
Biểu mẫu liên hệ	Khách hàng liên hệ với câu hỏi	Nhóm hỗ trợ xem xét và phản hồi
Tạo khách hàng tiềm năng	Thu thập thông tin khách hàng tiềm năng	Nhóm bán hàng theo dõi
Khảo sát	Thu thập phản hồi và ý kiến	Nhóm marketing phân tích kết quả
Đăng ký	Đăng ký tham gia sự kiện, bản tin	Theo dõi người tham dự/đăng ký
Đơn xin việc	Thu thập hồ sơ và thư xin việc	Nhóm nhân sự xem xét ứng viên
Biểu mẫu phản hồi	Đánh giá sự hài lòng của khách hàng	Cải thiện sản phẩm/dịch vụ

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

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

Trước khi gửi, bạn cần:

Dấu hiệu biểu mẫu - Định danh văn bản biểu mẫu duy nhất
ID cấu hình mô-đun biểu mẫu - Từ cài đặt biểu mẫu
Định danh thực thể mô-đun - Từ cấu hình biểu mẫu

Cách lấy những điều này:

// Fetch form
const form = await Forms.getFormByMarker('contact_form');

// Extract required IDs
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Now you can submit

Tại sao cần? OneEntry cần biết:

Mẫu biểu nào để sử dụng
Nơi lưu trữ dữ liệu
Quy tắc xác thực nào cần áp dụng

Cấu trúc dữ liệu biểu mẫu

Mảng formData chứa các đối tượng trường:

formData: [
  {
    marker: "field_name", // Field identifier
    type: "text"          // Field type
    value: "user_input",  // User's input
  }
]

Quan trọng:

marker phải khớp với các dấu hiệu trường từ định nghĩa biểu mẫu
type hữu ích cho việc xác thực
value chứa đầu vào của người dùng

Trạng thái gửi

Sử dụng status để theo dõi trạng thái gửi:

Trạng thái	Ý nghĩa	Khi nào sử dụng
`"sent"`	Đã gửi thành công	Mặc định cho các bản gửi mới
`"pending"`	Đang chờ xem xét	Cần kiểm duyệt
`"processed"`	Đã được quản trị viên xử lý	Được đánh dấu là đã xem xét
`"archived"`	Bản gửi cũ/đã đóng	Giữ lại để lưu trữ

Phân trang

Lấy các bản gửi theo lô.

Dấu hiệu biểu mẫu

Một cách để xác định các bản gửi:

Định danh	Nó là gì	Khi nào sử dụng
Dấu hiệu biểu mẫu	Định danh mẫu biểu mẫu	Lấy tất cả các bản gửi cho một biểu mẫu cụ thể

📊 Bảng tham khảo nhanh

Phương thức	Mô tả	Trường hợp sử dụng
postFormsData()	Gửi dữ liệu biểu mẫu mới	Người dùng gửi biểu mẫu liên hệ
getFormsDataByMarker()	Lấy các bản gửi cho biểu mẫu cụ thể	Xem tất cả các bản gửi biểu mẫu liên hệ

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

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

Bạn cần ba điều:

Cấu hình biểu mẫu từ Forms.getFormByMarker()
Dữ liệu đầu vào của người dùng
Gọi FormData.postFormsData()

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

Không trực tiếp. Các bản gửi biểu mẫu thường không thay đổi để duy trì tính toàn vẹn của dữ liệu.

Giải pháp thay thế:

Gửi một phiên bản mới với dữ liệu đã cập nhật
Sử dụng trường status để đánh dấu các bản gửi cũ là lỗi thời
Triển khai logic cập nhật tùy chỉnh trong frontend của bạn

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

Chỉ cần sử dụng File hoặc FileList với FormData.postFormsData() hoặc Tải tệp riêng biệt bằng mô-đun FileUploading, sau đó bao gồm URL tệp trong dữ liệu biểu mẫu.

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

Sử dụng các tham số body dateFrom và dateTo.

Tôi có thể tìm kiếm các bản gửi theo giá trị trường không?

Có, lấy các bản gửi và tìm kiếm ở phía khách hàng.

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

Sử dụng offset và limit.

Làm thế nào để tôi xử lý các lỗi xác thực?

Sử dụng try/catch và kiểm tra thông báo lỗi.

💡 Ghi chú quan trọng

⚠️ Cấu hình biểu mẫu là bắt buộc

Bạn không thể gửi biểu mẫu mà không có cấu hình:

formModuleConfigId và moduleEntityIdentifier là bắt buộc
Lấy những điều này từ Forms.getFormByMarker() trước khi gửi
Lưu trữ chúng trong ứng dụng của bạn để tránh gọi API lặp lại

🔒 Cân nhắc về bảo mật

Không bao giờ tiết lộ dữ liệu nhạy cảm:

Đừng gửi mật khẩu dưới dạng văn bản thuần túy
Xác thực đầu vào cả ở phía khách hàng và máy chủ
Làm sạch đầu vào của người dùng trước khi hiển thị

📦 Tập dữ liệu lớn

Phân trang là quan trọng:

Đừng lấy hàng ngàn bản gửi cùng một lúc
Sử dụng limit và offset cho phân trang
Cân nhắc việc lưu cache cho dữ liệu thường xuyên được truy cập

🔄 Chỉ đọc sau khi gửi

Dữ liệu biểu mẫu là không thay đổi:

Không thể cập nhật các bản gửi qua SDK
Gửi phiên bản mới nếu cần thay đổi
Sử dụng trường status để theo dõi trạng thái gửi

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

Lưu cache cấu hình biểu mẫu - Tránh việc lấy dữ liệu mỗi lần gửi
Xác thực trước khi gửi - Kiểm tra các trường bắt buộc ở phía khách hàng
Sử dụng phân trang - Lấy các bản gửi theo lô
Xử lý lỗi một cách nhẹ nhàng - Luôn sử dụng try/catch
Sử dụng các dấu hiệu một cách nhất quán - Tham chiếu các biểu mẫu theo dấu hiệu, không phải ID
Theo dõi trạng thái gửi - Sử dụng trường trạng thái để tổ chức các bản gửi
Xuất dữ liệu thường xuyên - Sao lưu các bản gửi vào CSV/cơ sở dữ liệu
Giám sát các bản gửi mới - Triển khai polling hoặc webhooks

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


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

Cài đặt biểu mẫu:

Lấy biểu mẫu theo dấu hiệu bằng cách sử dụng Forms.getFormByMarker('your-form-marker').
Sử dụng trường moduleFormConfigs từ biểu mẫu đã lấy cho cấu hình được sử dụng khi gửi dữ liệu biểu mẫu.
Tạo body bằng cách sử dụng moduleFormConfig và gửi dữ liệu biểu mẫu.


const formModuleConfigId = moduleFormConfigs[0].id;
const moduleEntityIdentifier = moduleFormConfigs[0].entityIdentifiers[0].id;

const body = {
  "formIdentifier": "your-form-marker",
  "formModuleConfigId": formModuleConfigId,
  "moduleEntityIdentifier": moduleEntityIdentifier,
  "replayTo": null,
  "status": "sent",
  "formData": [...]
};

const response = await FormData.postFormsData(body);

🔗 Tài liệu liên quan

Mô-đun Biểu mẫu - Tạo và quản lý cấu trúc biểu mẫu
Mô-đun Tải tệp - Xử lý việc tải tệp trong các biểu mẫu
Mô-đun Sự kiện - Thiết lập thông báo dựa trên sự kiện
Mô-đun Người dùng - Quản lý người dùng gửi biểu mẫu

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

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

✨ Khái niệm chính​

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

Cấu trúc gửi biểu mẫu​

Vòng đời dữ liệu biểu mẫu​

Các trường hợp sử dụng phổ biến​

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

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

Cấu trúc dữ liệu biểu mẫu​

Trạng thái gửi​

Phân trang​

Dấu hiệu biểu mẫu​

📊 Bảng tham khảo nhanh​

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

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

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

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

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

Tôi có thể tìm kiếm các bản gửi theo giá trị trường không?​

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

Làm thế nào để tôi xử lý các lỗi xác thực?​

💡 Ghi chú quan trọng​

⚠️ Cấu hình biểu mẫu là bắt buộc​

🔒 Cân nhắc về bảo mật​

📦 Tập dữ liệu lớn​

🔄 Chỉ đọc sau khi gửi​

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

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

Cài đặt biểu mẫu:​

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