رفتن به محتوای اصلی
  • معرفی
  • نصب
  • Tailwind
  • وب کامپوننت‌ها (بدون React)
  • دوزبانه، فارسی و انگلیسی
  • پلاگین‌های فیگما
  • استفاده با هوش مصنوعی
  • آیکون‌ها
  • راهنمای آیکون‌ها
  • سفارشی‌سازی و تم
  • حرکت و ریزتعامل‌ها
  • حالت‌های کامپوننت‌ها
  • فونت و تایپوگرافی
  • دسترس‌پذیری
  • نوشتن متن رابط
  • رنگ‌ها
  • برند کاشی
  • مقایسه با دیگران
  • نسخه‌ها
  • سیاست تغییرات
  • مهاجرت به ۲.۰
  • امنیت
  • حجم کامپوننت‌ها
  • فیلد فارسی
  • دیت‌پیکر شمسی
  • کد تأیید (OTP)
  • بازهٔ تاریخ شمسی
  • انتخاب ماه
  • شمارش معکوس
  • هیت‌مپ فعالیت
  • انتخاب استان
  • نقشهٔ ایران
  • فرم نشانی
  • انتخاب نوبت
  • ویرایش نگارشی
  • نمایش مبلغ
  • بازهٔ قیمت
  • کارت بانکی
  • رسید پرداخت
  • برگ تقویم
  • لوگوی بانک‌ها
  • ابزارهای فارسی
  • آپلود فایل
  • آکاردئون
  • آواتار
  • اسپلیتر
  • استپر
  • اسکلتون
  • اسلایدر
  • اعتبارسنجی فرم
  • امتیاز ستاره‌ای
  • انتخاب چندتایی
  • انتخاب رنگ
  • بج
  • بردکرامب
  • برگهٔ پایین
  • بنر
  • پاپ‌اور
  • تایم‌لاین
  • تب‌ها
  • تور معرفی
  • توست
  • تولتیپ
  • جداکننده و کلید میان‌بر
  • جدول داده
  • جستجو با پیشنهاد
  • چک‌باکس
  • چیپس
  • حالت خالی
  • دراپ‌داون
  • دکمه
  • دکمهٔ کپی
  • دیالوگ
  • رادیو
  • سایدبار
  • سگمنت
  • سلکت
  • سوییچ
  • صفحه‌بندی
  • قدرت رمز عبور
  • کارت
  • کارت آمار
  • کاروسل
  • کامبوباکس
  • کامند پالت
  • کشو
  • گروه دکمه
  • گیج
  • منوی راست‌کلیک
  • نمای درختی
  • نمودار
  • نمونهٔ رنگ
  • نوار پیشرفت
  • نوار ناوبری
  • ورودی
  • ورودی تگ
  • ورودی عدد
  • ویرایش درجا
  • هشدار
شروع کنید

اعتبارسنجی فرم

هوک useForm برای مقدار و خطای فیلدها با پیام‌های فارسی؛ قاعده‌های آماده برای کد ملی، موبایل، شبا، کارت و کد پستی.

import { useForm, rules } from "@kashi-ui/react";

نمونه

const form = useForm({
defaultValues: { name: "", nationalId: "", mobile: "", password: "", repeat: "", agree: false },
rules: {
  name: [rules.required(), rules.minLength(3)],
  nationalId: [rules.required(), rules.nationalId()],
  mobile: [rules.required(), rules.mobile()],
  password: [rules.required(), rules.minLength(8)],
  repeat: [rules.required(), rules.match("password")],
  agree: [rules.required("برای ادامه قوانین را بپذیرید.")],
},
});

<form noValidate onSubmit={form.handleSubmit(save)}>
{form.summary && <Alert tone="error" title={form.summary} />}
<Input label="نام و نام خانوادگی" {...form.field("name")} />
<NationalIdInput label="کد ملی" {...form.field("nationalId", { type: "value" })} />
<MobileInput label="موبایل" {...form.field("mobile", { type: "value" })} />
<Input label="رمز عبور" type="password" {...form.field("password")} />
<Input label="تکرار رمز عبور" type="password" {...form.field("repeat")} />
<Checkbox label="قوانین را می‌پذیرم" {...form.field("agree", { type: "checkbox" })} />
<Button type="submit" loading={form.isSubmitting}>ثبت‌نام</Button>
</form>

بدون پر کردن روی «ثبت‌نام» بزنید: خلاصهٔ خطاها بالای فرم می‌آید، اولین فیلد نادرست فوکوس می‌گیرد و هر خطا با اصلاح همان فیلد فوراً می‌رود.

اتصال فیلدها

form.field(name) همهٔ چیزی را که یک فیلد کاشی لازم دارد برمی‌گرداند: value، رویداد تغییر، onBlur، error، aria-invalid، required و ref برای فوکوس. روی کامپوننت پخشش کنید:

نوع برای چه می‌دهد
پیش‌فرض Input، Textarea، input بومی value و onChange
{ type: "value" } فیلدهای فارسی و هر کامپوننتی که onValueChange دارد: کد ملی، موبایل، شبا، کارت، مبلغ، کد پستی value و onValueChange (مقدار خام بدون فاصله)
{ type: "checkbox" } Checkbox و Switch checked، onChange؛ خطا در description

