wl-screen-info

一个用于获取和设置屏幕分辨率的 Node.js 工具，支持 macOS 和 Windows 操作系统。这个库为不同平台提供了统一的屏幕分辨率管理接口。

功能特性

• 获取当前屏幕分辨率
• 设置屏幕分辨率
• 列出所有可用的屏幕分辨率
• 通过回调监听屏幕分辨率变化
• 跨平台支持（macOS 和 Windows）
• 支持 CommonJS 和 ES 模块两种导入方式

安装

npm install wl-screen-info

编程使用

CommonJS 导入方式

const { getResolution, setResolution, getAvailableResolutions, onResolutionChange } = require('wl-screen-info');

// 获取当前分辨率
getResolution().then(resolution => {
  console.log(`当前分辨率: ${resolution.width}x${resolution.height}`);
});

// 设置分辨率
setResolution(1920, 1080).then(() => {
  console.log('分辨率设置成功');
});

// 获取可用分辨率
getAvailableResolutions().then(resolutions => {
  console.log('可用分辨率:', resolutions);
});

// 监听分辨率变化
const listener = onResolutionChange(newResolution => {
  console.log(`分辨率已更改为: ${newResolution.width}x${newResolution.height}`);
});

// 在一段时间后停止监听
setTimeout(() => {
  listener.stop();
  console.log('已停止监听分辨率变化');
}, 60000); // 1分钟后停止

ES 模块导入方式

import { getResolution, setResolution, getAvailableResolutions, onResolutionChange } from 'wl-screen-info';

// 获取当前分辨率
try {
  const resolution = await getResolution();
  console.log(`当前分辨率: ${resolution.width}x${resolution.height}`);
} catch (error) {
  console.error('获取分辨率失败:', error);
}

// 设置分辨率
try {
  await setResolution(1920, 1080);
  console.log('分辨率设置成功');
} catch (error) {
  console.error('设置分辨率失败:', error);
}

// 获取可用分辨率
try {
  const resolutions = await getAvailableResolutions();
  console.log('可用分辨率:', resolutions);
} catch (error) {
  console.error('获取可用分辨率失败:', error);
}

// 监听分辨率变化
const listener = onResolutionChange(newResolution => {
  console.log(`分辨率已更改为: ${newResolution.width}x${newResolution.height}`);
}, 2000); // 每2秒检查一次

// 停止监听
someButton.addEventListener('click', () => {
  listener.stop();
  console.log('已停止监听分辨率变化');
});

系统要求

macOS

• 需要安装 cscreen 来设置和列出分辨率。可以使用 Homebrew 安装：

  brew install cscreen

• macOS 可能需要用户权限才能执行更改显示设置的命令

Windows

• 更改屏幕分辨率可能需要管理员权限
• 库使用 PowerShell 命令与显示设置交互
• 为了获得更好的性能，您可以选择安装 QRes，一个用于更改屏幕分辨率的小型工具

API

getResolution()

• 返回值: Promise<{width: number, height: number, displayId: number}>
• 获取当前屏幕分辨率和显示 ID

setResolution(width, height, [displayId=1])

• 参数:
  • width: number - 目标宽度
  • height: number - 目标高度
  • displayId: number (可选) - 目标显示设备 ID（默认为 1）
• 返回值: Promise
• 为指定的显示设备设置屏幕分辨率

getAvailableResolutions()

• 返回值: Promise<Array<{width: number, height: number}>>
• 获取可用屏幕分辨率列表

onResolutionChange(callback, [interval=1000])

• 参数:
  • callback: Function - 当分辨率更改时接收新分辨率的回调函数
  • interval: number (可选) - 轮询间隔（毫秒，默认为 1000）
• 返回值: 带有 stop() 方法的对象，用于停止监听
• 监听屏幕分辨率变化，并在检测到变化时调用提供的回调函数

测试

# 安装依赖
npm install

# 运行测试
npm test

# 在监听模式下运行测试
npm run test:watch

测试用例说明

当前项目包含 12 个测试用例，所有测试均已通过，代码覆盖率达到 100%。测试用例包括：

• 平台检测测试：验证在不同平台（darwin/win32）下正确选择对应实现，以及在不支持的平台上抛出适当的错误
• API 契约测试：
  • 验证 getResolution 返回正确的对象结构并正确传播错误
  • 验证 setResolution 正确处理参数和错误传播
  • 验证 getAvailableResolutions 返回正确的数组结构
  • 验证 onResolutionChange 正确处理回调函数和间隔参数（包括使用默认间隔值）

所有测试都是单元测试，通过模拟外部依赖实现跨平台测试。完整的集成测试需要在实际操作系统环境中进行。

手动测试说明

以下是针对每个功能的手动测试步骤，帮助您在实际环境中验证库的功能：

