Input
حقل نص من سطر واحد. حجمان وثلاث تعبئات وبادئة ولاحقة، وكل الحالات: التمرير والتركيز والتعبئة والقراءة فقط والتعطيل والخطأ.
الإصدار 0.4.1 ·
التثبيت
bunx --bun shadcn@latest add @dga/inputويثبّت Field أيضًا.
الاستخدام
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
export function NameField() {
return (
<Field name="name">
<FieldLabel required>الاسم الكامل</FieldLabel>
<Input required autoComplete="name" />
<FieldDescription>كما يظهر في بطاقة الهوية.</FieldDescription>
</Field>
);
}استخدم Input للإجابات القصيرة من سطر واحد: الأسماء والهويات وعناوين البريد وأرقام الهاتف. اضبط type وinputMode للوحة مفاتيح مناسبة، وautoComplete ليتمكن المتصفح من التعبئة. وللأرقام التي تزيد وتنقص استخدم Number Input، وللنص متعدد الأسطر استخدم Textarea.
البنية
- الإطار (
<div>): الحد والتعبئة والظل والخط السفلي. - عنصر البداية (اختياري): أيقونة أو بادئة قصيرة مثل
+966. - Input (
<input>): النص. - عنصر النهاية (اختياري): أيقونة أو لاحقة أو زر.
أمثلة
الأحجام
lg بارتفاع 40px (الافتراضي)، وmd بارتفاع 32px.
التعبئات
قيمة appearance إما default أو lighter أو darker. وكما في DGA لا حدّ للتعبئتين الأفتح والأغمق في حالة السكون، ويظهر الحد عند التمرير والتركيز والضغط. وتعرضها الحالات أدناه كلها.
البادئة واللاحقة
يقبل startAdornment وendAdornment أيقونة أو نصًا، ويقعان في جهتي البداية والنهاية المنطقيتين. وتبقى أرقام الهاتف والبريد من اليسار إلى اليمين بـ dir="ltr".
RTL
يبدأ النص والنص التلميحي والعناصر الجانبية من اليمين. ويُحاذى النص العربي المكتوب إلى اليمين، ويُحاذى النص اللاتيني (كالبريد) بحسب dir="ltr" عند ضبطه.
إمكانية الوصول
| المفتاح | الإجراء |
|---|---|
| Tab | ينقل التركيز إلى الحقل. |
| Shift + Tab | يعيد التركيز إلى الخلف. |
- عنصر
<input>أصلي: سمّه دائمًا بـ Field؛ فالنص التلميحي ليس تسمية. - لا يوجد حد خارجي للتركيز. التمرير يُغمّق الحد. والضغط (بالفأرة أو اللمس) يعرض تعبئة الضغط وخطًا سفليًا بسمك 2px بنصف العرض ينمو من الوسط. والتركيز (بالفأرة أو لوحة المفاتيح) يعرض لون حد الضغط والخط السفلي بعرضه الكامل و
shadow-md(بلا ظل في الوضع الداكن). وينمو الخط السفلي من الوسط إلى الجهتين في LTR وRTL معًا، وبنسبة 3:1 على الأقل على كل تعبئة. - الحد الافتراضي بنسبة 3:1 أو أفضل مقابل الصفحة، فاتحًا وداكنًا (WCAG 1.4.11). وانظر الاختلافات للحالتين اللتين لا تبلغانها.
- يضبط الخطأ
aria-invalidويعرض أيقونة مع الرسالة. تبقى الحقول للقراءة فقط قابلة للتركيز، والمعطّلة لا. - أيقونات العناصر الجانبية زخرفية (
aria-hidden). وزر اللاحقة يحتاجaria-labelخاصًا به.
مرجع API
Input
حقل نص من سطر واحد داخل إطار. سمّه بـ Field. استخدم `type="email"` أو `"tel"` أو `"url"` أو `"password"` للوحة المفاتيح والتعبئة التلقائية المناسبة.
| الخاصية | النوع | القيمة الافتراضية |
|---|---|---|
stringنوع الحقل: `text` أو `email` أو `tel` أو `url` أو `password` وغيرها. | لا توجد قيمة افتراضية | |
| ||
"md" | "lg"الارتفاع: `md` 32px، و`lg` 40px. | "lg" | |
| ||
"default" | "lighter" | "darker"التعبئة: `default` (أبيض) أو `lighter` أو `darker`. وتحتفظ الثلاث بحد ظاهر. | "default" | |
| ||
string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<AwaitedReactNode>أيقونة أو بادئة قصيرة (مثل `+966`) قبل النص، في جهة البداية. | لا توجد قيمة افتراضية | |
| ||
string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<AwaitedReactNode>أيقونة أو لاحقة نصية أو زر بعد النص، في جهة النهاية. | لا توجد قيمة افتراضية | |
| ||
stringأصناف CSS للعنصر `<input>` نفسه. أما `className` فيصمّم الإطار المحيط به. | لا توجد قيمة افتراضية | |
| ||
string | numberالقيمة الابتدائية عند عدم التحكم. | لا توجد قيمة افتراضية | |
| ||
booleanيعطّل الحقل. | لا توجد قيمة افتراضية | |
| ||
(value: string, details) => voidتُستدعى بالنص الجديد كلما تغيّر. من Base UI. | لا توجد قيمة افتراضية | |
| ||
stringنص تلميحي يظهر والحقل فارغ. | لا توجد قيمة افتراضية | |
| ||
booleanيمكن قراءة النص ونسخه لكن لا يمكن تغييره. | لا توجد قيمة افتراضية | |
| ||
booleanلا يمكن إرسال النموذج والحقل فارغ. | لا توجد قيمة افتراضية | |
| ||
string | numberقيمة متحكَّم بها. | لا توجد قيمة افتراضية | |
| ||
يقبل أيضًا جميع خصائص Base UI Input (يفتح في نافذة جديدة).
الاختلافات عن DGA
- الحد الافتراضي هو neutral-500 لا neutral-400 (2.6:1 على الأبيض)، ليمكن العثور على الحقل في حالة السكون.
- النص التلميحي neutral-500 كما في DGA؛ ولا يستخدم neutral-600 إلا على تعبئتي الضغط والأغمق (4.34:1).
- حد الخطأ هو error-600 (كما في CSS الحي لـ DGA) لا error-700 في Figma.
- يعرض الحقل للقراءة فقط الخط السفلي عند التركيز، لأنه ما زال ضمن ترتيب Tab.
- فجوات معروفة، تُركت كما ترسمها DGA: حد القراءة فقط (1.5:1) والتعبئتان الأفتح والأغمق في حالة السكون (من 1.0 إلى 1.1:1).
| التغيير | السبب |
|---|---|
--field-border-default (light) | DGA draws the default field border in neutral-400 (#9da4ae), which is 2.58:1 on a white field. The default field has a white fill on a white or near-white page, so the border is the only thing that marks its boundary at rest (WCAG 1.4.11, 3:1). Neutral-500 is 4.83:1 on white. Kept only for this reason; hover, focus and press use the DGA colours. Dark mode already passes. |
--field-border-error (light) | Figma binds the error border to red-700 (#b42318); the live DGA CSS (--form-field-border-error) is error-600 (#d92d20), 4.77:1 on white, which still passes 3:1 as a border and 4.5:1 as the required marker. Follows the live DGA colour. |
--field-text-placeholder-tinted (new) | The DGA placeholder (neutral-500, #6c737f) is 4.83:1 on white but 4.34:1 on the filled darker fill and the pressed fill (#f3f4f6), under 4.5:1. Only those two states use this token (neutral-600, 6.2:1); everywhere else the placeholder is the DGA colour. |
Input, Textarea, Select: read-only focus | A read-only field is still in the tab order, and a focused element needs a visible indicator (WCAG 2.4.7). Without an outline, the underline is the indicator. |
عرض جميع الاختلافات (6) لهذا المكوّن أسباب الاختلافات مكتوبة بالإنجليزية.
التباين
270 زوجًا لونيًا فُحص · جميعها تجتاز WCAG 2.1 AAعرض 45 حالةإخفاء
| النمط / الحالة | الفاتح | الداكن |
|---|---|---|
| filled text | 18.09:1 AAA | 15.87:1 AAA |
| hovered text | 18.09:1 AAA | 15.87:1 AAA |
| focused text | 10.17:1 AAA | 12.04:1 AAA |
| pressed text | 9.24:1 AAA | 9.64:1 AAA |
| pressed placeholder | 6.69:1 AA | 5.06:1 AA |
| pressed prefix and suffix text | 9.24:1 AAA | 9.64:1 AAA |
| underline, focused and pressed | 18.74:1 3:1 | 16.80:1 3:1 |
| placeholder | 4.77:1 AA | 6.32:1 AA |
| prefix and suffix text | 10.17:1 AAA | 12.04:1 AAA |
| icon | 4.77:1 3:1 | 9.38:1 3:1 |
| border, default | 4.57:1 3:1 | 3.80:1 3:1 |
| border, hovered | 9.73:1 3:1 | 12.04:1 3:1 |
| border, focused and pressed | 17.93:1 3:1 | 16.80:1 3:1 |
| underline, error | 4.62:1 3:1 | 4.65:1 3:1 |
| border, error | 4.62:1 3:1 | 4.65:1 3:1 |
| filled text (lighter) | 17.64:1 AAA | 14.42:1 AAA |
| hovered text (lighter) | 17.64:1 AAA | 14.42:1 AAA |
| focused text (lighter) | 10.17:1 AAA | 12.04:1 AAA |
| pressed text (lighter) | 9.24:1 AAA | 9.64:1 AAA |
| pressed placeholder (lighter) | 6.69:1 AA | 5.06:1 AA |
| pressed prefix and suffix text (lighter) | 9.24:1 AAA | 9.64:1 AAA |
| underline, focused and pressed (lighter) | 18.28:1 3:1 | 15.27:1 3:1 |
| placeholder (lighter) | 4.65:1 AA | 5.75:1 AA |
| prefix and suffix text (lighter) | 9.92:1 AAA | 10.95:1 AAA |
| icon (lighter) | 4.65:1 3:1 | 8.52:1 3:1 |
| border, hovered (lighter) | 9.73:1 3:1 | 12.04:1 3:1 |
| border, focused and pressed (lighter) | 17.93:1 3:1 | 16.80:1 3:1 |
| underline, error (lighter) | 4.62:1 3:1 | 4.65:1 3:1 |
| border, error (lighter) | 4.62:1 3:1 | 4.65:1 3:1 |
| filled text (darker) | 16.44:1 AAA | 17.04:1 AAA |
| hovered text (darker) | 16.44:1 AAA | 17.04:1 AAA |
| focused text (darker) | 10.17:1 AAA | 12.04:1 AAA |
| pressed text (darker) | 9.24:1 AAA | 9.64:1 AAA |
| pressed placeholder (darker) | 6.69:1 AA | 5.06:1 AA |
| pressed prefix and suffix text (darker) | 9.24:1 AAA | 9.64:1 AAA |
| underline, focused and pressed (darker) | 17.03:1 3:1 | 18.03:1 3:1 |
| placeholder (darker) | 6.69:1 AA | 6.79:1 AA |
| prefix and suffix text (darker) | 9.24:1 AAA | 12.93:1 AAA |
| icon (darker) | 4.34:1 3:1 | 10.07:1 3:1 |
| border, hovered (darker) | 9.73:1 3:1 | 12.04:1 3:1 |
| border, focused and pressed (darker) | 17.93:1 3:1 | 16.80:1 3:1 |
| underline, error (darker) | 4.62:1 3:1 | 4.65:1 3:1 |
| border, error (darker) | 4.62:1 3:1 | 4.65:1 3:1 |
| border, hover and focus (lighter and darker) | 4.57:1 3:1 | 3.80:1 3:1 |
| read-only text | 18.09:1 AAA | 15.87:1 AAA |
يحتاج النص إلى تباين 4.5:1، والأيقونات وحلقات التركيز إلى 3:1. الحالات المعطّلة مستثناة. تقرير التباين الكامل