File Manager
커넥터 계약과 capability 게이팅으로 폴더 탐색, 업로드 큐, 파일 상세를 다루는 파일 매니저 가이드입니다.
reopt design업데이트
커넥터 계약(capability 게이팅), mock/brandapp 커넥터, 폴더 탐색·업로드 큐·파일 상세 UI를 담당합니다.
mock 커넥터의 지연·실패·capability 시뮬레이션을 전체 화면에서 실험해 보세요.
Playground 열기1. 기본 사용
FileManager 하나로 툴바, 브레드크럼, 목록/그리드, 드래그앤드롭 업로드, 상세 패널까지 전부 렌더됩니다. 데모와 테스트는 인메모리 mock 커넥터로 시작하세요.
import {
FileManager,
createMockFileManagerConnector,
} from "@reopt-ai/opt-filemanager";
import "@reopt-ai/opt-filemanager/styles.css";
const connector = createMockFileManagerConnector();
export function Files() {
return <FileManager connector={connector} locale="ko" />;
}2. 커넥터 계약
capabilities와 list만 필수입니다. mutation 메서드는 대응 capability가 true일 때만 구현하면 되고, UI는 capability가 꺼진 액션을 절대 호출하지 않습니다.
import type { FileManagerConnector } from "@reopt-ai/opt-filemanager";
export function createMyConnector(): FileManagerConnector {
return {
capabilities: {
createFolder: true,
createFile: false,
upload: true,
rename: true,
remove: true,
move: false, // UI가 이동 액션을 자동으로 숨깁니다
readText: false, // 텍스트 미리보기 비활성
usage: false, // 저장공간 미터 비활성
download: true,
},
async list({ folderId, signal }) {
const response = await fetch(`/api/files?folder=${folderId ?? ""}`, {
signal,
});
return { entries: await response.json() };
},
async upload({ parentId, file, signal }) {
// presigned URL, multipart 등 원하는 방식으로 구현
return uploadToMyBackend(parentId, file, signal);
},
// capability가 true인 메서드만 구현하면 됩니다
};
}| Capability | 의미 | 게이팅되는 UI |
|---|---|---|
| createFolder | 폴더 생성 | 새 폴더 버튼과 인라인 이름 폼 |
| createFile | 텍스트 파일 생성 | 새 파일 버튼 (brandapp은 Blob 업로드로 구현) |
| upload | 바이너리 업로드 | 업로드 버튼, 드래그앤드롭, 진행률 큐 |
| rename | 이름 변경 | 상세 패널의 이름 변경 폼 |
| remove | 삭제 | 상세 패널 삭제 + 다중 선택 일괄 삭제 |
| move | 폴더 간 이동 | 상세 패널·선택 바의 이동 메뉴 |
| readText | 텍스트 내용 읽기 | 상세 패널 텍스트 미리보기 |
| usage | 저장공간 사용량 | 하단 사용량 미터 (80% 경고, 95% 위험) |
| download | 다운로드 URL | 상세 패널 다운로드 링크 |
3. brandapp files 커넥터
brandapp files API는 평평한 네임스페이스입니다 — 폴더·이름 변경·이동이 없고, 업로드는 10MB 직접 multipart이며, 사용 중인 파일 삭제는 409로 거부될 수 있습니다. 커넥터가 이 제약을 capability로 선언하므로 UI는 자동으로 맞춰집니다.
import { createBrandappFilesConnector } from "@reopt-ai/opt-filemanager";
import { createReoptFileClient } from "@reopt-ai/brandapp-sdk/files";
// clientSecret은 브라우저 금지 — 서버 라우트나
// `reopt brandapp dev` 목 서버(4300)를 프록시로 두세요.
const connector = createBrandappFilesConnector({
client: createReoptFileClient(config),
});4. 아키텍처 모델
Connector-first
UI는 스토리지를 모릅니다. FileManagerConnector 계약(list 필수 + 선택적 mutation)만 구현하면 어떤 백엔드든 붙습니다.
Capability 게이팅
커넥터가 광고하는 capabilities에 따라 액션이 자동으로 숨겨집니다. 폴더 없는 평평한 백엔드도 일관된 화면을 유지합니다.
Headless + 컴포짓
useFileManager 훅이 상태 전부(탐색·선택·필터·업로드 큐)를 소유하고, 서브컴포넌트를 재조합해 커스텀 레이아웃을 만들 수 있습니다.
Zero runtime deps
런타임 의존성이 없습니다. 아이콘은 인라인 SVG, 색상은 var(--opt-*) 토큰 + 하드코딩 폴백으로 셸 없이도 렌더됩니다.