Bản dùng thử theo nguyên gốc File System Observer API

Thomas Steiner

API Truy cập hệ thống tệp và API Hệ thống tệp riêng tư gốc đều cho phép nhà phát triển truy cập vào các tệp và thư mục trên thiết bị của người dùng. Giải pháp cho phép nhà phát triển đọc và ghi vào hệ thống tệp thông thường mà người dùng nhìn thấy. Đối với hệ thống tệp thứ hai, các nhà phát triển sẽ mở ra một hệ thống tệp đặc biệt, ẩn khỏi hệ thống tệp của người dùng, riêng tư chỉ có nguồn gốc của mỗi trang web và đi kèm với một số lợi thế về hiệu suất. Cách nhà phát triển tương tác với các tệp và thư mục trong cả hai trường hợp đều là thông qua các đối tượng FileSystemHandle, cụ thể hơn là thông qua FileSystemFileHandle đối với tệp và FileSystemDirectoryHandle đối với thư mục. Cho đến nay, việc nhận được thông báo về các thay đổi đối với một tệp hoặc thư mục trong một trong hai hệ thống tệp đòi hỏi phải thực hiện một số hình thức thăm dò ý kiến và so sánh dấu thời gian lastModified hoặc thậm chí là chính nội dung tệp.

File System Observer API (API Trình quan sát hệ thống tệp) trong bản dùng thử theo nguyên gốc của Chrome 129 sẽ thay đổi điều đó và cho phép nhà phát triển tự động nhận thông báo khi có thay đổi. Hướng dẫn này giải thích cách hoạt động và cách dùng thử tính năng này.

Trường hợp sử dụng

Sử dụng File System Observer API trong những ứng dụng cần được thông báo về những thay đổi có thể xảy ra với hệ thống tệp ngay khi chúng xảy ra.

  • Môi trường phát triển tích hợp (IDE) dựa trên web cho thấy hình minh hoạ cây hệ thống tệp của dự án.
  • Những ứng dụng đồng bộ hoá các thay đổi về hệ thống tệp với máy chủ. Ví dụ: tệp cơ sở dữ liệu SQLite.
  • Các ứng dụng cần thông báo cho luồng chính về những thay đổi của hệ thống tệp từ một worker hoặc thẻ khác.
  • Những ứng dụng quan sát một thư mục tài nguyên, chẳng hạn như để tự động tối ưu hoá hình ảnh.

Cách sử dụng File System Observer API

Phát hiện tính năng

Để xem API Trình quan sát hệ thống tệp có được hỗ trợ hay không, hãy chạy kiểm thử tính năng như trong ví dụ sau.

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

Khởi động trình quan sát hệ thống tệp

Khởi chạy File System Observer (Trình quan sát hệ thống tệp) bằng cách gọi new FileSystemObserver(), cung cấp cho nó một hàm callback làm đối số.

const observer = new FileSystemObserver(callback);

Bắt đầu quan sát một tệp hoặc thư mục

Để bắt đầu quan sát một tệp hoặc thư mục, hãy gọi phương thức observe() không đồng bộ của thực thể FileSystemObserver. Cung cấp cho phương thức này đối số FileSystemHandle của tệp hoặc thư mục đã chọn. Khi quan sát một thư mục, có một đối số options (không bắt buộc) cho phép bạn chọn xem bạn có muốn nhận thông báo về các thay đổi đối với thư mục theo cách đệ quy hay không (nghĩa là đối với chính thư mục đó và tất cả thư mục con và tệp có chứa). Tuỳ chọn mặc định chỉ quan sát thư mục đó và các tệp được chứa trực tiếp.

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

Hàm callback

Khi có thay đổi đối với hệ thống tệp, hàm callback được gọi với thay đổi hệ thống tệp records và chính observer làm đối số. Ví dụ: bạn có thể sử dụng đối số observer để ngắt kết nối trình quan sát (xem phần Ngừng quan sát hệ thống tệp) khi tất cả các tệp mà bạn quan tâm đều đã bị xoá.

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

Bản ghi thay đổi hệ thống tệp

Mỗi bản ghi thay đổi của hệ thống tệp có cấu trúc như sau. Tất cả các trường đều chỉ có thể đọc.

  • root (FileSystemHandle): Tay cầm được truyền đến hàm FileSystemObserver.observe().
  • changedHandle (FileSystemHandle): Tên người dùng chịu ảnh hưởng của việc thay đổi hệ thống tệp.
  • relativePathComponents (Array): Đường dẫn của changedHandle so với root.
  • type (String): Loại thay đổi. Có thể có các loại sau:
    • "appeared": Tệp hoặc thư mục đã được tạo hoặc di chuyển vào root.
    • "disappeared": Tệp hoặc thư mục đã bị xoá hoặc bị chuyển ra khỏi root.
    • "modified": Tệp hoặc thư mục đã được sửa đổi.
    • "moved": Tệp hoặc thư mục đã được di chuyển trong root.
    • "unknown": Mã này cho biết không có hoặc có nhiều sự kiện bị bỏ lỡ. Nhà phát triển nên thăm dò thư mục đã xem để phản hồi vấn đề này.
    • "errored": Quan sát không còn hợp lệ. Trong trường hợp này, bạn có thể dừng quan sát hệ thống tệp.
  • relativePathMovedFrom (Array, không bắt buộc): Vị trí cũ của tên người dùng đã di chuyển. Chỉ dùng được khi type có giá trị là "moved".

Dừng quan sát một tệp hoặc thư mục

Để dừng quan sát một FileSystemHandle, hãy gọi phương thức unobserve(), truyền vào đó đối số xử lý làm đối số.

observer.unobserve(fileHandle);

Ngừng quan sát hệ thống tệp

Để dừng quan sát hệ thống tệp, hãy ngắt kết nối thực thể FileSystemObserver như sau.

observer.disconnect();

Dùng thử API

Để kiểm thử cục bộ File System Observer API, hãy thiết lập cờ #file-system-observer trong about:flags. Để thử nghiệm API với người dùng thực, hãy đăng ký bản dùng thử theo nguyên gốc và làm theo hướng dẫn trong phần Bản dùng thử Chrome Origin. Bản dùng thử theo nguyên gốc sẽ chạy từ Chrome 129 (ngày 11 tháng 9 năm 2024) đến Chrome 134 (ngày 26 tháng 2 năm 2025).

Bản minh hoạ

Bạn có thể xem cách hoạt động của API File System Observer trong bản minh hoạ được nhúng. Hãy xem mã nguồn hoặc phối lại mã minh hoạ trên Glitch. Bản minh hoạ sẽ tạo, xoá hoặc sửa đổi các tệp ngẫu nhiên trong một thư mục được quan sát và ghi lại hoạt động của thư mục đó vào phần trên của cửa sổ ứng dụng. Sau đó, Google Play sẽ ghi lại các thay đổi khi chúng xảy ra ở phần dưới của cửa sổ ứng dụng. Nếu bạn đọc thông tin này trên một trình duyệt không hỗ trợ File System Observer API, hãy xem ảnh chụp màn hình của bản minh hoạ.

Phản hồi

Nếu bạn có phản hồi về hình dạng của API Trình quan sát hệ thống tệp, hãy nhận xét về Vấn đề #123 trong kho lưu trữ màWG/fs.

Xác nhận

Tài liệu này do Daseul Lee, Nathan Memmott, Etienne Noël và Rachel Andrew xem xét.