시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-file` plugin in my project.

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

npm install @capgo/capacitor-file
npx cap sync

가져오기

import { CapacitorFile } from '@capgo/capacitor-file';

빠른 시작

import { CapacitorFile, FileSystemType } from '@capgo/capacitor-file';

const result = await CapacitorFile.requestFileSystem({ type: FileSystemType.TEMPORARY });
console.log(result);

예제: resolveLocalFileSystemURL

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.resolveLocalFileSystemURL({
  url: 'file:///data/user/0/com.example.app/files/report.pdf',
});
console.log(result);

예제: getFile

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getFile({ path: 'path/to/file' });
console.log(result);

자주 하는 실수

• 권한: 호출 checkPermissions() 그다음 requestPermissions() 필요할 때.
• 리스너: 화면이 언마운트될 때 핸들을 제거합니다.
• 신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

API 개요

requestFileSystem

파일 시스템 요청

import { CapacitorFile, FileSystemType } from '@capgo/capacitor-file';

const result = await CapacitorFile.requestFileSystem({ type: FileSystemType.TEMPORARY });
console.log(result);

resolveLocalFileSystemURL

파일 URL을 엔트리로 해석

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.resolveLocalFileSystemURL({ url: 'https://example.com' });
console.log(result);

getFile

파일 엔트리 가져오기

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getFile({ path: 'path/to/file' });
console.log(result);

getDirectory

디렉토리 엔트리 가져오기

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getDirectory({ path: 'path/to/file' });
console.log(result);

readFile

파일을 텍스트 또는 base64로 읽기

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.readFile({ path: 'path/to/file' });
console.log(result);

readAsDataURL

파일을 data URL(MIME 타입 접두사가 포함된 base64)로 읽기

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.readAsDataURL({ path: 'path/to/file' });
console.log(result);

writeFile

파일에 데이터 쓰기

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.writeFile({
  path: 'path/to/file',
  data: 'data',
});
console.log(result);

appendFile

파일에 데이터를 추가합니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.appendFile({
  path: 'path/to/file',
  data: 'data',
});
console.log(result);

deleteFile

파일을 삭제합니다.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.deleteFile({ path: 'path/to/file' });

mkdir

디렉토리를 생성합니다.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.mkdir({ path: 'path/to/file' });

rmdir

디렉토리를 삭제합니다.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.rmdir({ path: 'path/to/file' });

readdir

디렉토리 내용을 읽습니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.readdir({ path: 'path/to/file' });
console.log(result);

stat

파일 또는 디렉토리의 메타데이터를 가져옵니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.stat({ path: 'path/to/file' });
console.log(result);

getMetadata

파일 또는 디렉터리의 메타데이터를 가져옵니다. stat()의 별칭입니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getMetadata({ path: 'path/to/file' });
console.log(result);

rename

파일 또는 디렉토리의 이름을 변경하거나 이동합니다.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.rename({
  from: 'from',
  to: 'to',
});

move

파일 또는 디렉토리를 이동합니다. rename()의 별칭입니다.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.move({
  from: 'from',
  to: 'to',
});

copy

파일 또는 디렉토리를 복사합니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.copy({
  from: 'from',
  to: 'to',
});
console.log(result);

exists

파일 또는 디렉토리가 존재하는지 확인합니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.exists({ path: 'path/to/file' });
console.log(result);

getUri

파일의 URI를 가져옵니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getUri({ path: 'path/to/file' });
console.log(result);

truncate

파일을 지정된 크기로 자릅니다.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.truncate({ path: 'path/to/file' });

getDirectories

알려진 모든 파일 시스템 디렉토리를 가져옵니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getDirectories();
console.log(result);

getFreeDiskSpace

사용 가능한 디스크 공간을 바이트 단위로 가져옵니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getFreeDiskSpace();
console.log(result);

checkPermissions

파일 작업에 대한 현재 권한 상태를 확인합니다. Android에서는 외부 저장소 권한을 확인합니다. iOS 및 웹에서는 별도의 권한이 필요하지 않으므로 항상 ‘granted’를 반환합니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.checkPermissions();
console.log(result);

requestPermissions

파일 작업에 필요한 권한을 요청합니다. Android의 경우, 앱의 프라이빗 디렉토리 외부 파일에 접근하는 데 필요한 외부 저장소 권한을 요청합니다. iOS 및 웹의 경우, 별도의 권한이 필요하지 않으므로 항상 'granted'를 반환합니다.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.requestPermissions();
console.log(result);

타입 레퍼런스

RequestFileSystemOptions

파일 시스템 요청 옵션입니다.

export interface RequestFileSystemOptions {
  /** The type of file system to request */
  type: FileSystemType;
  /** Requested size in bytes (may not be enforced on all platforms) */
  size?: number;
}

FileSystem

파일 시스템을 나타냅니다.

export interface FileSystem {
  /** The name of the file system */
  name: string;
  /** The root directory of the file system */
  root: DirectoryEntry;
}

ResolveURLOptions

URL을 엔트리로 해석하기 위한 옵션입니다.

export interface ResolveURLOptions {
  /** The URL to resolve (file:// or cdvfile://) */
  url: string;
}

Entry

파일 또는 디렉토리 엔트리를 나타냅니다.

export interface Entry {
  /** True if this is a file */
  isFile: boolean;
  /** True if this is a directory */
  isDirectory: boolean;
  /** The name of the file or directory */
  name: string;
  /** The full path relative to the filesystem root */
  fullPath: string;
  /** The native file:// URI */
  nativeURL: string;
}

GetFileOptions

파일을 가져오기 위한 옵션입니다.

export interface GetFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Options for creating the file */
  options?: GetOptions;
}

FileEntry

파일 엔트리를 나타냅니다.

export interface FileEntry extends Entry {
  isFile: true;
  isDirectory: false;
}

GetDirectoryOptions

디렉터리를 가져오는 옵션입니다.

export interface GetDirectoryOptions {
  /** Path to the directory */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Options for creating the directory */
  options?: GetOptions;
}

DirectoryEntry

디렉터리 엔트리를 나타냅니다.

export interface DirectoryEntry extends Entry {
  isFile: false;
  isDirectory: true;
}

ReadFileOptions

파일을 읽기 위한 옵션입니다.

export interface ReadFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Encoding for text files (omit for binary/base64) */
  encoding?: Encoding;
  /** Byte offset to start reading from (default: 0) */
  offset?: number;
  /** Number of bytes to read (default: read to end of file) */
  length?: number;
}

ReadFileResult

파일 읽기 결과입니다.

export interface ReadFileResult {
  /** File contents as string (text) or base64 (binary) */
  data: string;
}

WriteFileOptions

파일 쓰기 옵션

export interface WriteFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Data to write (string for text, base64 for binary) */
  data: string;
  /** Encoding for text files */
  encoding?: Encoding;
  /** If true, append to existing file instead of overwriting */
  append?: boolean;
  /** Create intermediate directories if they don't exist */
  recursive?: boolean;
  /** Byte position to start writing at (for random access writes). If not specified, writes from beginning or appends based on 'append' flag */
  position?: number;
}

WriteFileResult

파일 쓰기 결과

export interface WriteFileResult {
  /** The URI of the written file */
  uri: string;
}

Source of Truth

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 저장 공간과 파일 처리를 계획하려면, 다음 항목과 연결하세요 @capgo/capacitor-file 사용하기 @capgo/capacitor-file 사용 시 네이티브 기능은 @capgo/capacitor-data-storage-sqlite @capgo/capacitor-data-storage-sqlite의 구현 세부 사항은, @capgo/capacitor-data-storage-sqlite 사용하기 @capgo/capacitor-data-storage-sqlite 사용 시 네이티브 기능을 위해, @capgo/capacitor-file @capgo/capacitor-file의 구현 세부 사항을 위해, 그리고 @capgo/capacitor-uploader @capgo/capacitor-uploader.의 구현 세부 사항에 대해서는