> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ImageInput

> إجراءات اختيار الصورة ومعاينتها ورفعها التي يملكها المستدعي.

## نظرة عامة

يجمع `ImageInput` بين معاينة الصورة ومنتقي الملفات الأصلي وإجراءات الرفع أو الإزالة أو الإلغاء. يتم تشغيل `onFileSelect` عند اختيار ملف. يتحقق تطبيقك من الملف ويرفعه، ويمتلك تقدّم الرفع وإلغاءه، ويوفر عنوان URL للمعاينة عبر `src`.

**Light**

[اختر صورة وعاينها وأزلها (light)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[اختر صورة وعاينها وأزلها (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-imageinput--display)

## استخدام

```tsx theme={null}
import { useState } from 'react';
import { ImageInput } from 'twenty-ui/components/input';

export const WorkspaceImage = () => {
  const [preview, setPreview] = useState<{
    src?: string;
    reader?: FileReader;
  }>({});

  return (
    <ImageInput
      helperText="Choose a square image for your workspace."
      src={preview.src}
      onFileSelect={(file) => {
        const reader = new FileReader();
        setPreview((current) => ({ src: current.src, reader }));
        reader.onload = () => {
          setPreview((current) => {
            if (current.reader !== reader) {
              return current;
            }

            return { src: reader.result?.toString() };
          });
        };
        reader.readAsDataURL(file);
      }}
      onRemove={() => setPreview({})}
    />
  );
};
```

يحتفظ المثال بالمعاينة الحالية أثناء قراءة بديل، ويتجاهل القراءات الناتجة عن التحديدات المُزالة أو المستبدلة.

## الاختيار والمعاينة

تفتح المعاينة وزر الرفع منتقي الملفات الأصلي نفسه. يتلقى `onFileSelect` العنصر `File` المحدد؛ ولا يبدأ عملية رفع بنفسه. يؤدي الإلغاء أو إرجاع اختيار فارغ إلى إبقاء الصورة الحالية دون تغيير. يُمسح إدخال الملف بعد الاختيار بحيث يمكن اختيار الملف نفسه مجددًا، ويظل `File` الخاص بدالة الاستدعاء قابلًا للاستخدام.

تدعم مكونات الواجهة التحديد الأصلي ومحتويات `File` القابلة للقراءة. تم التحقق من تدفقات React وPreact المُنشأة بواسطة SDK في Chromium باستخدام التفعيل بالمؤشر وEnter وSpace. لا يُفتح المنتقي إلا عبر نقرة موثوقة داخل المكون. تدعم عناوين URL للكائنات التي ينشئها Worker والمُسندة إلى `src` للصورة المعاينات.

تكون القيمة الافتراضية لـ `accept` هي `image/*`، وهو يرشح منتقي الملفات. تحقق من التنسيقات والأبعاد والحجم المسموح بها في تطبيقك. لا يحتفظ هذا المحدد المعتمد على الاستدعاءات بملف لإرساله عبر النموذج الأصلي. تستخدم أزرار إجراءاته `type="button"`، لذا لا ترسل نموذجًا محيطًا.

تعرض الصورة الفارغة أو التي فشل تحميلها عنصرًا نائبًا. يؤدي تغيير `src` إلى إعادة محاولة المعاينة، بما في ذلك بعد فشل تحميل صورة سابقة. تستدعي الإزالة `onRemove`؛ حدّث `src` بعد أن يزيل تطبيقك الصورة. يمتلك التطبيق عناوين URL للمعاينة المحلية ويلغي عناوين URL للكائنات التي ينشئها العامل عندما لا تعود مطلوبة. يمتلك العارض تنظيف عناوين URL لمعاينة مضيفه.

## خصائص الجذر وإدخال الملف

تُطبّق `className` و`style` و`ref` على عنصر div الجذر. يتلقى مرجع الجذر الافتراضي عنصر `HTMLDivElement`؛ استخدم `inputRef` لإدخال الملف المخفي. استخدم `render={<div ... />}` لتوفير سمات الجذر الأصلية أو معالجات الأحداث. أبقِ ذلك الجذر غير تفاعلي، لأن الوحدة تحتوي بالفعل على أزرار. يُطبّق `dir` على كل من الجذر وإدخال الملف؛ استخدم `dir="rtl"` للتخطيط من اليمين إلى اليسار.

تكون سمات إدخال الملف الأصلية خصائص على المستوى الأعلى، بما في ذلك `accept` و`capture` و`name` و`id` و`title` و`form` و`required` والسمات القابلة للوصول وسمات البيانات ومعالجات الأحداث. تُطبّق على الإدخال المخفي. يتلقى `inputRef` عنصر `HTMLInputElement` الخاص به. يستخدم عنصر التحكم دائمًا `type="file"`، ويقبل ملفًا واحدًا، ويعيد تعيين قيمته بعد كل اختيار. لا يمكن تخصيص `children` و`dangerouslySetInnerHTML` و`type` و`multiple` و`value` و`defaultValue` و`hidden`.

لا يزال التحقق الأصلي من `required` يرى إدخالًا فارغًا بعد الاختيار لأن الإدخال يُعاد تعيينه. تحقق من عمليات الرفع المكتملة في تطبيقك.

يتلقى `onChange` حدث التغيير الأصلي بينما لا يزال الإدخال يحتوي على الملف المحدد. ثم يُعاد تعيين الإدخال قبل تشغيل `onFileSelect`. تتبع خصائص الأحداث الأصلية عقد الإدخال في React. `onAbort` هو إجراء إيقاف الرفع.

## حالات الرفع والتعطيل

تجعل `isUploading` الجذر مشغولًا وتجعل الاختيار والإزالة غير متاحين. تبقى عناصر التحكم التي كانت متاحة قابلة للتركيز، لذلك لا يُفقد تركيز لوحة المفاتيح عند بدء الرفع. وفّر `onAbort` لاستبدال الرفع بالإلغاء أثناء الرفع. يعمل الإلغاء قبل وجود أول عنوان URL للصورة. يتولى التطبيق الإلغاء ويعيد تعيين `isUploading` إلى `false` عند انتهاء الرفع.

تعطّل `disabled` كل إجراء. يتطلب الاختيار `onFileSelect`. تتطلب الإزالة كلاً من `onRemove` و`src` غير فارغ.

**Light**

[رفع صورة مع إجراء إلغاء (light)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--uploading\&viewMode=story\&globals=colorScheme:light)

**Dark**

[رفع صورة مع إجراء إلغاء (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--uploading\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-imageinput--uploading)

## التسميات والإرشادات والأخطاء

وفّر سلاسل `uploadLabel` و`removeLabel` و`abortLabel` مترجمة محليًا. قيمها الافتراضية هي `Upload` و`Remove` و`Abort`. تسمّي تسمية الرفع أيضًا زر المعاينة وإدخال الملف المخفي. يمكن للسمات الأصلية القابلة للوصول توفير اسم مختلف لإدخال الملف. يصف `aria-describedby` أيضًا أزرار الاختيار ويتحد مع النص المساعد ونص الخطأ الخاصين بالتطبيق.

ينتمي `helperText` و`errorMessage` إلى التطبيق. يصف كلاهما عناصر التحكم في الاختيار، ويُعلن عن الأخطاء كتنبيهات. لا توجد حدود مضمّنة للملفات أو إرشادات للمنتج.

**Light**

[إدخال صورة مع إرشادات وخطأ (light)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--with-error\&viewMode=story\&globals=colorScheme:light)

**Dark**

[إدخال صورة مع إرشادات وخطأ (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--with-error\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-imageinput--with-error)

## الترحيل

استبدل `onUpload` بـ `onFileSelect`. أبقِ `accept` كخاصية على المستوى الأعلى. لا تزال دالة الاستدعاء تتلقى `File`؛ أبقِ رمز التحقق والرفع الحالي في تطبيقك.

```tsx theme={null}
import { ImageInput } from 'twenty-ui/components/input';

export const WorkspaceImageSelector = ({
  uploadImage,
}: {
  uploadImage: (file: File) => void;
}) => <ImageInput onFileSelect={uploadImage} accept="image/png, image/jpeg" />;
```

## الخصائص

**abortLabel** `string` (default: Abort)

Label for the Abort action.

**accept** `string` (default: image/\*)

Native file picker filter. Defaults to image/\*. The caller validates allowed formats.

**aria-describedby** `string`

Accessible description references for the hidden file input and selection buttons, combined with helperText and errorMessage.

**aria-label** `string`

Accessible name of the hidden file input. Defaults to uploadLabel.

**aria-labelledby** `string`

Accessible name reference for the hidden file input.

**capture** `boolean | "user" | "environment"`

Native device capture hint for the file picker.

**className** `string`

Class applied to the root element.

**dir** `string`

Text direction applied to both the root and hidden file input.

**disabled** `boolean` (default: false)

Disables file selection, removal, and abort actions.

**errorMessage** `string | null`

Application error, displayed as an alert and associated with the selection controls.

**form** `string`

Native form identifier associated with the hidden file input.

**helperText** `string`

Application instructions, associated with the selection controls.

**id** `string`

Native identifier of the hidden file input.

**inputRef** `Ref\<HTMLInputElement\>`

Ref to the hidden single-file HTMLInputElement.

**isUploading** `boolean` (default: false)

Marks the module busy. Selection and removal controls that would otherwise be enabled stay focusable but unavailable. Shows Abort when onAbort is supplied.

**name** `string`

Native name of the hidden file input.

**onAbort** `(() =\> void)`

Shows an abort action while uploading. It can cancel the first upload before a src exists.

**onChange** `ChangeEventHandler\<HTMLInputElement, HTMLInputElement\>`

Native file input change event, fired while the selected file is present and before the input resets. The input does not retain a file for form submission.

**onFileSelect** `((file: File) =\> void)`

Fires when a file is selected and receives its usable File after the input resets. Empty and canceled selections do not call it. Selection is disabled when omitted. The caller owns validation and uploading.

**onRemove** `(() =\> void)`

Requests removal of the current image. Removal is disabled without this callback or a nonempty src.

**ref** `Ref\<HTMLDivElement\>`

Ref to the root div element.

**removeLabel** `string` (default: Remove)

Label for the Remove action.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, \{\}\>`

Custom root element or render function. Supply root native attributes here and keep a non-interactive root.

**required** `boolean`

Native file input requirement. The input resets after selection, so the caller validates completed uploads.

**src** `string | null`

Resolved image URL. Empty or failed images show the image placeholder.

**style** `CSSProperties`

Inline style applied to the root element.

**title** `string`

Native title of the hidden file input.

**uploadLabel** `string` (default: Upload)

Label for the preview, Upload action, and hidden file input.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.