الفتحات

في FileUploader عدد 13 من الفتحات. مرّر بديلًا لأي منها في components، وكل فتحة لا تمرّرها تبقى على بديلها الافتراضي. فتحات العناصر تستقبل خصائص DOM فيناسبها عنصر المكتبة كما هو، وفتحات الأدوات تستقبل خصائص مسمّاة وتحتاج عادة إلى بضعة أسطر من المحوّل.

الاسمالنوعالخصائص التي تستقبلهاالبديل الافتراضيسمات data-*
Root<element>

خصائص DOM: HTMLAttributes<HTMLDivElement>

مصدر البديل
const Root = ({ className, ...props }: UploaderRootSlotProps) => (
  <div className={cx("sfu", className)} {...props} />
);
  • data-disabled
  • data-dragging
  • data-empty
  • data-variant
Dropzone<element>

خصائص DOM: HTMLAttributes<HTMLDivElement>

مصدر البديل
const Dropzone = ({ className, ...props }: DropzoneSlotProps) => (
  <div className={cx("sfu__zone", className)} {...props} />
);
  • data-disabled
  • data-dragging
Input<element>

خصائص DOM: InputHTMLAttributes<HTMLInputElement>

مصدر البديل
const Input = (props: UploaderInputSlotProps) => <input className="sfu__input" {...props} />;
—
Icon{widget}
  • dragging: boolean

    Whether a file is currently over the zone.

مصدر البديل
const Icon = ({ dragging }: UploaderIconSlotProps) => (
  <span className="sfu__icon" data-dragging={dragging || undefined}>
    <Glyph size={24}>
      <path d="M12 16V4" />
      <path d="m7 9 5-5 5 5" />
      <path d="M4 16v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2" />
    </Glyph>
  </span>
);
  • data-dragging
Empty{widget}
  • title: ReactNode
  • hint: ReactNode
  • dragging: boolean
مصدر البديل
const Empty = ({ title, hint, dragging }: UploaderEmptySlotProps) => (
  <span className="sfu__copy">
    <span className="sfu__title">{title}</span>
    {!dragging && <span className="sfu__hint">{hint}</span>}
  </span>
);
—
Trigger{widget}
  • onClick: () => void

    Opens the file dialog.

  • disabled: boolean
  • children: ReactNode
مصدر البديل
const Trigger = ({ onClick, disabled, children }: UploaderTriggerSlotProps) => (
  <button
    type="button"
    className="sfu__browse"
    disabled={disabled}
    onClick={(event) => {
      /** The zone itself opens the dialog; without this it would open twice. */
      event.stopPropagation();
      onClick();
    }}
  >
    {children}
  </button>
);
—
List<element>

خصائص DOM: HTMLAttributes<HTMLUListElement>

  • ref?: Ref<HTMLUListElement>
مصدر البديل
const List = ({ className, ...props }: UploaderListSlotProps) => (
  <ul className={cx("sfu__list", className)} {...props} />
);
—
Item<element>

خصائص DOM: LiHTMLAttributes<HTMLLIElement>

مصدر البديل
const Item = ({ className, ...props }: UploaderItemSlotProps) => (
  <li className={cx("sfu__item", className)} {...props} />
);
  • data-image
  • data-status
Thumbnail{widget}
  • item: UploadItem
  • src?: string

    The object URL, or the stored URL for restored items.

  • isImage: boolean

    Whether the item is an image.

  • alt: string

    Accessible name for the picture.

مصدر البديل
const Thumbnail = ({ src, isImage, alt }: ThumbnailSlotProps) => {
  const [broken, setBroken] = useState(false);
  return (
  <span className="sfu__thumb">
    {isImage && src && !broken ? (
      <img className="sfu__thumb-img" src={src} alt={alt} onError={() => setBroken(true)} />
    ) : (
      <Glyph>
        <path d="M14 3v4a1 1 0 0 0 1 1h4" />
        <path d="M17 21H7a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h7l5 5v11a2 2 0 0 1-2 2Z" />
      </Glyph>
    )}
  </span>
  );
};
—
ItemMeta{widget}
  • item: UploadItem
  • size: string

    The size, already formatted (2.4 MB). Empty for restored items.

  • status: ReactNode

    Status wording from the labels.

مصدر البديل
const ItemMeta = ({ item, size, status }: ItemMetaSlotProps) => (
  <span className="sfu__meta">
    <span className="sfu__name" title={item.name}>
      {item.name}
    </span>
    <span className="sfu__sub">
      {item.status === "error" ? (
        <span className="sfu__error">{item.error}</span>
      ) : (
        <>
          {size && <span>{size}</span>}
          {size && status ? <span aria-hidden="true">·</span> : null}
          {status}
        </>
      )}
    </span>
  </span>
);
—
Progress{widget}
  • value: number

    0–100.

  • active: boolean

    Whether the upload is in flight.

  • aria-label: string