فیلدهای فارسی خودشان هم کد نامعتبر را تشخیص می‌دهند؛ با useForm همان پیام هنگام ارسال هم نشان داده می‌شود و ارسال تا اصلاح آن انجام نمی‌شود.

قاعده‌ها

همهٔ قاعده‌ها جز required مقدار خالی را رد نمی‌کنند، پس یک فیلد اختیاری ایمیل فقط وقتی پر شده بررسی می‌شود. ارقام فارسی و عربی پذیرفته می‌شوند. پیام پیش‌فرض با زبان KashiProvider فارسی یا انگلیسی است و پیام دلخواه را به‌عنوان آخرین آرگومان بدهید.

قاعده بررسی پیام پیش‌فرض
rules.required() خالی نباشد (فاصلهٔ تنها هم خالی است) این بخش را پر کنید.
rules.minLength(n) / maxLength(n) تعداد نویسه دست‌کم n نویسه بنویسید.
rules.min(n) / max(n) مقدار عددی مقدار باید دست‌کم n باشد.
rules.email() قالب ایمیل نشانی ایمیل درست نیست؛ مثلاً name@example.com.
rules.pattern(re, msg) عبارت باقاعده قالب این مقدار درست نیست.
rules.nationalId() کد ملی با رقم کنترل کد ملی معتبر نیست.
rules.legalId() شناسهٔ ملی شرکت شناسهٔ ملی معتبر نیست.
rules.mobile() / landline() موبایل و تلفن ثابت ایران شماره موبایل معتبر نیست.
rules.card() / iban() شماره کارت (لون) و شبا شماره کارت معتبر نیست.
rules.postalCode() کد پستی ده‌رقمی کد پستی معتبر نیست.
rules.match(field) برابری با فیلد دیگر این دو مقدار یکسان نیستند.
rules.custom(fn, msg) هر شرط دلخواه؛ fn(value, values) پیام خودتان

پیام‌ها را برای کل برنامه با KashiProvider عوض کنید: messages={{ form: { required: "پر کردن الزامی است." } }}. متن خطا را طبق نوشتن متن رابط بنویسید: بگویید چه شده و چه کار کنند.

زمان بررسی

validateOn: "blur" (پیش‌فرض) بعد از خروج از فیلد، "change" با هر تایپ و "submit" فقط هنگام ارسال. در هر سه حالت، بعد از اولین ارسال یا وقتی فیلدی خطا دارد، با هر تغییر دوباره بررسی می‌شود تا کاربر بلافاصله ببیند خطا رفته است.

خطای سرور

خطایی را که سرور برگرداند روی همان فیلد بنشانید:

const save = form.handleSubmit(async (values) => {
  const res = await signup(values);
  if (res.mobileTaken) form.setError("mobile", "این شماره قبلاً ثبت‌نام کرده است؛ وارد شوید.");
});

آنچه برمی‌گرداند

ویژگی‌ها (props)
نامتوضیح، نوع و پیش‌فرض
field(name, { type })

اتصال فیلد؛ type یکی از text، value، checkbox

نوع: FieldBinding

handleSubmit(fn)

بررسی همه، فوکوس روی اولین خطا و اجرای fn با مقادیر

نوع: (e) => Promise<void>

values / errors / touched

مقادیر، پیام خطای هر فیلد و فیلدهای لمس‌شده

نوع: object

summary

«۲ مورد را اصلاح کنید.» پس از ارسال ناموفق

نوع: stringundefined

setValue / setError

تغییر مقدار یا خطای یک فیلد از بیرون

نوع: (name, value)

validate

بررسی بدون ارسال

نوع: () => boolean

reset(values?)

بازگشت به مقادیر اولیه یا مقادیر تازه

isSubmitting / isDirty / submitCount

در حال ارسال، تغییر کرده، تعداد ارسال

نوع: boolean / number

دسترس‌پذیری

  • خطای هر فیلد با aria-invalid و aria-describedby به همان فیلد وصل است.
  • پس از ارسال ناموفق، فوکوس به اولین فیلد نادرست می‌رود تا کاربر صفحه‌خوان و کیبورد مستقیم به مشکل برسد.
  • noValidate روی فرم بگذارید تا حباب‌های پیش‌فرض مرورگر با پیام‌های فارسی کاشی تداخل نکنند.

راهنمای استفاده

کِی استفاده کنیم

  • فرم ثبت‌نام، پرداخت، احراز هویت یا هر فرمی که خطایش باید فارسی و دقیق باشد.
  • فیلدهای ایرانی مثل کد ملی، موبایل، شبا و کارت که قاعدهٔ آماده دارند.

کِی استفاده نکنیم

  • فرم یک‌فیلدی مثل جست‌وجو؛ ویژگی‌های خود فیلد کافی است. ورودی

درست و نادرست

  1. درست

    کد ملی معتبر نیست؛ ده رقم را دوباره بررسی کنید.

    درست: خطا بگوید چه شده و چه کار کنند، کنار همان فیلد.
    نادرست

    ورودی نامعتبر است.

    نادرست: پیام کلی بالای فرم بدون مشخص کردن فیلد.
  2. درست
    درست: بررسی هنگام خروج از فیلد (پیش‌فرض blur) و پاک شدن خطا همان لحظهٔ اصلاح.
    نادرست
    نادرست: خطای قرمز از اولین حرفی که کاربر تایپ می‌کند.