Hướng dẫn toàn diện API form-create: 15 phương pháp cốt lõi để quản lý biểu mẫu động

Trong kỷ nguyên phát triển web hiện đại, các công cụ tạo biểu mẫu động (Form Generator) đã trở thành yếu tố then chốt giúp tăng cường năng suất phát triển. form-create, một thư viện mạnh mẽ cho phép xây dựng biểu mẫu linh hoạt, có thể tạo ra các giao diện động, thu thập dữ liệu, xác thực và gửi thông tin chỉ thông qua cấu hình JSON. Bài viết này sẽ đi sâu vào 15 phương pháp API cốt lõi của form-create, giúp các nhà phát triển từ cơ bản đến nâng cao có thể làm chủ toàn bộ quy trình vận hành biểu mẫu.

Tổng quan về API và cách thức gọi

Hệ thống API của form-create được chia thành ba nhóm chính: API khởi tạo biểu mẫu, API thao tác dữ liệu và API xử lý sự kiện. Tất cả các phương thức API đều được gọi thông qua đối tượng thể hiện formCreate. Cấu trúc gọi cơ bản như sau:

// Khởi tạo một thể hiện biểu mẫu
const giaoDienForm = formCreate.create(tapLuat, tuyChon);

// Gọi phương thức API
giaoDienForm.tenPhuongThuc(thamSo);

Bảng phân loại API chính

Loại API	Danh sách phương thức
Khởi tạo	`create`, `maker`, `parseJson`
Dữ liệu	`getValue`, `setValue`, `resetFields`, `validate`, `submit`
Quy tắc	`append`, `prepend`, `insert`, `remove`, `updateRule`
Sự kiện	`on`, `off`, `emit`
Tiện ích	`getRule`, `getField`, `setOptions`, `destroy`

API khởi tạo biểu mẫu

1. `create(rule, options)` - Khởi tạo biểu mẫu

Chức năng: Tạo và hiển thị một thể hiện biểu mẫu động, trả về đối tượng API để thao tác với biểu mẫu.

Tham số:

rule {Array} Mảng các quy tắc tạo biểu mẫu (bắt buộc)
options {Object} Các tùy chọn cấu hình biểu mẫu (tùy chọn)

Ví dụ:

const tapLuat = [
  {type: 'input', field: 'tenDangNhap', title: 'Tên Đăng Nhập', value: ''}
];

const tuyChon = {
  el: '#khungForm',
  onSubmit: (duLieuForm) => console.log('Dữ liệu đã gửi:', duLieuForm)
};

// Tạo biểu mẫu
const giaoDienForm = formCreate.create(tapLuat, tuyChon);

2. `maker` - Công cụ xây dựng quy tắc

Chức năng: Cung cấp API chuỗi gọi để xây dựng nhanh các quy tắc biểu mẫu, hỗ trợ tất cả các loại thành phần tích hợp.

Ví dụ:

// Tạo quy tắc cho trường nhập liệu
const quyTacTenSanPham = formCreate.maker.input('Tên sản phẩm', 'productName', 'Bút bi')
  .props({ placeholder: 'Nhập tên sản phẩm', clearable: true })
  .validate([{ required: true, message: 'Vui lòng nhập tên sản phẩm' }]);

// Thêm vào mảng quy tắc biểu mẫu
tapLuat.push(quyTacTenSanPham);

3. `parseJson(jsonRule)` - Phân tích chuỗi JSON thành quy tắc

Chức năng: Chuyển đổi một chuỗi JSON thành đối tượng quy tắc biểu mẫu, hỗ trợ cấu trúc lồng nhau phức tạp.

Ví dụ:

const chuoiJson = '[{"type":"input","field":"maSanPham","title":"Mã sản phẩm"}]';
const quyTac = formCreate.parseJson(chuoiJson);

API thao tác dữ liệu

4. `getValue(field)` - Lấy dữ liệu biểu mẫu

Chức năng: Lấy giá trị của một trường cụ thể hoặc toàn bộ dữ liệu biểu mẫu.