مصدر البديل
const Progress = ({ value, active, ...aria }: UploaderProgressSlotProps) => (
  <span
    className="sfu__progress"
    role="progressbar"
    aria-valuenow={Math.round(value)}
    aria-valuemin={0}
    aria-valuemax={100}
    data-active={active || undefined}
    {...aria}
  >
    <span className="sfu__progress-bar" style={{ inlineSize: `${Math.max(0, Math.min(100, value))}%` }} />
  </span>
);
  • data-active
Action{widget}
  • action: "remove" | "retry" | "cancel"
  • onClick: () => void
  • disabled?: boolean
  • aria-label: string
مصدر البديل
const Action = ({ action, onClick, disabled, ...aria }: UploaderActionSlotProps) => (
  <button
    type="button"
    className="sfu__action"
    data-action={action}
    disabled={disabled}
    onClick={(event) => {
      /** Actions sit inside the clickable zone in tile mode. */
      event.stopPropagation();
      onClick();
    }}
    {...aria}
  >
    <Glyph size={16}>
      {action === "remove" && (
        <>
          <path d="M18 6 6 18" />
          <path d="m6 6 12 12" />
        </>
      )}
      {action === "retry" && (
        <>
          <path d="M21 12a9 9 0 1 1-3-6.7" />
          <path d="M21 4v5h-5" />
        </>
      )}
      {action === "cancel" && (
        <>
          <rect x="6" y="6" width="12" height="12" rx="1" />
        </>
      )}
    </Glyph>
  </button>
);
  • data-action
Rejections{widget}
  • rejections: Rejection[]
  • onDismiss: () => void
  • dismissLabel: string
مصدر البديل
const Rejections = ({ rejections, onDismiss, dismissLabel }: RejectionsSlotProps) => (
  <div className="sfu__rejections" role="status" aria-live="polite">
    <ul>
      {rejections.map((rejection, index) => (
        <li key={`${rejection.file.name}-${index}`}>{rejection.message}</li>
      ))}
    </ul>
    <button type="button" className="sfu__action" onClick={onDismiss} aria-label={dismissLabel}>
      <Glyph size={16}>
        <path d="M18 6 6 18" />
        <path d="m6 6 12 12" />
      </Glyph>
    </button>
  </div>
);
—

الخصائص

كل خصائص FileUploader مجمّعة كما في توثيق المكتبة. الحالة المتحكَّم بها تأتي أزواجًا: مرّر القيمة مع معالج تغييرها، أو القيمة الابتدائية وحدها لتبقى الحالة داخل المكوّن.

الاسمالنوعالافتراضيالوصف
Selection
acceptstring | string[]—
multipleboolean

false, like the native input

Allow more than one file. Defaults to false, like the native input.

maxFilesnumber—

How many items the list may hold in total.

maxSizenumber—
minSizenumber—
validate(file: File) => string | null | undefined—

Your own rule. Return a message to refuse the file, or nothing to allow it.

disabledboolean—

Nothing can be picked, dropped or removed.

Value
valueUploadItem<TData>[]—

Controlled items.

onValueChange(items: UploadItem<TData>[]) => void—

Called with the new items after every change.

defaultValueInitialValue<TData>—

Where an uncontrolled uploader starts: items, files or URLs.

onFilesChange(files: File[]) => void—

Convenience for picker mode: the picked files, whenever they change.

onUrlsChange(urls: string[]) => void—

Convenience for upload mode: the stored URLs, whenever they change.

namestring—

The form field name. A plain HTML form then submits every item under it: a file picked in the browser as the file, as <input type="file" name> would, and a file already on a server (restored from a URL, or uploaded) as its URL, so the server can tell what to keep.

Uploading
uploadUploadFn<TData>—

Sends one file. Omit it and nothing is ever uploaded — the component becomes a picker and items stay ready.

autoUploadbooleantrue

Start uploading as soon as files are picked. Defaults to true.

concurrencynumber3

How many uploads may run at once. Defaults to 3.

onUploaded(item: UploadItem<TData>) => void—

Called for each file that finished uploading.

onUploadError(error: unknown, item: UploadItem<TData>) => void—

Called when an upload fails.

onReject(rejections: Rejection[]) => void—

Called with the files the constraints turned away.

Rendering
variantFileUploaderVariantdropzone

How the component is laid out. Defaults to dropzone.

componentsPartial<FileUploaderComponents>—

Replace any part; the rest fall back to SlotsmithProvider's components.fileUploader, then to the built-in ones.

labelsPartial<FileUploaderLabels>—

Override any text. Wins over locale.

localeLocaleInput

the provider's

The language: a locale object, or the tag of one given to SlotsmithProvider. Defaults to the provider's.

validationLabelsPartial<ValidationLabels>—

Wording for rejection messages.

slotPropsFileUploaderSlotProps—

Extra DOM props for the element parts.

previewboolean | "auto"—

Object-URL previews for images. "auto" (the default) means images only.

hideListboolean—

Hide the item list, e.g. when you render the files yourself.

childrenReactNode—

Rendered inside the drop zone, under the title.

captureWindowDropsboolean—

Swallow drops that miss the drop zone, so the browser doesn't open the file.

virtualFileUploaderVirtualOptions—

