Trang này được dịch bởi Cloud Translation API.

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

Thomas Steiner

Cả File System Access API và Origin Private File System API đề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. Cái trước 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 có thể thấy, còn cái sau mở ra một hệ thống tệp đặc biệt, ẩn đối với người dùng, riêng tư đối với nguồn gốc của mỗi trang web và có một số lợi thế về hiệu suất. Trong cả hai trường hợp, cách nhà phát triển tương tác với các tệp và thư mục là thông qua các đối tượng FileSystemHandle, cụ thể hơn là FileSystemFileHandle cho các tệp và FileSystemDirectoryHandle cho các thư mục. Cho đến nay, để biết được những thay đổi đối với một tệp hoặc thư mục trong một trong hai hệ thống tệp, bạn cần phải thực hiện một số hình thức thăm dò và so sánh dấu thời gian lastModified hoặc thậm chí là nội dung của tệp.

File System Observer API (API Trình theo dõi hệ thống tệp) trong bản dùng thử theo nguyên gốc từ Chrome 129 sẽ thay đổi điều đó và cho phép nhà phát triển tự động nhận được cảnh 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ề các thay đổi có thể xảy ra trong hệ thống tệp ngay khi những thay đổi đó diễn ra.

Môi trường phát triển tích hợp (IDE) dựa trên web cho thấy một bản trình bày về cây hệ thống tệp của dự án.
Ứng dụng đồng bộ hoá các thay đổi về hệ thống tệp với một máy chủ. Ví dụ: một 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ề các thay đổi đối với hệ thống tệp từ một worker hoặc thẻ khác.
Các ứ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.
Những trải nghiệm có lợi từ tính năng tải lại nhanh, chẳng hạn như bộ trang trình bày dựa trên HTML, trong đó quá trình tải lại được kích hoạt khi có thay đổi về tệp.

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

Phát hiện đối tượng

Để kiểm tra xem File System Observer API có được hỗ trợ hay không, hãy chạy một 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 một trình theo dõi hệ thống tệp

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

const observer = new FileSystemObserver(callback);

Bắt đầu theo dõi một tệp hoặc thư mục

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

// 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, một hàm gọi lại sẽ được gọi bằng thay đổi hệ thống tệp records và chính observer làm đối số. Bạn có thể dùng đối số observer để, chẳng hạn như ngắt kết nối trình theo dõi (xem phần Dừng theo dõi hệ thống tệp) khi tất cả các tệp 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 hệ thống tệp đều có cấu trúc sau. Tất cả các trường đều ở chế độ chỉ đọc.

root (một FileSystemHandle): Xử lý được truyền đến hàm FileSystemObserver.observe().
changedHandle (một FileSystemHandle): Xử lý bị ảnh hưởng bởi thay đổi của hệ thống tệp. Trường này sẽ là null cho các sự kiện thuộc loại "errored", "unknown" và "disappeared". Để xem tệp hoặc thư mục nào đã biến mất, hãy sử dụng relativePathComponents.
relativePathComponents (một Array): Đường dẫn của changedHandle so với root.
type (a 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 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": Điều này cho biết đã bỏ lỡ từ 0 sự kiện trở lên. Để phản hồi yêu cầu này, nhà phát triển nên thăm dò thư mục được theo dõi.
- "errored": Thông tin quan sát không còn hợp lệ. Trong trường hợp này, bạn có thể muốn dừng theo dõi hệ thống tệp. Giá trị này cũng sẽ được gửi khi đạt đến giới hạn tối đa về số lượng quan sát trên mỗi nguồn gốc. Giới hạn này phụ thuộc vào hệ điều hành và không được biết trước. Nếu điều này xảy ra, trang web có thể quyết định thử lại, mặc dù không có gì đảm bảo rằng hệ điều hành đã giải phóng đủ tài nguyên. Một trường hợp khác mà giá trị này sẽ được gửi là khi đối tượng được theo dõi (tức là gốc của hoạt động theo dõi) bị xoá hoặc di chuyển. Trong trường hợp này, trước tiên, sự kiện "disappeared" sẽ được gửi, sau đó là sự kiện "errored", cho biết rằng dữ liệu quan sát không còn hợp lệ nữa. Cuối cùng, sự kiện này được gửi khi quyền truy cập vào thư mục hoặc tệp được xoá.
relativePathMovedFrom (Array, không bắt buộc): Vị trí cũ của một tên người dùng đã được chuyển. Chỉ có khi type là "moved".

Lưu ý: Tuỳ thuộc vào hệ điều hành, không phải tất cả các sự kiện thay đổi đều có thể được báo cáo với cùng mức độ chi tiết, ví dụ: khi nội dung của một thư mục thay đổi một cách đệ quy. Tốt nhất là trang web sẽ nhận được một bản ghi thay đổi chi tiết chứa loại thay đổi và một hàm xử lý cho đường dẫn bị ảnh hưởng. Trong trường hợp xấu nhất, trang web sẽ nhận được một bản ghi thay đổi chung hơn (tức là một type có giá trị "unknown"). Trang web vẫn phải liệt kê thư mục để tìm ra thư mục con nào đã thay đổi. Đây vẫn là một điểm cải tiến so với việc thăm dò, vì bạn có thể kích hoạt quá trình liệt kê thư mục theo yêu cầu từ hàm gọi lại, thay vì cần thăm dò các thay đổi theo khoảng thời gian.

Dừng theo dõi một tệp hoặc thư mục

Để ngừng theo dõi một FileSystemHandle, hãy gọi phương thức unobserve(), truyền cho phương thức này giá trị nhận dạng dưới dạng một đối số.

observer.unobserve(fileHandle);

Ngừng theo dõi hệ thống tệp

Để ngừng theo dõi hệ thống tệp, hãy ngắt kết nối phiên bản FileSystemObserver như sau.

observer.disconnect();

Dùng thử API

Để kiểm thử File System Observer API cục bộ, hãy đặt cờ #file-system-observer trong about:flags. Để kiểm thử API với người dùng thực, hãy đăng ký dùng thử theo nguyên gốc và làm theo hướng dẫn trong bài viết Thử nghiệm theo nguyên gốc của Chrome. Bản dùng thử theo nguyên gốc sẽ diễn ra 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 API Trình theo dõi hệ thống tệp hoạt động trong bản minh hoạ được nhúng. Hãy xem mã nguồn. Bản minh hoạ này tạo, xoá hoặc sửa đổi các tệp một cách ngẫu nhiên trong một thư mục được theo dõi và ghi lại hoạt động của thư mục đó ở phần trên của cửa sổ ứng dụng. Sau đó, ứng dụng 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 bài viết 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ó ý kiến phản hồi về hình dạng của File System Observer API, hãy bình luận về Vấn đề #123 trong kho lưu trữ WHATWG/fs.

Đường liên kết có liên quan

Lời cảm ơn

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