ورودی (Input)

معرفی

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

چه زمانی استفاده نکنیم:

• برای متن چند خطی — از Textarea استفاده کنید
• برای انتخاب از لیست — از Select یا Autocomplete استفاده کنید
• برای جستجو با قابلیت autocomplete — از SearchInput استفاده کنید

استفاده

import { Input } from '@partodata/ui'

<Input placeholder="نام خود را وارد کنید" />

زمین بازی

با تغییر تنظیمات زیر، ورودی را به صورت زنده مشاهده کنید.

import { Input } from '@partodata/ui'

<Input size="sm" placeholder="متن راهنما..." />

اندازه‌ها

کامپوننت Input از پنج اندازهٔ نردبان کنترل‌ها پشتیبانی می‌کند. اندازهٔ پیش‌فرض md (38 پیکسل، متن 14) است، اندازهٔ فیلد فرم؛ در نوار ابزار صفحه (PageToolbar)، FilterBar و سرِ کارت‌ها و سربرگ‌ها همان ردیف آن را sm (30 پیکسل) می‌کند تا با دکمه‌ها هم‌قد باشد (اندازه و تراکم).

<Input size="xs" placeholder="اندازه xs" />
<Input size="sm" placeholder="اندازه sm (نوار ابزار)" />
<Input size="md" placeholder="اندازه md (پیش‌فرض)" />
<Input size="lg" placeholder="اندازه lg" />
<Input size="xl" placeholder="اندازه xl" />

نوع فیلد (kind)

ایمیل، رمز، نشانی وب، تلفن و بقیه هر کدام یک kind دارند و در همهٔ محصولات همان فیلدند. kind نوع ورودی، صفحه‌کلید موبایل، تکمیل خودکار، غلط‌یاب و جهت را می‌گذارد: مقدار لاتین (ایمیل، نشانی، تلفن، رمز، نام کاربری، عدد) در فرم فارسی هم چپ‌به‌راست و چپ‌چین است، و password دکمهٔ نمایش رمز را خودش دارد. type و dir و autoComplete را دستی ننویسید؛ قاعدهٔ parto/input-kind همین را گوشزد می‌کند.

<Input kind="email" />
<Input kind="password" autoComplete="new-password" /> {/* ثبت‌نام: هر ویژگی صریح بر پیش‌فرض kind می‌چربد */}

پیشوند و پسوند (startAdornment، endAdornment)

متن ثابت (https://، واحد پول)، آیکون یا دکمه‌ای کنار مقدار، همه با همین دو ویژگی ساخته می‌شوند؛ حلقهٔ فوکوس و مرز روی کل فیلد است و فاصلهٔ متن از آدورنمنت را خود Input اندازه می‌گیرد. InputGroup مدل دوم همین کار بود و منسوخ است.

import { Button, Input } from '@partodata/ui'
import { Search } from 'lucide-react'

<Input kind="url" startAdornment="https://" placeholder="example.com" />
<Input kind="search" startAdornment={<Search aria-hidden="true" />} placeholder="نام حساب" />
{/* مقدار عددی چپ‌به‌راست است؛ واحد در ابتدای آن می‌نشیند تا در خواندن راست‌به‌چپ پس از عدد بیاید */}
<Input kind="number" startAdornment="تومان" />
<Input kind="url" readOnly value={link} endAdornment={<Button size="xs" variant="ghost">کپی</Button>} />

عنوان یا توضیح بالای فیلد آدورنمنت نیست: آن‌ها label و description در FormRow هستند.

غیرفعال

با برچسب

Props

کلاس‌بندی wrapper با آدورنمنت

وقتی startAdornment یا endAdornment می‌دهید، یک عنصر wrapper دور ورودی رندر می‌شود و همان چیدمان (عرض، margin, جایگذاری در grid) را کنترل می‌کند — نه خود <input>. className همیشه فقط روی <input> می‌نشیند؛ برای این کلاس‌های چیدمانی از wrapperClassName استفاده کنید، وگرنه فیلد از آدورنمنت جدا به نظر می‌رسد:

import { Search } from 'lucide-react'

// درست — عرض روی wrapper است، آدورنمنت با فیلد هم‌تراز می‌ماند
;<Input wrapperClassName="w-64" endAdornment={<Search className="size-4" />} />

// نادرست — عرض روی خود input است، wrapper همچنان تمام‌عرض می‌ماند
;<Input className="w-64" endAdornment={<Search className="size-4" />} />

دسترسی‌پذیری

برای فرم‌های معتبرسنجی، از aria-invalid و aria-describedby استفاده کنید تا خطاها برای کاربران صفحه‌خوان قابل درک باشند:

<div>
  <Input aria-invalid="true" aria-describedby="email-error" value="invalid@" />
  <p id="email-error" className="text-destructive text-sm mt-1">
    آدرس ایمیل معتبر نیست
  </p>
</div>

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

کامپوننت‌های مرتبط

• Textarea — برای ورودی چند خطی
• Select — اگر کاربر باید از بین گزینه‌های از پیش‌تعریف‌شده انتخاب کند، نه متن آزاد بنویسد
• Autocomplete — اگر ورودی متنی به جستجو و پیشنهاد خودکار بین گزینه‌ها نیاز دارد
• SearchInput — برای جستجو با آیکون و clear button
• Form — وقتی چند فیلد دارید و اعتبارسنجی، label و پیام خطا باید یکپارچه مدیریت شوند
• راهنمای انتخاب کامپوننت — مقایسه همه ورودی‌ها