وب کامپوننت‌ها

پکیج @kashi-ui/elements کامپوننت‌های تعاملی کاشی را به‌شکل وب کامپوننت (Custom Elements استاندارد مرورگر) دارد. با هر فریم‌ورکی کار می‌کنند، یا بدون فریم‌ورک:

• HTML ساده و وردپرس: یک خط CSS و یک خط script، بدون ابزار ساخت.
• Vue، Svelte و Angular: مثل هر تگ HTML دیگری.
• فرم معمولی HTML: مقدار هر فیلد با name ارسال می‌شود و فرم با مقدار نامعتبر ارسال نمی‌شود.

ظاهر از همان @kashi-ui/css می‌آید و عنصرها Shadow DOM ندارند؛ پس تم، رنگ برند، حالت روشن و تیره و CSS خودتان بی‌تغییر روی آن‌ها اعمال می‌شود. در پروژهٔ React همان @kashi-ui/react را به کار ببرید.

این صفحه راه‌اندازی کلی است. نصب، نمونهٔ زنده، ویژگی‌ها و رویدادهای هر کامپوننت در بخش «وب کامپوننت» صفحهٔ همان کامپوننت آمده است (فهرست).

نصب

بدون نصب، از CDN، در <head> صفحه:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kashi-ui/css/dist/kashi.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@kashi-ui/elements/dist/cdn/kashi-elements.js"></script>

یا با npm، در پروژه‌ای که ابزار ساخت دارد (Vite، Nuxt، SvelteKit، Angular):

npm i @kashi-ui/elements @kashi-ui/css

import "@kashi-ui/css";
import "@kashi-ui/elements"; // همه؛ یا فقط یک بخش، مثل "@kashi-ui/elements/inputs.js"

صفحه را راست‌به‌چپ کنید: <html lang="fa" dir="rtl">.

نمونه

یک فرم معمولی HTML با چند کامپوننت کاشی:

<form action="/checkout" method="post">
<kashi-national-id name="national_id" required></kashi-national-id>
<kashi-mobile name="mobile"></kashi-mobile>
<kashi-date-picker label="تاریخ تحویل" name="delivery" holidays></kashi-date-picker>
<button class="k-btn k-btn--primary">ثبت سفارش</button>
</form>

کامپوننت‌ها

۶۳ عنصر؛ روی نام هر کامپوننت بزنید تا نصب، نمونه، ویژگی‌ها و رویدادهایش را ببینید.

فیلدها ویژگی‌های مشترک دارند: label، name، value، hint، error (خطای دلخواه، مثلاً از سرور)، required، disabled و aria-label (به‌جای برچسب دیداری).

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

هر فیلد با name مقدار خام خود را با ارقام انگلیسی ارسال می‌کند: کد ملی 0013542419، موبایل 09123456789، شبا IR…، مبلغ 2500000 و تاریخ 2026-03-21. قالب نمایشی (فاصله‌ها و ارقام فارسی) به سرور نمی‌رسد.

مقدار نامعتبر جلوی ارسال فرم را می‌گیرد و مرورگر پیام خطای فارسی همان فیلد را نشان می‌دهد؛ required هم مثل input معمولی کار می‌کند.

<form action="/checkout" method="post">
  <kashi-national-id name="national_id" required></kashi-national-id>
  <kashi-postal-code name="postal_code" required></kashi-postal-code>
  <button class="k-btn k-btn--primary">ثبت سفارش</button>
</form>

رویدادها و JavaScript

هر فیلد با هر تغییر رویداد kashi-change می‌فرستد. در detail مقدار، معتبر بودن و اطلاعات اضافه می‌آید، مثل نام بانک یا اپراتور. ویژگی‌های value و valid را هم مستقیم می‌شود خواند:

const card = document.querySelector("kashi-card-number");
card.addEventListener("kashi-change", (e) => {
  console.log(e.detail); // { value: "6037…", valid: true, bank: "بانک ملی" }
});

card.value = "6037991234567893"; // مقدار از بیرون
card.valid; // true

رویدادها و ویژگی‌های JavaScript هر عنصر در بخش «وب کامپوننت» صفحهٔ همان کامپوننت آمده است.

Vue، Svelte و Angular

Vue: به Vue بگویید تگ‌های kashi- کامپوننت Vue نیستند:

// vite.config.js
import vue from "@vitejs/plugin-vue";

export default {
  plugins: [vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("kashi-") } } })],
};

<kashi-mobile :value="mobile" @kashi-change="mobile = $event.detail.value"></kashi-mobile>

Svelte: تنظیمی لازم ندارد:

<kashi-mobile value={mobile} on:kashi-change={(e) => (mobile = e.detail.value)}></kashi-mobile>

Angular: CUSTOM_ELEMENTS_SCHEMA را به کامپوننت اضافه کنید:

@Component({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<kashi-mobile [value]="mobile" (kashi-change)="mobile = $event.detail.value"></kashi-mobile>`,
})

در TypeScript نوع همهٔ عنصرها ثبت شده است؛ document.querySelector("kashi-iban") نوع KashiIban را برمی‌گرداند.

کامپوننت‌های دیگر

بیشتر کامپوننت‌های دیگر کاشی (دکمه، کارت، نشان، هشدار، آکاردئون، مراحل، پیشرفت، فیلد متنی و…) به JavaScript نیاز ندارند و با کلاس‌های @kashi-ui/css ساخته می‌شوند؛ کد HTML هر کدام در تب «HTML» صفحهٔ همان کامپوننت آمده است.

همهٔ کامپوننت‌های تعاملی کاشی نسخهٔ وب کامپوننت دارند.

حجم

فایل CDN حدود ۳ کیلوبایت (gzip) است و هر بخش را فقط وقتی یکی از تگ‌هایش در صفحه پیدا شود دانلود می‌کند؛ صفحه‌ای که فقط فیلد کد ملی دارد، نمودار و نقشه را دانلود نمی‌کند. لوگوی بانک‌ها هم فقط هنگام وارد کردن شمارهٔ کارت یا شبا می‌آید. اگر عنصرها را با JavaScript می‌سازید و می‌خواهید از همان اول آماده باشند، loadAll() را صدا بزنید:

import { loadAll } from "https://cdn.jsdelivr.net/npm/@kashi-ui/elements/dist/cdn/kashi-elements.js";
await loadAll();

با npm فقط بخشی را که لازم دارید وارد کنید (ستون «بخش npm» جدول بالا)؛ مثلاً فقط فیلدهای فارسی:

import "@kashi-ui/elements/inputs.js";