API referansı

@thefinder/react

Dosya yöneticisi arayüzü. Tek bağımlılığı react ve react-dom'dur (≥ 18, peer); stiller saf CSS'tir.

"use client";
import { TheFinder } from "@thefinder/react";
import "@thefinder/react/styles.css";

<div style={{ height: "100vh" }}>
  <TheFinder endpoint="/api/files" locale="tr" />
</div>

styles.css bir kez, uygulamanın herhangi bir yerinde içe aktarılmalıdır. Bileşen ebeveyninin yüksekliğini doldurur (height prop'u ile değiştirilebilir).

<TheFinder />#

Bağlantı#

Görünüm#

Başlangıç durumu#

Prefs:

Olaylar#

onChange olayı: { type, entries?, ids? }. entries yeni ya da güncellenen öğeler, ids kaldırılan öğelerin kimlikleridir.

Seçici modu#

Bu prop'lardan onSelect verildiğinde bileşen seçici gibi davranır: alt çubukta "Seç" düğmesi çıkar, dosyaya çift tıklamak onu seçer. Modal bir seçici için useFilePicker daha pratiktir.

type Accept = string | string[] | ((entry: Entry) => boolean);
// "image/*"            MIME grubu
// ".pdf,.docx"         uzantılar
// ["image/png", ".svg"]
// (e) => e.size < 2_000_000

matchesAccept(entry, accept) aynı kuralı kendi kodunuzda uygulamak için dışa aktarılır. Klasörler hiçbir zaman eşleşmez.

Dosya seçici#

useFilePicker(options)#

const picker = useFilePicker({ endpoint: "/api/files", accept: "image/*" });

<button disabled={picker.isOpen} onClick={async () => {
  const files = await picker.open();
  if (files) setCover(files[0].url);
}}>Görsel seç</button>

Döner: { open(overrides?), isOpen }.

• open bir Promise<PickedFile[] | null> döner; kullanıcı vazgeçerse null gelir. overrides o açılış için seçenekleri değiştirir: picker.open({ multiple: true }).
• isOpen seçici açıkken true olur.
• Hook her render'da en son seçenekleri kullanır; seçenek nesnesini useMemo ile sarmanız gerekmez.

openFilePicker(options)#

React dışında (vanilla JS, Vue, zengin metin editörleri) aynı seçici. <body> sonuna bir <dialog> ekler, kapanınca kaldırır. React ve React DOM sayfada paketlenmiş olmalıdır.

import { openFilePicker } from "@thefinder/react";
import "@thefinder/react/styles.css";

const files = await openFilePicker({ endpoint: "/api/files", accept: ".pdf" });
if (files) input.value = files[0].url;

Sunucu tarafında (document yokken) hemen null döner.

FilePickerOptions#

<TheFinder /> prop'larının hepsi (onSelect, onCancel, height, style hariç) ve şunlar:

Seçici Escape ile, arka plana tıklayarak ya da "Vazgeç" düğmesiyle kapanır. Escape önce açık menü ya da pencereleri kapatır. Ayrı pencerede "Vazgeç" düğmesiyle ya da pencerenin kapat düğmesiyle kapanır.

PickedFile#

Entry ve ek olarak url: string. Volume'de url tanımlıysa bu adres ("/uploads/a.png"), değilse API'nin dosya adresi kullanılır. pickedUrl(entry, client, absolute?) aynı adresi kendi kodunuzda üretmek için dışa aktarılır.

Ayrı pencere#

theFinder, elFinder gibi ayrı bir tarayıcı penceresinde çalışabilir. Bunun için hiçbir şey servis etmeniz gerekmez: pencere, açan sayfanın kendi kodu ve stilleriyle içine çizdiği boş, aynı kökenli bir sayfadır; bu yüzden bütün prop'lar (özel editörler, headers, callback'ler) her zamanki gibi çalışır.

// Pencerede seçici: aynı promise, aynı sonuç.
const files = await openFilePicker({ endpoint: "/api/files", accept: "image/*", popup: true });
const picker = useFilePicker({ endpoint: "/api/files", popup: { width: 960, height: 640 } });

// Dosya yöneticisinin tamamı pencerede.
const finder = openFinderWindow({ endpoint: "/api/files" }, { title: "Dosyalar" });
await finder?.closed; // finder.window, finder.close()

openFinderWindow(props, options?) <TheFinder /> prop'larını (height hariç) ve { width = 1120, height = 720, title = "theFinder" } alır. { window, close, closed } döndürür; tarayıcı popup'ı engellerse null.

• Bir tıklama içinden çağırın, yoksa tarayıcı popup'ı engeller. Seçici o durumda dialog'a geri döner.
• Pencere sayfanın ortasında açılır ve sayfayla birlikte kapanır: sayfanın koduyla çalışır.
• Sayfanın stilleri (sonradan eklenenler de) ve <html> öznitelikleri (class="dark", lang) kopyalanır.
• CKEditor connector'ında: picker: { popup: true }.

Özel editörler#

editors prop'u, eşleşen dosyalar için "Birlikte aç" menüsüne bir öğe ekler. Editör, dosya yöneticisinin içinde tam ekran açılır.

import type { CustomEditor } from "@thefinder/react";

const csvViewer: CustomEditor = {
  id: "csv",
  label: "Tablo olarak aç",
  match: (entry) => entry.name.toLowerCase().endsWith(".csv"),
  render: ({ entry, store, onClose }) => <CsvTable url={store.fileUrl(entry)} title={entry.name} onClose={onClose} />,
};

<TheFinder endpoint="/api/files" editors={[csvViewer]} />

Editör içinden kullanışlı store üyeleri:

Kaydetme örneği:

const { entry: saved } = await store.client.putContent(entry.id, text);
store.updateEntry(saved);
store.toast("Kaydedildi", "success");

Store ve hook'lar#

Bileşen, useSyncExternalStore üzerine kurulu küçük bir store (FinderStore) kullanır. Store'a yalnızca <TheFinder /> içinde render edilen bileşenlerden (örneğin özel editörler) erişilebilir.

Store metotları (open, select, upload, paste, remove…) arayüzün kendisi için yazılmıştır. Kullanılabilirler ama 0.x boyunca imzaları değişebilir.

i18n#

Yeni bir dil eklemek için tüm anahtarları çevirip verin; eksik kalanlar İngilizce görünür:

import { locales, type Messages } from "@thefinder/react";

const de: Partial<Messages> = { upload: "Hochladen", newFolder: "Neuer Ordner" /* ... */ };
<TheFinder endpoint="/api/files" locale="de" messages={de} />

Anahtarların tam listesi için locales.en nesnesine bakın.

İkonlar#

Arayüzün elle çizilmiş SVG ikonları kendi bileşenlerinizde de kullanılabilir:

Tema#

Tüm stiller @layer thefinder içindedir. Katman dışında yazdığınız her kural onları ezer, !important gerekmez. Kök öğe .tf-root'tur. data-theme (light, dark, auto), data-skin (classic, macos) ve data-density öznitelikleri taşır.

.tf-root {
  --tf-accent: #0f766e;
  --tf-radius: 4px;
  --tf-font: "Inter", system-ui, sans-serif;
}
.tf-root[data-theme="dark"] {
  --tf-bg: #101418;
}

Sınıfların hepsi tf- öneklidir. Değişken dışındaki sınıflar iç yapıdır ve küçük sürümlerde değişebilir.

Yeniden dışa aktarımlar#

createClient, TheFinderClient, ApiError, encodeId ve Entry, VolumeInfo tipleri @thefinder/core/client'tan aynen gelir.

Bu sayfa docs/api/tr/react.md dosyasından üretildi.