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 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.

---

📖 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 bạn. Khi người dùng điền vào:

1. Gửi - Người dùng nhấp "Gửi" → Dữ liệu biểu mẫu được gửi đến OneEntry
2. Lưu - OneEntry lưu trữ việc gửi (tên, email, tin nhắn)
3. Lấy - Bạn lấy các bản gửi để xem, xuất khẩu, hoặc phân tích
4. 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ế:

Người dùng điền biểu mẫu liên hệ → postFormsData() → Lưu trong OneEntry
                                                              ↓
Quản trị viên xem các bản gửi ← getFormsData() ← OneEntry trả về dữ liệu

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 kịch bản ví dụ:

Kịch bản	Đ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 trong 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 cho khách hàng

---

✨ Các 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', // Dấu hiệu biểu mẫu
    formModuleConfigId: 9,          // ID cấu hình mô-đun
    moduleEntityIdentifier: 'blog', // Dấu hiệu thực thể mô-đun
    replayTo: null,                 // Địa chỉ email để trả lời
    status: 'sent',                 // Trạng thái gửi
    formData: [                     // Các trường biểu mẫu
      {
        marker: 'string',           // Dấu hiệu trường
        type: 'string',             // Loại trường
        value: 'Test',              // Giá trị trường
      },
      {
        marker: 'number',
        type: 'integer',
        value: 1,
      },
    ]
  };

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

1. Người dùng điền biểu mẫu trong trình duyệt
   ↓
2. Frontend xác thực đầu vào
   ↓
3. postFormsData() gửi đến OneEntry
   ↓
4. OneEntry xác thực & lưu trữ bản gửi
   ↓
5. Thông báo được gửi (email, webhook)
   ↓
6. Quản trị viên lấy dữ liệu với getFormsData()
   ↓
7. Xem xét, xuất khẩu, hoặc phản hồi

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	Bộ phận marketing phân tích kết quả
Đăng ký	Đăng ký cho các 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	Bộ phận 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:

1. Dấu hiệu biểu mẫu - Dấu hiệu duy nhất của biểu mẫu
2. ID cấu hình mô-đun biểu mẫu - Từ cài đặt biểu mẫu
3. Dấu hiệu thực thể mô-đun - Từ cấu hình biểu mẫu

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

// Lấy biểu mẫu
const form = await Forms.getFormByMarker('contact_form');

// Trích xuất các ID cần thiết
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Bây giờ bạn có thể gửi

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 để á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",     // Dấu hiệu trường
    type: "text"              // Loại trường
    value: "user_input",      // Đầu vào của người dùng
  }
]

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:

Dấu hiệu	Nó là gì	Khi nào sử dụng
Dấu hiệu biểu mẫu	Dấu hiệu mẫu biể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ệ
getFormsData()	Lấy tất cả các bản gửi (có phân trang)	Bảng điều khiển quản trị viên hiển thị tất cả các biểu mẫu
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:

1. Cấu hình biểu mẫu từ Forms.getFormByMarker()
2. Dữ liệu đầu vào của người dùng
3. 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à không còn hiệu lực
• Triển khai logic cập nhật tùy chỉnh trong backend 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?

Tải tệp riêng biệt bằng cách sử dụng mô-đun FileUploading, sau đó bao gồm các 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?

Lấy tất cả các bản gửi và lọc ở phía khách hàng

---

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

---

Sự khác biệt giữa getFormsData() và getFormsDataByMarker() là gì?

Phương thức	Nó trả về gì	Khi nào sử dụng
getFormsData()	Tất cả các bản gửi từ tất cả các biểu mẫu	Bảng điều khiển quản trị viên hiển thị mọi thứ
getFormsDataByMarker()	Các bản gửi cho một biểu mẫu cụ thể	Chỉ xem các bản gửi biểu mẫu liên hệ

---

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:

1. Lấy biểu mẫu theo dấu hiệu bằng cách sử dụng Forms.getFormByMarker('your-form-marker').
2. 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.
3. 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ý 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

---