تخطَّ إلى المحتوى

Textarea

حقل نص متعدد الأسطر يمكن للمستخدم تغيير حجمه. ثلاث تعبئات وكل الحالات: التمرير والتركيز والتعبئة والقراءة فقط والتعطيل والخطأ.

الإصدار 0.4.1 ·

حالات حقل النص المتعدد

التثبيت

bunx --bun shadcn@latest add @dga/textarea

ويثبّت Field أيضًا.

الاستخدام

page.tsx
tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Textarea } from "@/components/ui/textarea";

export function DetailsField() {
  return (
    <Field name="details">
      <FieldLabel required>تفاصيل الطلب</FieldLabel>
      <Textarea required rows={4} />
      <FieldDescription>اذكر رقم القطعة واسم الشارع.</FieldDescription>
    </Field>
  );
}

استخدم Textarea للإجابات التي تحتاج أكثر من سطر: الأوصاف والتعليقات والأسباب. اضبط rows للارتفاع الابتدائي. اذكر الحد الأقصى في النص المساعد، ولا تقتطع النص بصمت.

البنية

  • Textarea (<textarea>): الحد والتعبئة والنص ومقبض تغيير الحجم في عنصر واحد.
  • شريط التمرير هو شريط المتصفح نفسه؛ يظهر عندما يزيد النص عن ارتفاع الصندوق.

أمثلة

الحالات

الافتراضية والمعبأة وللقراءة فقط والمعطّلة وحالة الخطأ، مع التعبئة الأغمق دون تغيير الحجم.

الحالات

تغيير الحجم

resize="vertical" (الافتراضي) يعرض مقبضًا في زاوية النهاية. استخدم resize="none" عندما يتطلب التخطيط ارتفاعًا ثابتًا. ولا يتغير عرض الحقل جانبيًا أبدًا.

page.tsx
tsx
<Textarea resize="none" rows={6} />

RTL

يبدأ النص من اليمين ويقع مقبض تغيير الحجم في الزاوية السفلية اليسرى. ويتبع كل شيء اتجاه الصفحة.

LTR (الإنجليزية)
RTL (العربية)

إمكانية الوصول

المفتاحالإجراء
Tabينقل التركيز إلى الحقل.
Enterيبدأ سطرًا جديدًا.
  • عنصر <textarea> أصلي مرتبط بتسمية Field ونصه المساعد وخطئه.
  • الحالات نفسها كما في Input: ينمو الخط السفلي من الوسط عند الضغط (نصفًا) وعند التركيز (كاملًا)، ولا يوجد حد خارجي. ويحمل عنصر <div> الغلاف الحد والخط السفلي لأن <textarea> لا يستطيع رسمهما.
  • يمكن سحب مقبض تغيير الحجم بالمؤشر. ويحصل مستخدمو لوحة المفاتيح على المساحة نفسها بالكتابة؛ أعطِ rows ارتفاعًا يكفي للإجابة المتوقعة.
  • إن عرضت حدًا للأحرف فضعه في النص المساعد واستخدم maxLength ليُفرض.

مرجع API

Textarea

حقل نص متعدد الأسطر يزداد ارتفاعه (وقابل لتغيير الحجم افتراضيًا). سمّه بـ Field. يرتبط بتسمية Field ونصه المساعد وخطأه كأي عنصر تحكم آخر.

خصائص Textarea
الخاصيةالنوعالقيمة الافتراضية
"default" | "lighter" | "darker"

التعبئة: `default` (أبيض) أو `lighter` أو `darker`. وتحتفظ الثلاث بحد ظاهر.

"default"
"vertical" | "none"

`vertical` يتيح للمستخدم سحب الزاوية لتغيير الارتفاع. و`none` يثبّته.

"vertical"
string

أصناف الإطار المحيط بالحقل (الحد والتعبئة والخط السفلي).

لا توجد قيمة افتراضية
string

أصناف عنصر `<textarea>` الأصلي.

لا توجد قيمة افتراضية
number

عدد الأسطر الظاهرة، وهو يحدد الارتفاع الابتدائي.

4
string

القيمة الابتدائية عند عدم التحكم.

لا توجد قيمة افتراضية
boolean

يعطّل الحقل.

لا توجد قيمة افتراضية
string

نص تلميحي يظهر والحقل فارغ.

لا توجد قيمة افتراضية
boolean

يمكن قراءة النص ونسخه لكن لا يمكن تغييره.

