ابزارهای فارسی

پکیج @kashi-ui/persian هیچ وابستگی‌ای ندارد و در مرورگر، Node.js و هر فریم‌ورکی (React، Vue، Svelte، Angular) کار می‌کند. کامپوننت‌های فارسی کاشی هم روی همین پکیج ساخته شده‌اند.

تاریخ شمسی

import { toJalali, toGregorian, formatJalali, parseJalali } from "@kashi-ui/persian";

toJalali(new Date(2024, 7, 2));        // { jy: 1403, jm: 5, jd: 12 }
toGregorian(1403, 5, 12);               // Date: 2024-08-02

formatJalali(date);                     // "۱۴۰۳/۰۵/۱۲"
formatJalali(date, { style: "long" });  // "۱۲ مرداد ۱۴۰۳"
formatJalali(date, { style: "full" });  // "جمعه ۱۲ مرداد ۱۴۰۳"

parseJalali("۱۴۰۳/۵/۱۲");               // Date
parseJalali("1404/12/30");              // null (۱۴۰۴ کبیسه نیست)

هشدار منطقهٔ زمانی: برای ارسال تاریخ به سرور از date.toISOString() استفاده نکنید. این تابع زمان را به UTC تبدیل می‌کند و چون ایران ۳٫۵ ساعت جلوتر است، نیمه‌شب را روز قبل می‌کند. به‌جای آن از toISODate(date) استفاده کنید.

دقت: تبدیل برای همهٔ ۷۲٬۹۷۰ روز از ۱۳۰۰ تا ۱۵۰۰ با تقویم persian کتابخانهٔ ICU (همان تقویم مرورگرها) مقایسه و تست شده است.

زمان نسبی

import { formatRelative } from "@kashi-ui/persian";

formatRelative(date);   // «همین الان»، «۵ دقیقه پیش»، «دیروز»، «۳ روز دیگر»، «۲ سال پیش»

«دیروز» و «فردا» بر اساس روز تقویمی محاسبه می‌شوند، نه ۲۴ ساعت. در React از <RelativeTime date={date} /> استفاده کنید که هر دقیقه به‌روز می‌شود و تاریخ کامل شمسی را در title دارد.

ارقام و اعداد

import { toFaDigits, toEnDigits, onlyDigits, formatNumber } from "@kashi-ui/persian";

toFaDigits(1403);              // "۱۴۰۳"
toEnDigits("۰۹۱۲ ٣٤٥");        // "0912 345"  (ارقام عربی هم)
onlyDigits("۰۹۱۲-۳۴۵ 67");     // "091234567"
formatNumber(1250000);         // "۱٬۲۵۰٬۰۰۰"

toEnDigits را همیشه پیش از ذخیرهٔ ورودی کاربر استفاده کنید؛ کاربر ایرانی ممکن است با هر دو صفحه‌کلید تایپ کند.

عدد به حروف

import { numberToWords } from "@kashi-ui/persian";

numberToWords(1250000); // "یک میلیون و دویست و پنجاه هزار"
numberToWords(1001);    // "هزار و یک"
numberToWords(-45);     // "منفی چهل و پنج"

یکدست‌سازی متن

کاربران با صفحه‌کلید عربی «ي» و «ك» تایپ می‌کنند و جستجوی «علی» دیگر «علي» را پیدا نمی‌کند. پیش از ذخیره و جستجو، متن را یکدست کنید:

import { normalizePersian } from "@kashi-ui/persian";

normalizePersian("علي كريمي");                 // "علی کریمی"
normalizePersian("مـــدرسه");                   // "مدرسه"   (حذف کشیده)
normalizePersian("كتاب ١٢", { digits: "fa" }); // "کتاب ۱۲"

برای متنی که کاربر می‌نویسد (توضیحات، نظرها، مقاله‌ها)، fixPersianText ویرایش نگارشی هم انجام می‌دهد: نیم‌فاصله، ویرگول و علامت سؤال فارسی و ارقام. تعداد هر نوع اصلاح را هم برمی‌گرداند. کامپوننت آن ویرایش نگارشی است.

import { fixPersianText, fixKeyboardLayout } from "@kashi-ui/persian";

fixPersianText("كتاب ها را مي خوانم ?").text; // "کتاب‌ها را می‌خوانم؟"
fixKeyboardLayout("sghl");                     // "سلام" (صفحه‌کلید انگلیسی به فارسی)

مبلغ

import { formatMoney, rialToToman } from "@kashi-ui/persian";

formatMoney(1250000);                              // "۱٬۲۵۰٬۰۰۰ تومان"
formatMoney(1250000, { compact: true });           // "۱٫۲۵ میلیون تومان"
formatMoney(125000000, { from: "rial", compact: true }); // "۱۲٫۵ میلیون تومان"
rialToToman(50000);                                // 5000

اعتبارسنجی

import { isValidNationalId, isValidCardNumber, getBankByCard, formatCardNumber } from "@kashi-ui/persian";

isValidNationalId("0013542419");         // true
isValidLegalId("10380284790");           // true (شناسهٔ ملی شرکت)
isValidIban("IR062960000000100324200001");
isValidMobile("+98 912 345 6789");       // true
getMobileOperator("0935")?.name;          // "ایرانسل"
isValidCardNumber("4111111111111111");   // true
getBankByCard("610433");                 // { name: "بانک ملت", slug: "mellat" }
formatCardNumber("6104331234");          // "6104 3312 34"
isValidPostalCode("1193653471");         // true
formatPostalCode("1193653471");          // "11936-53471"
isValidPlate({ first: "12", letter: "ب", middle: "345", region: "67" }); // true
formatPlate({ first: "12", letter: "ب", middle: "345", region: "67" });  // "۱۲ ب ۳۴۵ ایران ۶۷"
plateType("ت");                          // "taxi"
isValidLandline("+98 21 8877 6655");     // true
getLandlineProvince("031");              // "اصفهان"
formatLandline("02188776655");           // "021 8877 6655"

ساعت

import { parseTime, formatTime } from "@kashi-ui/persian";

parseTime("۹:۳۰");                       // { hours: 9, minutes: 30 }
parseTime("2145");                       // { hours: 21, minutes: 45 }
parseTime("25:00");                      // null
formatTime({ hours: 9, minutes: 5 });    // "09:05"