CForm

Form chuẩn của framework: bọc a-form, đặt sẵn layout dọc (nhãn trên, ô nhập dưới) và chuyển tiếp nguyên vẹn mọi prop, slot, sự kiện của antd Form.

Dùng khi: mọi màn hình nhập liệu — tạo mới, chỉnh sửa, bộ lọc trong drawer, hộp thoại nhập nhanh.

Không dùng khi: chỉ có một ô nhập không cần nhãn và không cần kiểm tra (ô tìm kiếm rời) — dùng CInput trực tiếp.

<script setup lang="ts">
import { reactive } from 'vue'
import { CFormItem, CInput, CSelect, CSelectOption, CTextarea, message } from '@tasco/ui'

// Form chuẩn: layout dọc, rules phía client, gửi bằng nút html-type="submit".
// CForm phát `finish` khi mọi rule đã qua và `finishFailed` khi có rule chưa qua.
const model = reactive({ customer: '', channel: undefined as string | undefined, note: '' })

const rules = {
  customer: [{ required: true, message: 'Nhập tên khách hàng' }],
  channel: [{ required: true, message: 'Chọn kênh bán' }],
}

function onFinish() {
  message.success(`Đã gửi: ${model.customer} · ${model.channel}`)
}

function onFinishFailed() {
  message.warning('Kiểm tra lại các ô còn thiếu.')
}
</script>

<template>
  <CForm
    :model="model"
    :rules="rules"
    style="max-width: 420px"
    @finish="onFinish"
    @finish-failed="onFinishFailed"
  >
    <CFormItem
      label="Khách hàng"
      name="customer"
    >
      <CInput
        v-model:value="model.customer"
        placeholder="Tên khách hàng"
      />
    </CFormItem>

    <CFormItem
      label="Kênh bán"
      name="channel"
    >
      <CSelect
        v-model:value="model.channel"
        placeholder="Chọn kênh"
      >
        <CSelectOption value="direct">
          Trực tiếp
        </CSelectOption>
        <CSelectOption value="online">
          Trực tuyến
        </CSelectOption>
      </CSelect>
    </CFormItem>

    <CFormItem
      label="Ghi chú"
      name="note"
    >
      <CTextarea
        v-model:value="model.note"
        :rows="2"
      />
    </CFormItem>

    <CFormItem>
      <CButton
        variant="primary"
        html-type="submit"
      >
        Lưu
      </CButton>
    </CFormItem>
  </CForm>
</template>

Gửi form

Hai cách, chọn theo việc trang cần làm:

Cách	Dùng khi	Đánh đổi
@finish + nút html-type="submit"	Trang thêm/sửa thường: một nút Lưu, validate cả form rồi gọi API	Ít code nhất, và Enter trong ô nhập cũng gửi được form
ref → formRef.value.validate()	Trang tự quyết thời điểm: validate một phần (bước wizard), resetFields() sau khi lưu, clearValidate() khi đổi giữa chế độ thêm và sửa	Trang phải tự bắt lỗi khi validate() reject

Dùng chung được: nút Lưu vẫn đi qua @finish, còn ref lo phần reset và validate từng bước.

Bằng @finish

Sự kiện	Khi nào phát
@finish	Người dùng gửi form và mọi rule đã qua — đây là chỗ gọi API
@finish-failed	Có rule chưa qua; antd đã tự hiện lỗi dưới từng ô

<CForm :model="model" :rules="rules" @finish="onFinish" @finish-failed="onFinishFailed">
  <!-- … -->
  <CFormItem>
    <CButton variant="primary" :loading="submitting" html-type="submit">Lưu</CButton>
  </CFormItem>
</CForm>

Bằng ref từ 2.1

Bản 2.0 của @tasco/ui chưa expose API của form (formRef.value.validate là undefined) — app còn ở 2.0 gửi form bằng @finish.

CForm expose API của form; khai kiểu bằng CFormInstance của @tasco/ui. Đừng import FormInstance từ ant-design-vue — ESLint chặn mọi import từ đó, kể cả import type.

<script setup lang="ts">
import type { CFormInstance } from '@tasco/ui'

const formRef = ref<CFormInstance>()

async function luu() {
  try {
    await formRef.value?.validate()
  } catch {
    return   // rule chưa qua — antd đã hiện lỗi dưới từng ô
  }
  await createOrder({ ...model })
  formRef.value?.resetFields()
}
</script>

