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 사용 방법
기능 감지
File System Observer 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 사용해 보기
File System Observer API를 로컬에서 테스트하려면 about:flags에서 #file-system-observer 플래그를 설정합니다. 실제 사용자를 대상으로 API를 테스트하려면 오리진 트라이얼에 가입하고 Chrome 오리진 트라이얼 가이드에 따라 안내를 따르세요. 오리진 트라이얼은 Chrome 129 (2024년 9월 11일)부터 Chrome 134 (2025년 2월 26일)까지 진행됩니다.
데모
삽입된 데모에서 File System Observer API가 작동하는 모습을 확인할 수 있습니다. 소스 코드를 확인하거나 Glitch에서 데모 코드를 리믹스하세요. 이 데모는 관찰된 디렉터리의 파일을 무작위로 생성, 삭제 또는 수정하고 앱 창 상단에 활동을 기록합니다. 그런 다음 앱 창 하단에서 변경사항이 발생할 때마다 로깅합니다. File System Observer API를 지원하지 않는 브라우저에서 이 도움말을 읽는 경우 데모의 스크린샷을 참고하세요.
의견
File System Observer API의 형식에 관한 의견이 있으면 WHATWG/fs의 Issue #123 저장소에 의견을 작성하세요.