Tham số:

field {String} Tên trường (tùy chọn, nếu không cung cấp sẽ trả về tất cả dữ liệu)

Ví dụ:

// Lấy giá trị của một trường đơn lẻ
const tenNguoiDung = giaoDienForm.getValue('tenDangNhap');

// Lấy toàn bộ dữ liệu biểu mẫu
const duLieuHienTai = giaoDienForm.getValue();
console.log(duLieuHienTai); // {tenDangNhap: 'abc', matKhau: '123'}

5. `setValue(field, value)` - Đặt giá trị cho biểu mẫu

Chức năng: Đặt giá trị động cho một trường cụ thể, hỗ trợ thiết lập hàng loạt.

Tham số:

field {String|Object} Tên trường hoặc đối tượng cặp khóa-giá trị
value {any} Giá trị của trường (bắt buộc khi field là chuỗi)

Ví dụ:

// Thiết lập giá trị cho một trường
giaoDienForm.setValue('tenDangNhap', 'quanTriVien');

// Thiết lập hàng loạt cho nhiều trường
giaoDienForm.setValue({
  tenDangNhap: 'admin123',
  emailLienHe: 'admin@example.com'
});

6. `resetFields()` - Đặt lại biểu mẫu

Chức năng: Đặt lại tất cả các trường trong biểu mẫu về giá trị ban đầu và xóa trạng thái xác thực.

Ví dụ:

// Gắn sự kiện cho nút đặt lại
document.getElementById('nutReset').addEventListener('click', () => {
  giaoDienForm.resetFields();
});

7. `validate(callback)` - Xác thực biểu mẫu

Chức năng: Kích hoạt xác thực biểu mẫu thủ công, hỗ trợ xác thực toàn bộ hoặc theo trường cụ thể.

Tham số:

callback {Function} Hàm callback được gọi khi xác thực hoàn tất
field {String|Array} Trường cần xác thực (tùy chọn)

Ví dụ:

// Xác thực toàn bộ
giaoDienForm.validate((hopLe, loiXayRa) => {
  if (hopLe) {
    console.log('Biểu mẫu hợp lệ');
  } else {
    console.log('Xác thực thất bại:', loiXayRa);
  }
});

// Xác thực các trường cụ thể
giaoDienForm.validate(['tenDangNhap', 'emailLienHe'], (hopLe) => {
  // Xử lý kết quả xác thực
});

8. `submit()` - Gửi biểu mẫu

Chức năng: Kích hoạt quy trình gửi biểu mẫu, tự động thực hiện xác thực trước khi gửi dữ liệu.

Ví dụ:

// Gửi biểu mẫu thủ công
document.getElementById('nutGui').addEventListener('click', () => {
  giaoDienForm.submit();
});

// Lắng nghe sự kiện gửi (cấu hình trong options)
const cauHinh = {
  onSubmit: (duLieu) => {
    // Xử lý dữ liệu biểu mẫu đã gửi
    return new Promise((hoanThanh) => {
      setTimeout(() => {
        console.log('Gửi biểu mẫu thành công:', duLieu);
        hoanThanh(); // Phải gọi resolve để thông báo việc gửi hoàn tất
      }, 1200);
    });
  }
};

API thao tác quy tắc

9. `append(rule, position)` - Thêm trường

Chức năng: Thêm quy tắc trường mới vào cuối biểu mẫu hoặc tại một vị trí cụ thể.

Tham số:

rule {Object|Array} Đối tượng hoặc mảng các quy tắc trường
position {Number} Chỉ mục vị trí chèn (tùy chọn)

Ví dụ:

// Tạo quy tắc mới
const quyTacMonHoc = formCreate.maker.select('Môn học yêu thích', 'favSubject', [])
  .options([
    { label: 'Toán học', value: 'math' },
    { label: 'Vật lý', value: 'physics' },
    { label: 'Hóa học', value: 'chemistry' }
  ]);