<template>
  <CForm ref="formRef" :model="model" :rules="rules">
    <!-- … -->
  </CForm>
</template>

Hàm	Việc
validate(nameList?)	Validate cả form, hoặc chỉ các field trong nameList
validateFields(nameList?)	Tên gọi khác của validate, hành vi giống hệt
resetFields(name?)	Trả về giá trị khởi tạo và xoá lỗi
clearValidate(name?)	Chỉ xoá lỗi, giữ nguyên giá trị
scrollToField(name)	Cuộn tới một ô — dùng khi tự xử lý lỗi 422

validate() reject khi có rule chưa qua, nên luôn bọc try/catch: để promise reject trần là tạo unhandled rejection. Gọi các hàm này lúc form chưa mount (hoặc đã bị gỡ) sẽ ném lỗi [@tasco/ui] … nói rõ nguyên nhân.

Ví dụ đầy đủ — wizard hai bước, mỗi bước chỉ validate phần của nó:

<script setup lang="ts">
import { computed, reactive, ref } from 'vue'
import type { CFormInstance } from '@tasco/ui'
import { CFormItem, CInput, CStep, CSteps, message } from '@tasco/ui'

// Wizard hai bước: bước 1 chỉ validate phần của nó, nên không dùng được @finish
// (sự kiện đó luôn validate cả form). Lấy API của form qua template ref.
const formRef = ref<CFormInstance>()
const step = ref(0)
const saving = ref(false)

const model = reactive({ customer: '', email: '', amount: 0 })

const rules = {
  customer: [{ required: true, message: 'Nhập tên khách hàng' }],
  email: [
    { required: true, message: 'Nhập email' },
    { type: 'email', message: 'Email không hợp lệ' },
  ],
  amount: [{ required: true, message: 'Nhập giá trị đơn hàng' }],
}

const stepFields = computed(() => (step.value === 0 ? ['customer', 'email'] : ['amount']))

async function next() {
  try {
    await formRef.value?.validate(stepFields.value)
    step.value = 1
  }
  catch {
    // antd đã hiện lỗi dưới từng ô — chỉ cần giữ nguyên bước hiện tại.
  }
}

async function save() {
  saving.value = true
  try {
    await formRef.value?.validate()
    message.success(`Đã lưu đơn của ${model.customer}.`)
    formRef.value?.resetFields()
    step.value = 0
  }
  catch {
    // Rule chưa qua: lỗi đã hiện tại ô, không cần thông báo thêm.
  }
  finally {
    saving.value = false
  }
}
</script>

<template>
  <div style="max-width: 420px">
    <CSteps
      :current="step"
      size="small"
      style="margin-bottom: 24px"
    >
      <CStep title="Khách hàng" />
      <CStep title="Giá trị" />
    </CSteps>

    <CForm
      ref="formRef"
      :model="model"
      :rules="rules"
    >
      <template v-if="step === 0">
        <CFormItem
          label="Khách hàng"
          name="customer"
        >
          <CInput
            v-model:value="model.customer"
            placeholder="Công ty An Bình"
          />
        </CFormItem>
        <CFormItem
          label="Email"
          name="email"
        >
          <CInput
            v-model:value="model.email"
            placeholder="lienhe@anbinh.vn"
          />
        </CFormItem>
      </template>

      <CFormItem
        v-else
        label="Giá trị đơn"
        name="amount"
      >
        <CInputCurrency v-model:value="model.amount" />
      </CFormItem>

      <CFormItem>
        <div style="display: flex; gap: 8px">
          <CButton
            v-if="step === 0"
            variant="primary"
            @click="next"
          >
            Tiếp tục
          </CButton>
          <template v-else>
            <CButton
              variant="outline"
              @click="step = 0"
            >
              Quay lại
            </CButton>
            <CButton
              variant="primary"
              :loading="saving"
              @click="save"
            >
              Lưu
            </CButton>
          </template>
        </div>
      </CFormItem>
    </CForm>
  </div>
</template>

Rules

const rules = {
  customer: [{ required: true, message: 'Nhập tên khách hàng' }],
  email: [
    { required: true, message: 'Nhập email' },
    { type: 'email', message: 'Email không hợp lệ' },
  ],
  amount: [{ required: true, message: 'Nhập giá trị' }],
}

name của CFormItem phải trùng khoá trong model và trong rules, nếu không rule không chạy và lỗi không hiện ở đúng ô.

