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 (API truy cập hệ thống tệp) và Origin Private File System API (API hệ thống tệp riêng của nguồn 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. Phương thức 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 nhìn thấy, còn phương thức sau mở ra một hệ thống tệp đặc biệt, ẩn khỏi người dùng, chỉ dành riêng cho nguồn gốc của mỗi trang web và có 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 là thông qua các đối tượng FileSystemHandle, cụ thể hơn là FileSystemFileHandle cho tệp và FileSystemDirectoryHandle cho thư mục. Cho đến nay, việc đượ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 yêu cầu 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à 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 từ Chrome 129 sẽ thay đổi điều đó và tự động thông báo cho nhà phát triển khi có thay đổi. Hướng dẫn này giải thích cách hoạt động của tính năng này và cách dùng thử.

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

Sử dụng API Trình quan sát hệ thống tệp trong các ứng dụng cần được thông báo về những thay đổi có thể xảy ra đối 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 ảnh 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á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ề các thay đổi đối với hệ thống tệp từ một worker hoặc một thẻ khác.
Các ứng dụng quan sát thư mục tài nguyên, ví dụ: để tự động tối ưu hoá hình ảnh.
Những trải nghiệm hưởng lợi từ tính năng tải lại nhanh, chẳng hạn như các trang trình bày dựa trên HTML, trong đó quá trình tải lại được kích hoạt bởi một thay đổi về tệp.

Cách sử dụng API Trình quan sát hệ thống tệp

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 chạy trình quan sát hệ thống tệp

Khởi chạy Trình quan sát hệ thống tệp bằng cách gọi new FileSystemObserver(), cung cấp cho trình quan sát đó 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 FileSystemHandle của tệp hoặc thư mục đã chọn dưới dạng đối số. Khi quan sát một thư mục, bạn có thể chọn một đối số options không bắt buộc để biết liệu bạn có muốn được thông báo về các thay đổi đối với thư mục theo quy tắc đệ quy hay không (tức là đối với chính thư mục đó và tất cả thư mục con và tệp có trong thư mục đó). Tuỳ chọn mặc định là chỉ quan sát chính 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 gọi lại

Khi hệ thống tệp thay đổi, 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ể sử dụng đối số observer để, ví dụ: 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ả 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 hệ thống tệp có cấu trúc như sau. Tất cả các trường đều ở chế độ chỉ có thể đọc.

root (FileSystemHandle): Tay điều khiển được truyền đến hàm FileSystemObserver.observe().
changedHandle (FileSystemHandle): Tên xử lý chịu ảnh hưởng của thay đổi về hệ thống tệp. Trường này sẽ là null đối với 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 (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 được chuyển vào root.
- "disappeared": Tệp hoặc thư mục đã bị xoá hoặc bị di 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": Cho biết đã bỏ lỡ từ 0 sự kiện trở lên. Nhà phát triển nên thăm dò ý kiến về thư mục được theo dõi để phản hồi điều này.
- "errored": Quan sát không còn hợp lệ. Trong trường hợp này, bạn nên dừng quan sát 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 của số 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 xác định trước đượ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 để gửi giá trị này là khi tên người dùng được quan sát (tức là gốc của hoạt động quan sát) 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, theo sau là sự kiện "errored", cho biết rằng dữ liệu quan sát không còn hợp lệ. 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 tay cầm tệp bị xoá.
relativePathMovedFrom (Array, không bắt buộc): Vị trí cũ của một tay cầm đã di chuyển. Chỉ có sẵn khi type là "moved".

Lưu ý: Tuỳ thuộc vào hệ điều hành, không phải tất 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 đệ quy. Tốt nhất là trang web sẽ nhận được bản ghi thay đổi chi tiết chứa loại thay đổi và tên người dùng 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à type có giá trị "unknown"). Bản ghi này vẫn yêu cầu trang web liệt kê thư mục để tìm ra phần tử con nào đã thay đổi. Đây vẫn là một điểm cải tiến so với tính năng thăm dò ý kiến, vì việc liệt kê thư mục có thể được bắt đầu theo yêu cầu từ hàm gọi lại, thay vì cần thăm dò ý kiến về các thay đổi trong khoảng thời gian.

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

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

observer.unobserve(fileHandle);

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

Để ngừ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ử API Trình quan sát hệ thống tệp 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ý 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ử theo nguyên gốc của Chrome. 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 File System Observer API hoạt động trong màn hình minh hoạ được nhúng. Xem mã nguồn hoặc phối lại mã minh hoạ trên Glitch. Bản minh hoạ này tạo, xoá hoặc sửa đổi các tệp trong một thư mục được quan sát một cách ngẫu nhiên 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 API Trình quan sát hệ thống tệp, 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.