لا توجد قيمة افتراضية
boolean

لا يمكن إرسال النموذج والحقل فارغ.

لا توجد قيمة افتراضية
string

قيمة متحكَّم بها.

لا توجد قيمة افتراضية

يقبل أيضًا جميع خصائص Base UI Field (يفتح في نافذة جديدة).

الاختلافات عن DGA

  • في Figma نسخة واحدة بارتفاع ثابت. أما هذا الحقل فيكبر بحسب rows ويمكن تغيير حجمه.
  • لا حدّ للتعبئتين الأفتح والأغمق في حالة السكون، كما في Input، بما في ذلك الفجوة المعروفة.
التغييرالسبب
Textarea: sizeA multi-line field has no single right height. Figma's Resize and Scroll Bar props map to resize and the native scroll bar.

عرض جميع الاختلافات (1) لهذا المكوّن أسباب الاختلافات مكتوبة بالإنجليزية.

التباين

276 زوجًا لونيًا فُحص · جميعها تجتاز WCAG 2.1 AAعرض 46 حالة
النمط / الحالةالفاتحالداكن
filled text18.09:1 AAA15.87:1 AAA
hovered text18.09:1 AAA15.87:1 AAA
focused text10.17:1 AAA12.04:1 AAA
pressed text9.24:1 AAA9.64:1 AAA
pressed placeholder6.69:1 AA5.06:1 AA
pressed prefix and suffix text9.24:1 AAA9.64:1 AAA
underline, focused and pressed18.74:1 3:116.80:1 3:1
placeholder4.77:1 AA6.32:1 AA
prefix and suffix text10.17:1 AAA12.04:1 AAA
icon4.77:1 3:19.38:1 3:1
border, default4.57:1 3:13.80:1 3:1
border, hovered9.73:1 3:112.04:1 3:1
border, focused and pressed17.93:1 3:116.80:1 3:1
underline, error4.62:1 3:14.65:1 3:1
border, error4.62:1 3:14.65:1 3:1
filled text (lighter)17.64:1 AAA14.42:1 AAA
hovered text (lighter)17.64:1 AAA14.42:1 AAA
focused text (lighter)10.17:1 AAA12.04:1 AAA
pressed text (lighter)9.24:1 AAA9.64:1 AAA
pressed placeholder (lighter)6.69:1 AA5.06:1 AA
pressed prefix and suffix text (lighter)9.24:1 AAA9.64:1 AAA
underline, focused and pressed (lighter)18.28:1 3:115.27:1 3:1
placeholder (lighter)4.65:1 AA5.75:1 AA
prefix and suffix text (lighter)9.92:1 AAA10.95:1 AAA
icon (lighter)4.65:1 3:18.52:1 3:1
border, hovered (lighter)9.73:1 3:112.04:1 3:1
border, focused and pressed (lighter)17.93:1 3:116.80:1 3:1
underline, error (lighter)4.62:1 3:14.65:1 3:1
border, error (lighter)4.62:1 3:14.65:1 3:1
filled text (darker)16.44:1 AAA17.04:1 AAA
hovered text (darker)16.44:1 AAA17.04:1 AAA
focused text (darker)10.17:1 AAA12.04:1 AAA
pressed text (darker)9.24:1 AAA9.64:1 AAA
pressed placeholder (darker)6.69:1 AA5.06:1 AA
pressed prefix and suffix text (darker)9.24:1 AAA9.64:1 AAA
underline, focused and pressed (darker)17.03:1 3:118.03:1 3:1
placeholder (darker)6.69:1 AA6.79:1 AA
prefix and suffix text (darker)9.24:1 AAA12.93:1 AAA
icon (darker)4.34:1 3:110.07:1 3:1
border, hovered (darker)9.73:1 3:112.04:1 3:1
border, focused and pressed (darker)17.93:1 3:116.80:1 3:1
underline, error (darker)4.62:1 3:14.65:1 3:1
border, error (darker)4.62:1 3:14.65:1 3:1
border, hover and focus (lighter and darker)4.57:1 3:13.80:1 3:1
read-only text18.09:1 AAA15.87:1 AAA
border, resize handle4.57:1 3:13.80:1 3:1

يحتاج النص إلى تباين 4.5:1، والأيقونات وحلقات التركيز إلى 3:1. الحالات المعطّلة مستثناة. تقرير التباين الكامل