fsevents 项目技术文档

1. 安装指南

要使用 fsevents，您需要首先确保您的系统是 MacOS，并且安装了 Node.js。本项目支持 Node.js 版本 8.16 及以上。

安装步骤：

npm install fsevents

2. 项目的使用说明

fsevents 是一个允许 Node.js 应用程序访问 MacOS FSEvents API 的本地模块。这个 API 允许应用程序注册目录树的更改通知。

使用方法：

const fsevents = require('fsevents');

// 开始监听
const stop = fsevents.watch(__dirname, (path, flags, id) => {
  const info = fsevents.getInfo(path, flags);
});

// 结束监听
stop();

重要提示： 该 API 的行为与典型的 JS API 略有不同。stop 函数必须被检索并存储在某个位置，即使您不打算停止监视器。如果您忘记这样做，垃圾收集器最终会介入，监视器将被注销，您的回调将不再被调用。

.watch 方法的回调参数包含三个参数：

• path: string - 文件系统中已更改的项的路径
• flags: number - 一个数字值，描述了更改的内容
• id: string - 一个唯一标识符，用于标识此特定事件

该方法返回一个关闭回调，当调用时，返回一个 Promise，该 Promise 在监视器进程关闭时解析。

3. 项目API使用文档

fsevents 提供以下 API：

fsevents.watch(dirname: string, (path: string, flags: number, id: string) => void): () => Promise<undefined>

• 参数：
  • dirname: string - 要监听的目录路径
  • (path, flags, id) => void - 当操作系统检测到文件系统更改时调用的回调函数
• 返回值：
  • 返回一个关闭回调函数，用于停止监听

fsevents.getInfo(path: string, flags: number, id: string): FsEventInfo

• 参数：
  • path: string - 文件路径
  • flags: number - 更改标志
  • id: string - 事件唯一标识符
• 返回值：
  • 返回一个 FsEventInfo 对象，包含事件信息

FsEventInfo 对象结构：

{
  "event": "created", // {FsEventsEvent}
  "path": "file.txt",
  "type": "file",    // {FsEventsType}
  "changes": {
    "inode": true,   // iNode 元信息是否已更改
    "finder": false, // Finder 元数据是否已更改
    "access": false, // 访问权限是否已更改
    "xattrs": false  // 扩展属性是否已更改
  },
  "flags": 0x100000000
}

4. 项目安装方式

本项目通过 npm 包管理器进行安装。请确保您的系统已安装 npm。

安装命令：

npm install fsevents

确保您正在使用 Node.js 版本 8.16 或更高版本。如果您遇到任何与平台相关的问题，请确保您正在使用 MacOS 系统，因为 fsevents 仅支持 MacOS。