File System Access API와 Origin Private File System API를 사용하면 개발자가 사용자 기기의 파일과 디렉터리에 액세스할 수 있습니다. 전자는 개발자가 일반적인 사용자 표시 파일 시스템을 읽고 쓸 수 있도록 하고 후자는 각 사이트의 출처에 비공개이며 특정 성능 이점이 있는 특수 사용자 숨김 파일 시스템을 엽니다. 두 경우 모두 개발자가 파일 및 디렉터리와 상호작용하는 방식은 FileSystemHandle 객체를 통해서입니다. 더 구체적으로는 파일의 경우 FileSystemFileHandle, 디렉터리의 경우 FileSystemDirectoryHandle입니다. 지금까지 파일 시스템의 파일 또는 디렉터리 변경사항을 알리려면 lastModified 타임스탬프 또는 파일 콘텐츠 자체를 폴링하고 비교하는 형태가 필요했습니다.
Chrome 129부터 오리진 트라이얼로 제공되는 File System Observer API는 이를 변경하여 변경사항이 발생하면 개발자에게 자동으로 알림을 보냅니다. 이 가이드에서는 작동 방식과 기능을 사용해 보는 방법을 설명합니다.
사용 사례
파일 시스템 변경사항이 발생하자마자 이를 알려야 하는 앱에서는 File System Observer API를 사용하세요.
- 프로젝트의 파일 시스템 트리를 표현하는 웹 기반 통합 개발 환경 (IDE)
- 파일 시스템 변경사항을 서버와 동기화하는 앱 예를 들어 SQLite 데이터베이스 파일입니다.
- 작업자 또는 다른 탭에서 파일 시스템 변경사항을 기본 스레드에 알려야 하는 앱
- 예를 들어 이미지를 자동으로 최적화하기 위해 리소스 디렉터리를 관찰하는 앱
- 파일 변경으로 새로고침이 트리거되는 HTML 기반 슬라이드와 같이 핫 리로드를 통해 이점을 얻을 수 있는 환경
File System Observer API 사용 방법
기능 감지
파일 시스템 관찰자 API가 지원되는지 확인하려면 다음 예와 같이 기능 테스트를 실행하세요.
if ('FileSystemObserver' in self) {
// The File System Observer API is supported.
}
파일 시스템 관찰자 초기화
new FileSystemObserver()를 호출하여 파일 시스템 관찰자를 초기화하고 callback 함수를 인수로 제공합니다.
const observer = new FileSystemObserver(callback);
파일 또는 디렉터리 관찰 시작
파일 또는 디렉터리 관찰을 시작하려면 FileSystemObserver 인스턴스의 비동기 observe() 메서드를 호출합니다. 선택한 파일 또는 디렉터리의 FileSystemHandle을 인수로 이 메서드에 제공합니다. 디렉터리를 관찰할 때 디렉터리 자체와 포함된 모든 하위 디렉터리 및 파일의 변경사항을 재귀적으로 알림을 받을지 선택할 수 있는 선택적 options 인수가 있습니다. 기본 옵션은 디렉터리 자체와 직접 포함된 파일만 관찰하는 것입니다.
// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});
콜백 함수
파일 시스템이 변경되면 파일 시스템 변경 records과 observer 자체가 인수로 사용되어 콜백 함수가 호출됩니다. observer 인수를 사용하여 관심 있는 파일이 모두 삭제될 때 관찰자를 연결 해제할 수 있습니다 (파일 시스템 관찰 중지 참고).
const callback = (records, observer) => {
for (const record of records) {
console.log('Change detected', record);
}
};
파일 시스템 변경사항 기록
각 파일 시스템 변경 레코드의 구조는 다음과 같습니다. 모든 필드는 읽기 전용입니다.
root(FileSystemHandle):FileSystemObserver.observe()함수에 전달된 핸들입니다.changedHandle(FileSystemHandle): 파일 시스템 변경의 영향을 받는 핸들입니다. 이 필드는"errored","unknown","disappeared"유형 이벤트의 경우null입니다. 사라진 파일이나 디렉터리를 확인하려면relativePathComponents를 사용하세요.relativePathComponents(Array):root을 기준으로 한changedHandle의 경로입니다.type(String): 변경 유형입니다. 다음 유형이 가능합니다."appeared": 파일 또는 디렉터리가 생성되었거나root로 이동되었습니다."disappeared": 파일 또는 디렉터리가 삭제되었거나root에서 이동되었습니다."modified": 파일 또는 디렉터리가 수정되었습니다."moved": 파일 또는 디렉터리가root내에서 이동되었습니다."unknown": 0개 이상의 이벤트가 누락되었음을 나타냅니다. 개발자는 이에 따라 감시된 디렉터리를 폴링해야 합니다."errored": 관찰이 더 이상 유효하지 않습니다. 이 경우 파일 시스템 관찰을 중지하는 것이 좋습니다. 이 값은 출처별 관측치의 최대 한도에 도달한 경우에도 전송됩니다. 이 제한은 운영체제에 따라 다르며 사전에 알 수 없습니다. 이 경우 사이트에서 재시도할 수 있지만 운영체제에서 충분한 리소스를 확보했는지 보장할 수는 없습니다. 이 값이 전송되는 또 다른 경우는 관찰된 핸들 (즉, 관찰의 루트)이 삭제되거나 이동되는 경우입니다. 이 경우 먼저"disappeared"이벤트가 전송된 다음 관찰이 더 이상 유효하지 않음을 나타내는"errored"이벤트가 전송됩니다. 마지막으로 이 이벤트는 디렉터리 또는 파일 핸들에 대한 권한이 삭제될 때 전송됩니다.
relativePathMovedFrom(Array, 선택사항): 이동된 핸들의 이전 위치입니다.type이"moved"인 경우에만 사용할 수 있습니다.
파일 또는 디렉터리 관찰 중지
FileSystemHandle 관찰을 중지하려면 핸들을 인수로 전달하여 unobserve() 메서드를 호출하세요.
observer.unobserve(fileHandle);
파일 시스템 관찰 중지
파일 시스템 관찰을 중지하려면 다음과 같이 FileSystemObserver 인스턴스를 연결 해제하세요.
observer.disconnect();
API 사용해 보기
파일 시스템 관찰자 API를 로컬로 테스트하려면 about:flags에서 #file-system-observer 플래그를 설정하세요. 실제 사용자로 API를 테스트하려면 오리진 트라이얼을 신청하고 Chrome 오리진 트라이얼 가이드에 따라 안내를 따르세요. 오리진 트라이얼은 Chrome 129 (2024년 9월 11일)부터 Chrome 134 (2025년 2월 26일)까지 실행됩니다.
데모
삽입된 데모에서 File System Observer API가 작동하는 모습을 확인할 수 있습니다. 소스 코드를 확인합니다. 데모는 관찰된 디렉터리에서 파일을 무작위로 만들거나 삭제하거나 수정하고 앱 창의 상단에 활동을 기록합니다. 그런 다음 앱 창 하단에 변경사항이 발생할 때 이를 기록합니다. File System Observer API를 지원하지 않는 브라우저에서 이 내용을 읽고 있다면 데모의 스크린샷을 참고하세요.
의견
파일 시스템 관찰자 API의 형태에 관한 의견이 있으면 WHATWG/fs 저장소의 문제 #123에 댓글을 달아 주세요.