Thông báo viết tiếng Việt, nói việc cần làm ("Nhập tên khách hàng") thay vì mô tả lỗi ("Trường bắt buộc").

Lỗi nghiệp vụ từ backend

Rules chỉ kiểm được thứ trình duyệt biết. Lỗi nghiệp vụ (mã trùng, vượt hạn mức) do backend trả về dạng 422 và gắn vào từng ô bằng validate-status + help:

<CFormItem
  label="Khách hàng"
  name="customer"
  :validate-status="serverErrors.customer ? 'error' : undefined"
  :help="serverErrors.customer?.[0]"
>
  <CInput v-model:value="model.customer" />
</CFormItem>

Chi tiết: Lỗi 422 và form.

Bố cục

<script setup lang="ts">
import { ref } from 'vue'
import { CFormItem, CInput, Col as CCol, Row as CRow } from '@tasco/ui'

// Hai kiểu bố cục hay dùng: ngang (nhãn bên trái) và lưới nhiều cột.
const model = ref({ code: 'DH-0001', customer: 'Công ty An Bình', owner: 'Đỗ Xuân Thành' })
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 24px">
    <CForm
      layout="horizontal"
      :label-col="{ span: 6 }"
      :wrapper-col="{ span: 18 }"
      :model="model"
      style="max-width: 460px"
    >
      <CFormItem label="Mã đơn">
        <CInput v-model:value="model.code" />
      </CFormItem>
      <CFormItem label="Khách hàng">
        <CInput v-model:value="model.customer" />
      </CFormItem>
    </CForm>

    <CForm :model="model">
      <CRow :gutter="16">
        <CCol
          :xs="24"
          :md="12"
        >
          <CFormItem label="Khách hàng">
            <CInput v-model:value="model.customer" />
          </CFormItem>
        </CCol>
        <CCol
          :xs="24"
          :md="12"
        >
          <CFormItem label="Người phụ trách">
            <CInput v-model:value="model.owner" />
          </CFormItem>
        </CCol>
      </CRow>
    </CForm>
  </div>
</template>

Mặc định layout="vertical" — dễ đọc, hợp màn hình hẹp, nhãn dài không bị cắt. Đổi sang horizontal khi form ngắn và nhãn đều nhau; nhớ khai label-col / wrapper-col.

Form nhiều cột dùng Row + Col từ @tasco/ui, luôn có điểm ngắt (:xs="24") để không vỡ trên màn hình hẹp.

API

CForm không thêm prop nào ngoài mặc định layout="vertical"; toàn bộ prop, slot và sự kiện của a-form (model, rules, label-col, wrapper-col, disabled, @finish, @finish-failed, @values-change…) dùng như bình thường.

Bảng trên không liệt kê hàm lấy qua ref — xem Bằng ref.

Ô nhập đi kèm

Dữ liệu	Component
Chữ ngắn / dài	CInput, CTextarea
Số	CInputNumber
Tiền	CInputCurrency
Phần trăm	CInputPercent
Chọn một / nhiều	CSelect + CSelectOption
Có/không	CSwitch, CCheckbox
Ngày, khoảng ngày	CDatePicker, CRangePicker
Tệp	CUpload

Tất cả là primitive antdv re-export: import { CInput, CSelect } from '@tasco/ui'.

Khả năng tiếp cận

• CFormItem gắn <label> với ô nhập, nên bấm nhãn là focus vào ô — đừng thay nhãn bằng chữ thường đặt cạnh.
• Lỗi hiện qua help được antd liên kết bằng aria-describedby; trình đọc màn hình đọc được khi người dùng vào ô.
• Ô bắt buộc có dấu * do required trong rules sinh ra — đừng tự thêm dấu sao vào nhãn.
• Sau khi gửi thất bại, antd cuộn tới ô lỗi đầu tiên; giữ hành vi đó thay vì tự cuộn.

Lưu ý

• model nên là reactive object phẳng chứa đúng các field của form; đừng gán nguyên bản ghi lấy từ backend vào đó.
• Bật :loading trên nút lưu trong lúc gửi; luôn tắt trong finally.
• Form dài nên có nút Huỷ rõ ràng và cảnh báo khi rời trang — xem Trang form.

Liên quan

• Trang form — mẫu trang đầy đủ.
• Lỗi 422 và form — lỗi nghiệp vụ.
• CFilterBar — form lọc ngắn đặt trên bảng.