// Thêm vào cuối biểu mẫu
giaoDienForm.append(quyTacMonHoc);

// Chèn vào vị trí cụ thể (chỉ mục 1)
giaoDienForm.append(quyTacMonHoc, 1);

10. `remove(field)` - Xóa trường

Chức năng: Xóa trường cụ thể khỏi biểu mẫu dựa trên tên trường.

Tham số:

field {String} Tên trường cần xóa (bắt buộc)

Ví dụ:

// Xóa trường 'tenDangNhap'
giaoDienForm.remove('tenDangNhap');

// Xóa nhiều trường (hỗ trợ từ v2.5.0+)
giaoDienForm.remove(['tenDangNhap', 'emailLienHe']);

11. `updateRule(field, newRule)` - Cập nhật quy tắc

Chức năng: Cập nhật động quy tắc tạo của một trường cụ thể, hỗ trợ cập nhật một phần thuộc tính.

Tham số:

field {String} Tên trường mục tiêu
newRule {Object} Cấu hình quy tắc mới (hỗ trợ ghi đè một phần)

Ví dụ:

// Cập nhật tiêu đề và quy tắc xác thực cho trường email
giaoDienForm.updateRule('emailLienHe', {
  title: 'Địa chỉ Email', // Thay đổi tiêu đề
  validate: [{ required: true, message: 'Vui lòng nhập địa chỉ email hợp lệ' }] // Sửa quy tắc xác thực
});

// Thay đổi thuộc tính của trường 'matKhau'
giaoDienForm.updateRule('matKhau', {
  props: { type: 'password', disabled: false }
});

API xử lý sự kiện

12. `on(eventName, handler)` - Gắn sự kiện

Chức năng: Gắn một trình lắng nghe sự kiện cho thể hiện biểu mẫu, hỗ trợ các sự kiện cấp biểu mẫu và cấp trường.

Các sự kiện phổ biến:

submit Sự kiện gửi biểu mẫu
change Sự kiện thay đổi giá trị trường
validate Sự kiện thay đổi trạng thái xác thực
mounted Sự kiện hoàn tất gắn kết biểu mẫu

Ví dụ:

// Lắng nghe sự kiện gửi
giaoDienForm.on('submit', (duLieu) => {
  return new Promise((hoanThanh) => {
    setTimeout(() => {
      console.log('Gửi dữ liệu bất đồng bộ hoàn tất');
      hoanThanh(); // Phải gọi resolve để thông báo biểu mẫu đã hoàn tất việc gửi
    }, 1500);
  });
});

// Lắng nghe sự kiện thay đổi trường
giaoDienForm.on('change', (truong, giaTri, duLieuHienTai) => {
  console.log(`Trường ${truong} thay đổi thành:`, giaTri);
});

13. `off(eventName, handler)` - Hủy gắn sự kiện

Chức năng: Loại bỏ trình lắng nghe sự kiện đã được gắn. Nếu không chỉ định handler, tất cả các trình lắng nghe của sự kiện đó sẽ bị xóa.

Ví dụ:

// Định nghĩa hàm xử lý sự kiện
const xuLyGuiForm = (duLieu) => { /* Logic xử lý */ };

// Gắn sự kiện
giaoDienForm.on('submit', xuLyGuiForm);

// Hủy gắn hàm xử lý cụ thể
giaoDienForm.off('submit', xuLyGuiForm);

// Hủy gắn tất cả các trình lắng nghe cho sự kiện 'submit'
giaoDienForm.off('submit');

API thao tác nâng cao

14. `validateField(field)` - Xác thực trường riêng lẻ

Chức năng: Thực hiện xác thực cho một trường cụ thể và trả về kết quả xác thực, thường được sử dụng trong các tình huống xác thực thời gian thực.

Tham số:

field {String} Tên trường

Ví dụ:

// Xác thực thời gian thực trường email khi thay đổi
document.getElementById('inputEmail').addEventListener('change', () => {
  giaoDienForm.validateField('emailLienHe').then((hopLe) => {
    if (hopLe) {
      console.log('Email hợp lệ');
    } else {
      console.log('Email không hợp lệ');
    }
  });
});