Renders only the items in view, for batches of hundreds: pass the virtualizer hook (useVirtualizer from @tanstack/react-virtual) as use, and the sizes.

تُمرَّر أي خاصية أخرى إلى العنصر الجذر <div>.

النصوص واللغات

كل نص يعرضه FileUploader أو يعلنه، مع قيمته الافتراضية بالإنجليزية. مرّر labels لتغيير بعضها في مكوّن واحد، أو locale لتحويل كل النصوص إلى لغة أخرى. العرض أدناه يفعل الأمرين.

المفتاحالنوعالافتراضي بالإنجليزيةالوصف
titleReactNode"Drag and drop, or browse"

The drop zone's headline.

hint(limits: { accept?: string; maxSize?: string; maxFiles?: number }) => ReactNodehint({ accept: "image/*,.pdf", maxSize: "5 MB", maxFiles: 3 })

يطبع "image/*, .pdf · up to 5 MB · max 3 files"

The line under it; the default names the limits.

dropHereReactNode"Drop to add"

While a file is over the zone.

browseReactNode"Browse"

The browse button.

dropzonestring"Add files"

Accessible name of the drop zone.

removestring"Remove file"
retrystring"Retry upload"
cancelstring"Cancel upload"
progress(name: string) => stringprogress("photo.jpg")

يطبع "Uploading photo.jpg"

Accessible name of an item's progress bar.

readyReactNode"Ready"

Status wording per item state.

uploadingReactNode"Uploading…"
doneReactNode"Uploaded"
failedReactNode"Failed"
preview(name: string) => stringpreview("photo.jpg")

يطبع "Preview of photo.jpg"

Accessible name for a preview.

dismissstring"Dismiss"

Dismisses the rejection list.

rejectedTitle(count: number) => ReactNoderejectedTitle(3)

يطبع "3 files not added"

Announced when files are refused.

رسائل التحقق

رسائل الملفات التي ترفضها القيود، وهي قسم ثانٍ من النصوص. مرّر validationLabels لتغيير بعضها في مكوّن واحد، وحزمة locale تترجمها مع بقية النصوص.

المفتاحالنوعالافتراضي بالإنجليزيةالوصف
wrongType(name: string) => stringwrongType("photo.jpg")

يطبع "photo.jpg is not an allowed file type"

A file that matches none of the accept tokens. Receives the file name.

tooLarge(name: string, max: string) => stringtooLarge("photo.jpg", "…")

يطبع "photo.jpg is too large (max …)"

A file over maxSize. Receives the file name and the limit, formatted (5 MB).

tooSmall(name: string, min: string) => stringtooSmall("photo.jpg", "…")

يطبع "photo.jpg is too small (min …)"

A file under minSize. Receives the file name and the limit, formatted (1 KB).

tooMany(max: number) => stringtooMany(3)

يطبع "Only 3 files allowed"

A file past maxFiles, counting the items already listed. Receives the limit.

Belege hierher ziehenimage/* · bis 2 MB

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

التنسيق

أسماء الأصناف التي تضعها البدائل الافتراضية في FileUploader على عناصرها، والمتغيرات التي يقرؤها ملف تنسيقه. اضبط متغيرًا على المكوّن أو على أي عنصر يحيط به لتغيير مظهره، واستهدف الصنف فقط لما لا يغطيه متغير.

الصنفالفتحة
.sfu
.sfu__actions—
.sfu__error—
.sfu__compact—
.sfu__hint—
.sfu__input
.sfu__icon
.sfu__copy
.sfu__title—
.sfu__browse
.sfu__thumb
.sfu__thumb-img—
.sfu__meta
.sfu__name—
.sfu__sub—
.sfu__progress
.sfu__progress-bar—
.sfu__action
.sfu__rejections
.sfu__zone
.sfu__list
.sfu__item
المتغيرالطبقة
--sfu-accentهذا المكوّن
--sfu-bgهذا المكوّن
--sfu-borderهذا المكوّن
--sfu-dangerهذا المكوّن
--sfu-font-sizeهذا المكوّن
--sfu-gapهذا المكوّن
--sfu-hoverهذا المكوّن
--sfu-mutedهذا المكوّن
--sfu-radiusهذا المكوّن
--sfu-surfaceهذا المكوّن
--sfu-textهذا المكوّن
--sfu-tile-sizeهذا المكوّن
--ss-accentمشترك بين كل المكوّنات
--ss-borderمشترك بين كل المكوّنات
--ss-dangerمشترك بين كل المكوّنات
--ss-font-sizeمشترك بين كل المكوّنات
--ss-hoverمشترك بين كل المكوّنات
--ss-mutedمشترك بين كل المكوّنات
--ss-radiusمشترك بين كل المكوّنات
--ss-surfaceمشترك بين كل المكوّنات
--ss-textمشترك بين كل المكوّنات

تنتقل كل المتغيرات إلى قيمها الداكنة تحت .dark, [data-theme="dark"]، على الصفحة أو على أي عنصر يحيط بالمكوّن.

صفحة السمات تشرح المتغيرات والسمات الجاهزة.

آخر تحديث