1. 测试获取当前分辨率

// 创建 test-resolution.js 文件
const { getResolution } = require('wl-screen-info');

getResolution()
  .then(resolution => {
    console.log('当前分辨率:', resolution);
    console.log(`宽度: ${resolution.width}, 高度: ${resolution.height}, 显示ID: ${resolution.displayId}`);
  })
  .catch(error => {
    console.error('获取分辨率失败:', error);
  });

执行命令：

node test-resolution.js

预期结果：输出当前显示器的分辨率信息。

2. 测试设置分辨率

注意：此操作会更改您的显示器分辨率，请谨慎操作！建议先记录当前分辨率以便恢复。

// 创建 test-set-resolution.js 文件
const { setResolution, getResolution } = require('wl-screen-info');

// 先获取并记录当前分辨率
let originalResolution;

getResolution()
  .then(res => {
    originalResolution = res;
    console.log('当前分辨率:', originalResolution);
    
    // 设置新分辨率（示例：1920x1080，请根据您的显示器支持的分辨率调整）
    return setResolution(1920, 1080);
  })
  .then(() => {
    console.log('分辨率设置成功');
    // 验证新分辨率
    return getResolution();
  })
  .then(newResolution => {
    console.log('新分辨率:', newResolution);
    
    // 可选：3秒后恢复原始分辨率
    setTimeout(() => {
      console.log('正在恢复原始分辨率...');
      setResolution(originalResolution.width, originalResolution.height)
        .then(() => console.log('原始分辨率已恢复'))
        .catch(err => console.error('恢复分辨率失败:', err));
    }, 3000);
  })
  .catch(error => {
    console.error('操作失败:', error);
  });

执行命令（Windows系统可能需要以管理员身份运行）：

node test-set-resolution.js

预期结果：屏幕分辨率短暂更改为指定值，然后在几秒后恢复原始分辨率。

3. 测试获取可用分辨率

// 创建 test-available-resolutions.js 文件
const { getAvailableResolutions } = require('wl-screen-info');

getAvailableResolutions()
  .then(resolutions => {
    console.log('可用分辨率列表:');
    resolutions.forEach((res, index) => {
      console.log(`${index + 1}. ${res.width}x${res.height}`);
    });
  })
  .catch(error => {
    console.error('获取可用分辨率失败:', error);
  });

执行命令：

node test-available-resolutions.js

预期结果：输出当前显示器支持的所有分辨率列表。

4. 测试监听分辨率变化

// 创建 test-resolution-change.js 文件
const { onResolutionChange } = require('wl-screen-info');

console.log('开始监听分辨率变化（按Ctrl+C停止）...');

// 开始监听分辨率变化，每500毫秒检查一次
const listener = onResolutionChange(newResolution => {
  console.log('检测到分辨率变化:', newResolution);
  console.log(`新分辨率: ${newResolution.width}x${newResolution.height}`);
}, 500);

// 1分钟后自动停止监听（可选）
setTimeout(() => {
  console.log('自动停止监听分辨率变化');
  listener.stop();
}, 60000);

执行命令：

node test-resolution-change.js

手动操作：在程序运行期间，手动更改显示器分辨率（通过系统设置或其他方式）。

预期结果：当分辨率发生变化时，程序会检测到并输出新的分辨率信息。

图形化测试界面

本项目还提供了一个基于Vue3的图形化测试界面，方便您直观地测试所有功能。

目录结构

图形化测试界面位于项目根目录下的test-ui文件夹中，采用Vue3 + Element Plus构建：

test-ui/
├── src/             # Vue源代码
│   ├── App.vue      # 主组件
│   └── main.js      # 应用入口
├── public/          # 静态资源
├── package.json     # 项目配置和依赖
├── vite.config.js   # Vite配置
├── index.html       # HTML入口
└── .gitignore       # Git忽略文件

启动测试界面

1. 进入test-ui目录：

cd test-ui

2. 安装依赖（如果尚未安装）：

npm install

3. 启动开发服务器：

npm run dev

4. 打开浏览器，访问输出中显示的URL（通常是 http://localhost:5173）

测试界面功能

图形化测试界面提供了以下功能：

1. 当前分辨率信息：显示当前屏幕分辨率，并可手动刷新
2. 设置分辨率：通过表单输入设置新的屏幕分辨率
3. 可用分辨率列表：显示所有可用的屏幕分辨率，并支持一键应用
4. 分辨率变化监听：实时监听分辨率变化，并记录变化历史

注意：由于浏览器安全限制，在Web环境中无法直接调用系统级API来修改屏幕分辨率。因此，测试界面使用了模拟数据和行为来演示功能。在实际Node.js环境中使用库时，所有功能将正常工作。

许可证

MIT