15. `destroy()` - Hủy biểu mẫu

Chức năng: Hủy hoàn toàn thể hiện biểu mẫu, giải phóng bộ nhớ và loại bỏ các phần tử DOM, hữu ích trong các ứng dụng SPA khi chuyển đổi trang.

Ví dụ:

// Kích hoạt hủy biểu mẫu khi người dùng rời khỏi một thành phần
const nutHuyForm = document.getElementById('huyForm');
if (nutHuyForm) {
  nutHuyForm.addEventListener('click', () => {
    giaoDienForm.destroy();
    console.log('Biểu mẫu đã bị hủy.');
  });
}

Mẹo thực hành và các phương pháp tốt nhất

Gợi ý tối ưu hóa hiệu suất

Tái sử dụng quy tắc: Sử dụng hàm tiện ích copyRule để tái sử dụng các quy tắc trường cùng loại.

const quyTacCoBan = {type: 'input', props: {clearable: true}};
const quyTacMaSp = formCreate.util.copyRule(quyTacCoBan, {field: 'maSanPham', title: 'Mã sản phẩm'});

Tải trì hoãn: Sử dụng thuộc tính lazyload cho các biểu mẫu phức tạp để hiển thị theo yêu cầu.

 {
  type: 'textarea',
  field: 'moTaChiTiet',
  title: 'Mô tả chi tiết',
  lazyload: true // Ban đầu không render, tải khi cuộn vào vùng hiển thị
 }

Thao tác hàng loạt: Sử dụng phương thức batch để xử lý cập nhật trường hàng loạt.

giaoDienForm.batch([
  {method: 'setValue', args: ['tenDangNhap', 'admin']},
  {method: 'updateRule', args: ['emailLienHe', {disabled: true}]}
]);

Các vấn đề thường gặp và giải pháp

Q1: Làm thế nào để thêm/bớt các mục biểu mẫu một cách linh hoạt?

A: Kết hợp API append/remove với công cụ tạo quy tắc maker:

// Gắn sự kiện cho nút 'Thêm mục'
document.getElementById('themMuc').addEventListener('click', () => {
  const quyTacDong = formCreate.maker.input(`Mục động ${Date.now()}`, `dynamic_item_${Date.now()}`, '');
  giaoDienForm.append(quyTacDong);
});

Q2: Làm thế nào để thực hiện xác thực liên kết giữa các trường?

A: Sử dụng sự kiện validate và hàm xác thực tùy chỉnh:

giaoDienForm.on('validate', (tenTruong, giaTriTruong, hopLeHienTai, duLieuTatCa) => {
  if (tenTruong === 'xacNhanEmail') {
    if (giaTriTruong !== duLieuTatCa.emailLienHe) {
      return {valid: false, message: 'Địa chỉ email xác nhận không khớp'};
    }
  }
  return {valid: true};
});

Khả năng tương thích phiên bản API

Tên phương thức	Phiên bản hỗ trợ tối thiểu	Mô tả thay đổi
`batch`	v2.4.0	Bổ sung API thao tác hàng loạt
`updateRule`	v2.3.0	Hỗ trợ cập nhật một phần quy tắc
`remove`	v2.2.0	Bổ sung hỗ trợ tham số mảng để xóa hàng loạt
`validateField`	v2.0.0	Phiên bản đầu tiên, hỗ trợ xác thực trường đơn lẻ

Thẻ: form-create JavaScript API Dynamic Forms Form Validation

Đăng vào ngày 19 tháng 5 lúc 10:09

Thành phố Cuồng loạn

Hướng dẫn toàn diện API form-create: 15 phương pháp cốt lõi để quản lý biểu mẫu động

Tổng quan về API và cách thức gọi

Bảng phân loại API chính

API khởi tạo biểu mẫu

1. `create(rule, options)` - Khởi tạo biểu mẫu

2. `maker` - Công cụ xây dựng quy tắc

3. `parseJson(jsonRule)` - Phân tích chuỗi JSON thành quy tắc

API thao tác dữ liệu

4. `getValue(field)` - Lấy dữ liệu biểu mẫu

5. `setValue(field, value)` - Đặt giá trị cho biểu mẫu

6. `resetFields()` - Đặt lại biểu mẫu

7. `validate(callback)` - Xác thực biểu mẫu

8. `submit()` - Gửi biểu mẫu

API thao tác quy tắc

9. `append(rule, position)` - Thêm trường

10. `remove(field)` - Xóa trường

11. `updateRule(field, newRule)` - Cập nhật quy tắc

API xử lý sự kiện

12. `on(eventName, handler)` - Gắn sự kiện

13. `off(eventName, handler)` - Hủy gắn sự kiện

API thao tác nâng cao

14. `validateField(field)` - Xác thực trường riêng lẻ

15. `destroy()` - Hủy biểu mẫu

Mẹo thực hành và các phương pháp tốt nhất

Gợi ý tối ưu hóa hiệu suất

Các vấn đề thường gặp và giải pháp

Q1: Làm thế nào để thêm/bớt các mục biểu mẫu một cách linh hoạt?

Q2: Làm thế nào để thực hiện xác thực liên kết giữa các trường?

Khả năng tương thích phiên bản API

Thẻ Phổ Biến

Thành phố Cuồng loạn

Hướng dẫn toàn diện API form-create: 15 phương pháp cốt lõi để quản lý biểu mẫu động

Tổng quan về API và cách thức gọi

Bảng phân loại API chính

API khởi tạo biểu mẫu

1. create(rule, options) - Khởi tạo biểu mẫu

2. maker - Công cụ xây dựng quy tắc

3. parseJson(jsonRule) - Phân tích chuỗi JSON thành quy tắc

API thao tác dữ liệu

4. getValue(field) - Lấy dữ liệu biểu mẫu

5. setValue(field, value) - Đặt giá trị cho biểu mẫu

6. resetFields() - Đặt lại biểu mẫu

7. validate(callback) - Xác thực biểu mẫu

8. submit() - Gửi biểu mẫu

API thao tác quy tắc

9. append(rule, position) - Thêm trường

10. remove(field) - Xóa trường

11. updateRule(field, newRule) - Cập nhật quy tắc

API xử lý sự kiện

12. on(eventName, handler) - Gắn sự kiện

13. off(eventName, handler) - Hủy gắn sự kiện

API thao tác nâng cao

14. validateField(field) - Xác thực trường riêng lẻ

15. destroy() - Hủy biểu mẫu

Mẹo thực hành và các phương pháp tốt nhất

Gợi ý tối ưu hóa hiệu suất

Các vấn đề thường gặp và giải pháp

Q1: Làm thế nào để thêm/bớt các mục biểu mẫu một cách linh hoạt?

Q2: Làm thế nào để thực hiện xác thực liên kết giữa các trường?

Khả năng tương thích phiên bản API

Thẻ Phổ Biến

1. `create(rule, options)` - Khởi tạo biểu mẫu

2. `maker` - Công cụ xây dựng quy tắc

3. `parseJson(jsonRule)` - Phân tích chuỗi JSON thành quy tắc

4. `getValue(field)` - Lấy dữ liệu biểu mẫu

5. `setValue(field, value)` - Đặt giá trị cho biểu mẫu

6. `resetFields()` - Đặt lại biểu mẫu

7. `validate(callback)` - Xác thực biểu mẫu

8. `submit()` - Gửi biểu mẫu

9. `append(rule, position)` - Thêm trường

10. `remove(field)` - Xóa trường

11. `updateRule(field, newRule)` - Cập nhật quy tắc

12. `on(eventName, handler)` - Gắn sự kiện

13. `off(eventName, handler)` - Hủy gắn sự kiện

14. `validateField(field)` - Xác thực trường riêng lẻ

15. `destroy()` - Hủy biểu mẫu