PowerToys 鸿蒙PC工具集工程解析:批量重命名计划生成、预乘 Alpha 图像重采样与文件处理流程

PowerToys 工具集是一个面向鸿蒙 PC 的独立 JavaScript 工具应用,基于 Electron 壳工程,将批量重命名、PNG/BMP 图片缩放、文件像素取色、目录检索、结构化文件预览和输入辅助组织在同一个窗口中。本文围绕现有源码,分析如何用六个 CommonJS 引擎支撑九个工具面板,以及如何连接目录扫描、改名计划、RGBA 像素处理、颜色计算和文件写入——重点展开“先计算、后执行”的重命名流程与预乘 alpha 图像重采样,并说明窗口配置、交互控件及打包资源的适配方式。

这里的 PowerToys 是参考 Microsoft PowerToys 部分交互习惯的独立实现,不是 Windows 原生 PowerToys 的完整移植。本文依据业务源码、工程配置与提供的三张应用截图编写;实际验证限于本机 Node.js 语法检查和少量引擎内存案例,不包含本次 HAP 构建、设备安装、真机性能测试或上架审核经历。

欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_PowerToys

一、技术架构分析

1.1 整体架构

本项目采用“鸿蒙 HAP 工程 + Electron 主进程 + 本地页面 + JavaScript 引擎”的分层结构:

  • 鸿蒙工程:electron 是入口模块,依赖本地 web_engine 模块,业务资源放在 web_engine 的 resfile/resources/app 下。
  • Electron 主进程:创建窗口,处理目录选择、扫描、文件读写、批量改名、剪贴板、文件定位和本窗口置顶。
  • 渲染进程:组织导航、表单、结果列表、Canvas 预览与状态反馈,通过 IPC 调用主进程能力。
  • 计算引擎:处理名称变换、图片编解码和重采样、颜色分析、检索计算、文本结构解析以及工具注册信息。

主要数据流可以表示为:

用户选择目录或文件
        ↓
main.js:目录范围登记 / 扫描 / 读取字节
        ↓ IPC
renderer.js:面板状态与交互调度
        ↓ require
六个 JavaScript 模块:生成计划 / 像素结果 / 解析报告
        ↓
DOM 或 Canvas 展示
        ↓ 用户执行保存或改名
main.js:实际写入 / rename / 对话框 / 执行结果

这个结构的价值,是将可独立验证的数据处理与平台窗口、文件操作分开。它并不意味着所有功能都脱离运行环境:图像引擎仍使用 Node.js 的 zlib,渲染层需要 DOM 和 Canvas,文件操作依赖 Electron IPC 与底层文件系统。

1.2 技术方案

设计维度当前工程采用的方案需要保留的边界
产品定位单窗口、九面板的本地效率工具集不是 Windows 系统增强服务的全量替代
UI 技术HTML、CSS、原生 DOM、Canvas 2D未引入 React、Vue 或第三方组件库
批量改名JavaScript 生成计划,主进程逐项执行不是原子事务,也没有循环交换名调度
图片处理自实现 PNG/BMP 编解码与三种重采样不支持 JPEG/WebP,不代表覆盖全部格式变体
文件检索对当前扫描结果进行筛选和排序不是常驻后台全盘索引
快捷键当前页面的键盘事件不提供系统全局热键
窗口置顶操作当前 BrowserWindow不管理其他应用窗口
部署业务资源随鸿蒙壳工程打包工程配置存在模板信息,不能直接等同发布就绪

“零第三方业务库”与“零运行时依赖”是两回事。这里前者成立,后者不成立:Electron、Node.js、鸿蒙壳模块和原生运行库仍是运行基础。

1.3 核心功能清单

工具主要能力注册表状态
PowerRename字面量/通配/正则替换、七种大小写规则、编号、计划与逆操作real
Image ResizerPNG/BMP、最近邻/双线性/Lanczos3、目标尺寸计算、图片输出real
Color Picker文件像素取色、十种格式输出、对比度、配色与主色板real
PowerToys Run工具搜索、数学表达式计算、体积换算、当前目录结果partial
Quick Machine Search文件名称与体积筛选、排序、文内查找和替换real
PeekJSON、Markdown、CSV/TSV、INI、XML/HTML 结构检查real
Always on Top请求当前应用窗口置顶并回读状态partial
Shortcut Guide应用内快捷键与工具列表说明partial
Quick Accent重音候选、字符反查、去音调及面板输入框插入partial

工具注册表统计为 9 项,其中 real 为 5 项、partial 为 4 项。它们是源码中的能力分类,不是动态自检结果,更不是“九项工具全部验收通过”的证明。注册表描述仍需与实现核对,例如窗口实际使用系统边框,不能沿用其中“配合无边框”的文字作功能结论。

二、环境准备

2.1 开发环境要求

项目当前可核对的信息
本文核对环境Windows、PowerShell,Node.js v22.20.0
页面技术HTML5、CSS、JavaScript、Canvas 2D
模块形式CommonJS,渲染层通过 require 加载引擎
业务包入口package.json 的 main 指向 main.js
工程产品default
兼容 SDK 配置5.0.5(17),release 阶段
runtimeOSHarmonyOS
入口设备类型2in1、tablet
鸿蒙开发工具与工程 SDK 匹配的 DevEco Studio 及相关工具链

这里的 Node.js 版本仅描述本文执行检查的本机环境,不是从截图推断出来的设备 Node 版本。设备实际 Electron、Node 和 Chrome 版本由 app:info 通道读取 process.versions 后展示。

部分引擎文件头写有“纯 ES5”,但实际使用了 Unicode 属性正则、正则后行断言、String.normalize、Math.cbrt 和 Object.assign 等能力。部署前应检查实际运行时支持情况,不能仅按注释认定 ES5 环境即可执行。

2.2 项目结构

以下只列与本文业务链路直接相关的文件:

ohos_PowerToys_electron-main/
└── ohos_hap/
    ├── AppScope/
    │   ├── app.json5
    │   └── resources/base/element/string.json
    ├── build-profile.json5
    ├── electron/
    │   ├── oh-package.json5
    │   └── src/main/module.json5
    └── web_engine/
        └── src/main/
            ├── module.json5
            └── resources/resfile/resources/app/
                ├── package.json
                ├── main.js
                ├── renderer.js
                ├── index.html
                ├── engines/
                │   ├── rename-engine.js
                │   ├── image-engine.js
                │   ├── color-engine.js
                │   ├── preview-engine.js
                │   ├── search-engine.js
                │   └── tools-core.js
                ├── styles/powertoys.css
                └── samples/
                    ├── _manifest.txt
                    ├── peek-sample.json
                    ├── peek-sample.csv
                    ├── img-chart-320x200.png
                    └── rename/

正文使用 web_engine/src/main/resources/resfile/resources/app 中的实际业务文件作为依据,不用 electron/build、.hvigor 等生成目录里的副本替代源码。

2.3 依赖说明

业务 package.json 当前内容如下:

{
  "name": "powertoys-ohos-shell",
  "version": "1.0.0",
  "description": "Microsoft PowerToys 风格系统增强工具集(鸿蒙 PC Electron 壳应用)",
  "main": "main.js",
  "author": "ohos_hap",
  "license": "MIT"
}

该文件没有 scripts、dependencies 或 devDependencies,不能据此使用 npm start,也不能假定 npm install 会为这里自动准备匹配的 Electron 运行时。

依赖或模块职责
ElectronBrowserWindow、ipcMain/ipcRenderer、dialog、clipboard、shell
Node.js fs/path文件操作、路径组合、偏好保存
Node.js zlibPNG IDAT 的压缩与解压
rename-engine.js名称变换、计划统计、操作列表与逆操作
image-engine.js字节解析、RGBA、重采样、图片编码
color-engine.js色彩空间转换、WCAG 对比度、量化
search-engine.js模糊检索、文本查找替换、计算器、重音字符
preview-engine.js文件结构解析和统计
tools-core.js工具信息、能力分类及注册表检索

鸿蒙模块层面的依赖也需要单独核对。electron/oh-package.json5 中使用本地依赖:

"dependencies": {
  "web_engine": 'file:../web_engine',
}

业务包的 MIT 字段与关于弹层里的“本项目 Apache-2.0”声明目前不一致。本文保留实际文件内容,不代替项目维护者确定最终许可证,也不把 Electron 自身的 MIT 协议与应用代码许可证混为一谈。

三、核心适配流程

3.1 主进程实现:窗口、目录范围与文件 IPC

主进程 main.js 负责系统能力,名称计算、图像缩放和结构解析则由渲染层引擎完成。窗口按工作区宽度的 92%、高度的 86% 初始化,并设置最小尺寸。

以下为 createWindow 的完整源码,依赖文件前面声明的 screen、BrowserWindow 和 mainWindow:

function createWindow() {
  try {
    var display = screen.getPrimaryDisplay();
    var width = display.workAreaSize.width;
    var height = display.workAreaSize.height;

    // 防 XComponent 崩溃:frame: true + transparent: false + resizable: true
    mainWindow = new BrowserWindow({
      width: Math.floor(width * 0.92),
      height: Math.floor(height * 0.86),
      minWidth: 900,
      minHeight: 600,
      frame: true,
      transparent: false,
      resizable: true,
      title: 'PowerToys 工具集',
      webPreferences: {
        nodeIntegration: true,
        contextIsolation: false
      }
    });

    mainWindow.loadFile('index.html');
    mainWindow.on('closed', function () { mainWindow = null; });
  } catch (e) {
    console.warn('[PowerToys] 创建窗口失败:', String(e && e.message));
  }
}

源码注释反映配置意图,不等于已经证明该配置能消除所有 XComponent 或原生崩溃。当前调用 try/catch 主要覆盖同步异常,不会自动接住所有异步加载失败。

主进程共注册 18 个请求响应通道:

分类IPC 通道作用
运行与偏好app:info、prefs:get、prefs:set运行时信息与扫描参数持久化
目录dir:choose、dir:trust、fs:scan选择和登记工作范围、扫描条目
读取fs:readText、fs:readBinary、samples:list文本、二进制及样例清单
写入fs:writeText、fs:writeBinary、file:saveText、file:saveBytes路径写入及保存对话框
文件操作rename:apply、files:choose、shell:reveal改名、选文件、文件管理器定位
系统交互clip:write、win:alwaysOnTop写剪贴板、本窗口置顶

启动时,应用自身目录和 userData 目录进入 allowedRoots。用户通过对话框选择其他目录或文件后,相关目录也会被登记。偏好文件 PowerToysPrefs.json 保存历史信息,但历史目录记录不等于重启后自动获得目录授权。

范围判断使用下面的字符串前缀函数,依赖 fwd 将反斜杠转换为正斜杠:

function isUnder(target, root) {
  var t = fwd(target), r = fwd(root);
  if (!t || !r) return false;
  if (t === r) return true;
  var sep = r.charAt(r.length - 1) === '/' ? r : r + '/';
  return t.indexOf(sep) === 0;
}

这个“目录授权表”属于应用工作流范围管理,不能当作强安全隔离:它没有使用 resolve/realpath 规范化路径,渲染层又开启了 Node 集成。对于不可信页面或任意路径输入,需要额外设计路径规范化、符号链接处理和受限桥接接口;本文未实施这些修改。

3.2 九个面板与工具注册表

页面采用顶部操作栏、左侧导航、右侧工具面板、底部状态栏的布局。renderer.js 直接加载六个业务模块:

var RN = require('./engines/rename-engine.js');
var IMG = require('./engines/image-engine.js');
var COL = require('./engines/color-engine.js');
var PV = require('./engines/preview-engine.js');
var SE = require('./engines/search-engine.js');
var TC = require('./engines/tools-core.js');

工具注册表为每个工具维护 id、name、category、status、engine、entry、capability、limits 和 basis。导航读取可进入的工具项,面板徽标读取 status,命令面板把工具说明转换为可检索条目。

tools-core.js 中的数量统计如下,依赖 TOOLS、STATUS 和 byStatus:

function stats() {
  return {
    total: TOOLS.length,
    real: byStatus(STATUS.REAL).length,
    partial: byStatus(STATUS.PARTIAL).length
  };
}

这种设计减少了导航、徽标和工具总览各自维护清单的重复。但“来自同一份数据”只能保证展示来源统一,不能保证说明文字天然准确;当扫描范围、格式支持或窗口行为变化时,注册表也需要同步检查。

渲染状态按业务拆分:重命名使用 plan 与 undoStack,图片使用 images、image 与 picked,预览使用 preview,文内检索使用 searchSel、searchText 与 replaceInfo。名称计划和图片像素结果是不同对象,不因共享一个窗口而混用。

HTML 使用本地脚本与样式,页面头部的实际声明为:

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; style-src 'self' 'unsafe-inline'">
<title>PowerToys 工具集</title>
<link rel="stylesheet" href="styles/powertoys.css">

动态结果主要通过 createTextNode、textContent 和节点组合展示。例如文件名、JSON 路径、搜索上下文不会被直接当作 HTML 执行。不过,CSP 并不能把已开启 Node 集成的渲染进程变成安全沙箱。

3.3 PowerRename:从名称规则到可执行计划

批量重命名最重要的不是一次调用多少次 rename,而是让用户先看到“哪些条目会改、改成什么、哪些项不能执行”。

rename-engine.js 将计算分成几个阶段:

  1. 将搜索条件编译为匹配器。
  2. 根据目录、隐藏条目、筛选词、排除词及数量限制筛选输入。
  3. 拆分名称主体和扩展名,决定规则作用部位。
  4. 展开替换模板、大小写变换、编号和前后缀。
  5. 检测非法名称、现存名称占用及计划目标冲突。
  6. 输出逐项状态和统计,不直接修改磁盘。

匹配器支持 literal、wildcard、regex 三种模式:

function buildMatcher(pattern, mode, opts) {
  opts = opts || {};
  var flags = 'g' + (opts.matchCase ? '' : 'i');
  var source;
  if (mode === MODE.REGEX) {
    source = String(pattern == null ? '' : pattern);
  } else if (mode === MODE.WILDCARD) {
    source = opts.wholeWord ? '\\b(?:' + wildToRe(pattern) + ')\\b' : wildToRe(pattern);
  } else {
    source = opts.wholeWord ? '\\b' + escapeRe(pattern) + '\\b' : escapeRe(pattern);
  }
  if (!source) return { ok: false, error: '搜索内容为空', source: '' };
  var re;
  try {
    re = new RegExp(source, flags);
  } catch (e) {
    return { ok: false, error: '表达式无法解析:' + source, source: source };
  }
  return { ok: true, re: re, source: source };
}

该节选依赖 MODE、wildToRe 和 escapeRe。字面量模式会转义正则特殊字符,通配模式转换星号、问号和字符集合;regex 分支直接使用表达式,不会额外套用 wholeWord。这里的整词边界使用 JavaScript 正则的词边界,不是完整的中文分词。

规则当前实现
作用部位文件名主体、扩展名、整个名称
大小写保持、随匹配项、小写、大写、词首大写、驼峰、互换
替换引用$0~$9、命名引用及转义字符处理
编号{N}、{N:000} 等补零写法,可设置起点和步长
附加规则前缀、后缀、空白处理、扩展名处理
计划状态rename、unchanged、nomatch、conflict、invalid、skipped 等

planRename 的输入是扫描条目和选项,输出含 items、stats、pattern、error。本文在内存中用 draft.txt、搜索 draft、替换 final、作用部位 name 验证,得到 final.txt,changed 为 1、conflict 为 0;没有对磁盘执行改名。

只有状态为 rename 的条目才进入执行列表:

function buildOps(plan) {
  var ops = [];
  (plan.items || []).forEach(function (it) {
    if (it.status !== 'rename') return;
    ops.push({ from: it.path, to: siblingPath(it.path, it.newName), index: it.index });
  });
  return ops;
}

该函数依赖 siblingPath 生成同目录目标路径。主进程收到列表后,再检查源路径、目标占用和目录范围,逐项执行 fs.renameSync。因此计划通过并不代表执行时磁盘状态一定仍然相同。

撤销也不是简单交换整批请求,而是只为成功项生成逆操作,并反转顺序:

function invertOps(ops, results) {
  var undo = [];
  for (var i = ops.length - 1; i >= 0; i--) {
    var r = results && results[i];
    if (!r || !r.ok) continue;
    undo.push({ from: ops[i].to, to: ops[i].from });
  }
  return undo;
}

这里有三条需要明确的边界:当前执行不是事务;父目录与子项同批改名会产生路径依赖;部分撤销成功后,渲染层仍保留整批逆操作,并没有剔除已撤销项。实际处理前应在独立目录副本中验证,不应把撤销栈当作完整备份机制。

3.4 Image Resizer:PNG/BMP、RGBA 与三种重采样

图像引擎采用统一像素模型:宽、高和按 RGBA 顺序排列的 Uint8Array。每个像素占四字节,坐标到数组偏移的关系为:

offset = (y × width + x) × 4
pixels[offset + 0] = R
pixels[offset + 1] = G
pixels[offset + 2] = B
pixels[offset + 3] = A

格式入口根据文件签名派发,而不是只相信扩展名:

function decodeImage(buf) {
  var fmt = sniffFormat(buf);
  if (fmt === FORMATS.PNG) return pngDecode(buf);
  if (fmt === FORMATS.BMP) return bmpDecode(buf);
  return { ok: false, width: 0, height: 0, pixels: null, format: '', error: '不是可处理的图片(当前仅支持 PNG / BMP)' };
}
function encodeImage(img, format) {
  if (format === FORMATS.BMP) return bmpEncode(img);
  return pngEncode(img);
}

PNG 解码:先恢复字节,再展开像素。

解码过程检查签名和块长度、核对 CRC,读取 IHDR、PLTE、tRNS 和 IDAT,使用 zlib 解压,再逐行还原滤波数据。PNG 五种行滤波中,Paeth 预测器依赖左侧、上侧和左上侧字节:

function paeth(a, b, c) {
  var p = a + b - c;
  var pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
  if (pa <= pb && pa <= pc) return a;
  if (pb <= pc) return b;
  return c;
}

unfilter 内部的反滤波分支如下,a、b、c 和 v 由当前行及上一行计算,最终按八位回绕:

var rec;
if (ft === 0) rec = v;
else if (ft === 1) rec = v + a;
else if (ft === 2) rec = v + b;
else if (ft === 3) rec = v + ((a + b) >> 1);
else rec = v + paeth(a, b, c);
out[cur + x] = rec & 0xff;

位打包样本再转换到八位通道。源码存在 1/2/4/8/16 位深分支,但 16 位样本只取高字节,内部并不保留十六位精度;Adam7 隔行 PNG 被明确拒绝。输出 PNG 统一为八位 RGBA,也不会完整保留输入图片的所有附加元数据。

BMP 分支处理行跨度四字节对齐和正负高度,存在 1/4/8/24/32bpp 分支,输出为 32bpp BI_RGB。分支存在不等于格式全覆盖:当前允许 compression=3,却未解析任意通道位掩码;索引色调色板字段处理也需要专项样本验证。

重采样:像素结果与界面缩放分离。

方法实现要点适用考虑
nearest目标像素中心映射到源坐标,取最近像素保留硬边缘和像素风格
bilinear四邻域加权,RGB 先预乘 alpha,再反预乘透明边缘需要避免隐藏色直接混入
lanczos3sinc 核、两趟可分离卷积,缩小时扩展核并归一权重更重视细节时使用,但计算和内存成本更高

双线性的透明处理可概括为:

alpha = Σ(weight × sourceAlpha)
premultipliedColor = Σ(weight × sourceColor × sourceAlpha)
color = premultipliedColor / alpha

这一步处理透明度插值,并不等于已经在线性光色彩空间中完成全部图像处理。实现中还需要对接近零的 alpha 作保护。

Lanczos3 的核函数如下;横向和纵向卷积过程位于同文件的 lanczosResample:

function sinc(x) { return x === 0 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x); }
function lanczos3(x) {
  if (x <= -3 || x >= 3) return 0;
  if (x > -1e-7 && x < 1e-7) return 1;
  return sinc(x) * sinc(x / 3);
}

界面中的 Canvas 用于显示实际像素数组,CSS 宽度仅决定预览占用的屏幕空间。renderer.js 的画布绘制函数如下,依赖 DOM 查询函数 $:

function paintCanvas(img) {
  var cv = $('imCanvas');
  cv.width = img.width;
  cv.height = img.height;
  var ctx = cv.getContext('2d');
  ctx.clearRect(0, 0, img.width, img.height);
  ctx.putImageData(new ImageData(new Uint8ClampedArray(img.pixels), img.width, img.height), 0, 0);
  var k = Math.min(1, 620 / img.width, 420 / img.height);
  // 只定宽度,高度交给 aspect-ratio 跟随:被栅格 max-width 夹住时也只等比缩,不会压扁
  cv.style.aspectRatio = img.width + ' / ' + img.height;
  cv.style.width = Math.max(1, Math.round(img.width * k)) + 'px';
  cv.style.height = 'auto';
}

点击取色时,再按画布内部尺寸与显示矩形的比例转换坐标,然后从 RGBA 数组读取像素。它不是屏幕抓色,也不依赖当前预览在屏幕上显示了多少像素。

三个操作按钮的含义不能混用:

  • “计算目标尺寸”:仅计算宽高,不替换当前图像。
  • “缩放并保存”:逐图读取、解码、计算尺寸、重采样和编码,写入当前工作目录的 powertoys-resized 子目录。
  • “另存当前”:直接编码当前 state.image.img,不自动使用刚计算的目标尺寸。

批处理按文件基本名生成目标名,因此不同来源的同名文件、转换后同名文件存在覆盖风险;批量输出也不会自动把当前预览替换为缩放后的结果。

3.5 颜色、搜索计算与结构化预览

颜色计算:统一通道,区分输入与输出能力。

color-engine.js 支持十种格式输出:HEX、十六进制整数、RGB、RGBA、HSL、HSLA、HSV、CMYK、CIELAB 和 CIELCh。命名色表实测为 77 项。

sRGB 线性化是颜色计算的基础,源码如下:

function srgbToLinear(v) {
  var c = clamp(v, 0, 255) / 255;
  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
}

该函数依赖 clamp。RGB 到 XYZ、Lab 和 LCh 的链路使用 D65 参考白,色差使用 ΔE76,而不是 ΔE2000。CMYK 是公式换算,不包含 ICC 印刷色彩管理。

WCAG 相对亮度和对比度实现为:

function relativeLuminance(c) {
  return srgbToLinear(c.r) * 0.2126 + srgbToLinear(c.g) * 0.7152 + srgbToLinear(c.b) * 0.0722;
}
function contrastRatio(c1, c2) {
  var l1 = relativeLuminance(c1), l2 = relativeLuminance(c2);
  var hi = Math.max(l1, l2), lo = Math.min(l1, l2);
  return Math.round(((hi + 0.05) / (lo + 0.05)) * 100) / 100;
}

wcagReport 输出普通文本 AA/AAA、大字 AA/AAA、UI 组件五个布尔判定,以及一个文字等级。当前比值先保留两位小数再判断阈值,且不合成透明前景与实际背景,因此临界值和半透明颜色需要额外复核。

主色板使用中位切分:按通道跨度选择盒子,排序后分裂,取盒内平均色作为代表色。默认忽略 alpha 不大于 8 的像素,比例分母是参与量化的像素数,不是整幅图片的全部像素数。

检索与计算器:查询数据,不执行用户 JavaScript。

模糊匹配优先连续子串,再尝试贪心子序列;排序还叠加词项得分和编辑距离回退。返回的 ranges 为半开区间,供界面突出匹配字符。

引擎提供扩展名、体积、文件/目录、排除词等选项,五种排序键为 score、name、size、time、ext。当前 doSearch 主要传入名称、体积、文件/目录和排序参数,不能把引擎所有可选项都写成界面已经接入的筛选功能;时间字段用于排序,不是时间范围筛选器。

命令面板分别尝试数学表达式、体积解析、工具注册表和当前目录匹配,结果可以同时出现。点击工具结果切换面板,点击目录结果请求文件管理器定位,不会将输入当成 shell 命令执行。

数学计算器采用“分词 → 调度场算法转逆波兰式 → 栈求值”的链路:

function calculate(expr) {
  var res = { ok: false, value: null, text: '', error: '' };
  var tk = tokenizeExpr(expr);
  if (!tk.ok) { res.error = tk.error; return res; }
  if (!tk.tokens.length) { res.error = '表达式为空'; return res; }
  var rp = toRpn(tk.tokens);
  if (!rp.ok) { res.error = rp.error; return res; }
  try {
    var v = evalRpn(rp.rpn);
    if (!isFinite(v)) { res.error = '结果不是有限数值'; return res; }
    res.ok = true; res.value = v;
    res.text = formatNumber(v);
    return res;
  } catch (e) {
    res.error = e.message || '表达式无法求值';
    return res;
  }
}

节选依赖同文件中的 tokenizeExpr、toRpn、evalRpn 和 formatNumber。函数与常量来自白名单,不使用 eval 或 new Function。本文实际计算 sqrt(81)+2^3,得到 17;这只验证该表达式,不构成所有语法组合的兼容性证明。

Peek:展示解析结果,不执行文件内容。

preview-engine.js 按扩展名和内容线索选择解析器:

类型处理内容当前边界
JSON递归下降、行列错误、节点/深度、重复键、路径、格式化接受注释,不是严格 JSON 规范验证器;JSONL 未逐行解析
Markdown标题、列表、任务、围栏、表格、链接等结构不是完整 Markdown 渲染器
CSV/TSV引号状态机、双写转义、跨行字段、列画像列数不齐会记录;未闭合引号没有严格失败判定
INI段、键值、注释、重复键与异常行不等同于所有配置格式或 properties 转义语义
XML/HTML标签计数和栈配对不是完整 XML/HTML 解析器,不渲染或执行页面
普通文本/代码/日志行号、行尾、缩进线索和文本统计不包含完整语法高亮或字符集自动转换

JSON 解析入口中维护当前位置、行列和深度上限,递归深度判断节选如下:

if (depth > stats.depth) stats.depth = depth;
if (depth > maxDepth) fail('嵌套深度超过上限 ' + maxDepth);

这是 parseJson 内部 value 函数的一部分,依赖其闭包状态,不是独立调用片段。默认最大深度为 200。格式化和路径遍历使用解析得到的对象,因此源文本的空白、注释以及重复键不会原样保留。

文内替换另有“内存预览 → 写备份 → 覆盖原文件 → 回读检索”的链路。备份位于当前工作目录的 powertoys-backup 下,但它来自读取缓存的 UTF-8 文本,并非原始字节副本;截断读取、同名备份覆盖和缓存失效问题仍需处理,详见第六章。

Quick Accent:把 Unicode 组合规则落到面板输入框。

引擎登记十种组合标记,加上“无附加符号”,共十一项。候选由英文字母与组合标记经过 NFC 正规化产生,无法合成为单字符时保留组合序列。点击候选通过 selectionStart、selectionEnd 插入 acText,而不是向其他应用注入键盘事件。

去音调函数如下:

function deaccent(text) {
  var s = str(text);
  if (!canNormalize()) return s;
  return s.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
}

它依赖 str 和 canNormalize,移除的是 U+0300~U+036F 范围内的组合标记,不是覆盖所有语言的转写系统。本文验证 a 加 acute 得到 á,返回一个预组字符。

3.6 Catppuccin Mocha 深色主题

样式层使用 Catppuccin Mocha 配色,通过根变量统一控制工作区、表单、状态和交互强调色:

:root {
  --base: #1e1e2e;
  --mantle: #181825;
  --crust: #11111b;
  --surface0: #313244;
  --surface1: #45475a;
  --surface2: #585b70;
  --overlay0: #6c7086;
  --overlay1: #7f849c;
  --text: #cdd6f4;
  --subtext0: #a6adc8;
  --subtext1: #bac2de;
  --blue: #89b4fa;
  --lavender: #b4befe;
  --sky: #89dceb;
  --teal: #94e2d5;
  --green: #a6e3a1;
  --yellow: #f9e2af;
  --peach: #fab387;
  --rosewater: #f5e0dc;
  --flamingo: #f2cdcd;
  --pink: #f5c2e7;
  --mauve: #cba6f7;
  --red: #f38ba8;
}

布局上,外框使用三行 Grid,主区域再拆为侧栏与内容。minmax(0, 1fr) 和内部滚动容器用于限制结果区挤压其他区域:

#appFrame {
  display: grid;
  grid-template-rows: auto minmax(0, 1fr) auto;
  height: 100vh;
}
#mainArea {
  display: grid;
  grid-template-columns: 248px minmax(0, 1fr);
  min-height: 0;
}

工具状态同时提供颜色和文字,不能只看绿点或黄点判断功能是否经过实测。图片预览区的棋盘格表示透明背景;在尚未载入图片时,它也会作为空预览底纹出现。

四、鸿蒙稳定性适配

本章记录当前代码已经采用的配置和需要继续验证的边界,不把其他项目的故障经过移植成 PowerToys 的真机排障记录。

4.1 禁用默认菜单栏

问题现象: 默认应用菜单与页面工具栏可能形成两套入口,工具集希望统一由页面导航和操作按钮承载业务交互。本文没有另行复现菜单导致的设备故障。

根因分析: Electron 菜单与 DOM 工具栏属于不同机制,默认菜单不会自动与九个面板的命令保持一致。

解决方案: 当前 main.js 在创建窗口前移除应用菜单:

Menu.setApplicationMenu(null);

常用操作通过页面按钮与应用内快捷键进入。快捷键说明表列出七组说明,包括 Alt+1~9、Ctrl+Shift+P、Alt+R、Alt+S、Alt+T、输入框 Enter 和 Esc。真正的键盘处理位于 onKeyDown 及各输入框绑定中,说明表不是自动生成事件绑定的命令注册系统,维护时仍要双向核对。

4.2 自定义下拉与关于弹层

问题现象: 九面板共享大量选择控件和说明窗口,需要统一外观及状态;如果让每个控件各自维护显示值和实际值,容易产生界面与计算参数不一致。

根因分析: 选择器不仅有选项列表,还涉及 data-value、selected 类和显示文字;关于说明则不需要额外创建系统模态窗口。

解决方案: 当前页面使用 .custom-select 和 DOM 关于弹层。setSelectValue 同时更新选中样式、实际值和文字:

function setSelectValue(root, value) {
  var opts = Array.prototype.slice.call(root.querySelectorAll('.select-option'));
  var picked = null;
  opts.forEach(function (o) {
    var hit = o.getAttribute('data-value') === value;
    if (hit && !picked) picked = o;
  });
  if (!picked) return;
  opts.forEach(function (o) {
    if (o === picked) o.classList.add('selected'); else o.classList.remove('selected');
  });
  root.setAttribute('data-value', picked.getAttribute('data-value'));
  setDisplayText(root, picked.textContent);
}

该函数依赖 setDisplayText。用户点击选项后,还会由事件处理器调用对应联动函数;程序化设置值并不自动等同于触发完整点击链路。

关于弹层通过 hidden 类切换可见状态:

function openAboutDialog() {
  var l = document.getElementById('aboutDialogLayer');
  if (l) l.classList.remove('hidden');
}
function closeAboutDialog() {
  var l = document.getElementById('aboutDialogLayer');
  if (l) l.classList.add('hidden');
}

当前做法避免为这类页面说明额外创建窗口,但文件选择和保存仍使用 Electron dialog,不能概括为“整个应用完全不用原生对话框”。自定义控件的键盘导航、焦点管理与辅助技术体验,也需要独立验收。

4.3 窗口配置与运行边界

配置当前值或调用实际含义
硬件加速app.disableHardwareAcceleration()关闭硬件加速路径,不代表性能必然更好
frametrue使用系统窗口边框
transparentfalse不创建透明窗口
resizabletrue允许调整窗口尺寸
最小尺寸900×600提供布局下限,不能替代各尺寸检查
nodeIntegrationtrue页面可 require Node/CommonJS 模块
contextIsolationfalse当前页面不是隔离的预加载桥接架构
createWindow 异常处理try/catch处理同步异常,不能兜住全部原生与异步故障

Always on Top 的实现只操作 mainWindow,并回读 Electron 状态:

ipcMain.handle('win:alwaysOnTop', function (event, req) {
  var on = !!(req && req.on);
  if (!mainWindow) return { success: false, on: false, error: '窗口不可用' };
  try {
    mainWindow.setAlwaysOnTop(on, 'floating');
    mainWindow.setSkipTaskbar(false);
    return { success: true, on: mainWindow.isAlwaysOnTop() };
  } catch (e) {
    return { success: false, on: false, error: '当前平台不支持窗口置顶' };
  }
});

这个节选依赖 ipcMain 与 mainWindow。API 回读比单纯翻转前端布尔值更有依据,但窗口管理器是否按预期表现,仍需要设备测试确认,本文不宣称已经验证跨应用覆盖效果。

4.4 IPC 错误反馈与同步计算负载

问题现象: 文件读取、解码或写入失败时,用户需要知道失败发生在哪一步;大图计算又可能让页面暂时无法响应。当前三张截图不足以证明这些异常路径或重负载场景已经通过。

根因分析: IPC 调用失败、返回值表示业务失败、结果处理器抛异常是三种不同情况;此外,PNG 解压、重采样和主色量化主要是渲染进程中的同步计算,串行批处理并不等于后台线程处理。

解决方案: 当前 renderer.js 对请求及同步结果处理作统一反馈:

function call(ch, payload) { return ipcRenderer.invoke(ch, payload || {}); }
function ask(ch, payload, onOk) {
  return call(ch, payload).then(function (r) {
    try { onOk(r); } catch (e) { status('结果处理异常(' + briefErr(e) + ')', 'err'); }
  }).catch(function (e) {
    status(ch + ' 调用失败(' + briefErr(e) + ')', 'err');
  });
}

节选依赖 ipcRenderer、status 和 briefErr。各业务回调还会检查 success 或 ok。它没有 IPC 超时机制,顶层 require 失败也发生在该包装器之外,不能说所有故障都已被统一捕获。

当前资源约束应分层理解:

位置现有约束未被它覆盖的情况
目录扫描深度 0~4,最多返回 4000 条不是全盘索引与耗时预算
文本读取默认返回至多约 2MiB,可请求上限 8MiBreadFileSync 先读完整文件,不是读取内存硬上限
二进制读取超过 32MiB 先拒绝不限制压缩数据解开后的内存
PNG/BMP 解码单边最大 8192不等于输出缩放尺寸也有同一上限
文内检索界面请求最多 2000 个匹配,展示前 400 个不限制单次正则回溯耗时
Lanczos3/量化顺序执行计算中间像素数组、浮点缓冲和排序仍可能很大

进一步的输出像素预算、解压长度限制、工作线程、取消机制和异常后批处理推进属于后续改进方向,本文没有将其写成已经实施的优化,也没有套用其他项目的“IPC 旁路 fs 直写”结论。

五、构建与部署

以下三张图来自项目提供的上架素材目录,用于说明界面布局和可见状态,不是本文新执行的测试截图。

在这里插入图片描述

图一:PowerRename 面板。当前工作目录指向应用自身目录,界面显示 7 个条目,其中 4 个文件、3 个目录;计划表为空,“执行改名”和“撤销上一次”不可用。它展示规则输入及初始状态,不表示已经成功完成批量改名。顶部 5/4 为注册表能力分类数量。

在这里插入图片描述

图二:Image Resizer 面板。工作目录已切换到 samples,界面显示 23 个条目,递归选项为下探 1 层。图片尚未选择,棋盘格是预览背景,像素统计和批处理结果尚未生成;显示 Lanczos3、PNG 和尺寸参数并不能证明已执行缩放。扫描说明里的“进入 2 层”来自 visited 目录访问计数,不宜解读为实际最大递归深度。

在这里插入图片描述

图三:关于弹层覆盖在 Image Resizer 页面上,展示独立 JavaScript 实现说明、免责声明和项目许可证文案。截图中的 Apache-2.0 声明与当前 package.json 的 MIT 字段不一致,需要维护者进一步统一,不能把此图当作许可证合规结论。

5.1 本地调试与本文验证结果

桌面调试应从实际业务目录启动,而不是从工作区根目录或 ohos_hap 根目录启动。已准备好兼容版本的桌面 Electron,并使其命令可用时,可以在业务目录执行:

electron .

这是后续调试方式说明,本次没有启动桌面 Electron。业务 package.json 未固定 Electron 版本,桌面运行结果也不能直接替代鸿蒙壳运行结果。

语法检查不需要启动窗口。在同一业务目录可逐项检查:

node --check main.js
node --check renderer.js
node --check engines/rename-engine.js
node --check engines/image-engine.js
node --check engines/color-engine.js
node --check engines/preview-engine.js
node --check engines/search-engine.js
node --check engines/tools-core.js

本文已在 Node.js v22.20.0 中执行上述八个文件的语法检查,并直接调用现有引擎获得以下结果。图片和文本样例只读,编码、重采样、名称计划均在内存完成,没有写入测试产物。

验证对象实际输入本次结果
JavaScript 语法main、renderer 和六个引擎8 个文件通过
工具注册表tools-core.stats()total=9、real=5、partial=4
色彩与重音常量FORMATS、namedList、ACCENT_MARKS10 种输出格式、77 个命名色、11 个重音表项
名称计划draft.txt,draft → finalfinal.txt,changed=1,无冲突
数学表达式sqrt(81)+2^317
黑白对比度不透明黑色与白色 RGB21
重音候选a、acuteá,预组字符
PNG 解码img-chart-320x200.png320×200,64000 像素
像素统计同一 PNG平均 RGB=(79,81,94),平均 alpha=255,不透明比例=1
PNG 内存往返解码 → PNG 编码 → 解码RGBA 数组逐字节一致
三种重采样同一图片缩至 80×50nearest、bilinear、lanczos3 均返回成功及目标尺寸
JSON 正常样例peek-sample.json30 节点、最大深度 5
JSON 错误样例peek-sample-broken.json报错:缺少逗号,第 7 行第 3 列
CSV 样例peek-sample.csv4 列、7 个数据行、2 行列数不齐

上述结果证明这些特定输入经过了实际计算,不证明所有 PNG/BMP 变体、所有表达式、全部文本编码或设备 UI 均已兼容。三种重采样本次核对的是成功返回和尺寸,不是视觉质量或性能排名。

5.2 业务资源与鸿蒙模块的衔接

本工程业务资源已位于:

web_engine/src/main/resources/resfile/resources/app/

应把 main.js、renderer.js、index.html、engines、styles、package.json 和所需 samples 作为一个相互配套的资源集合检查。不要只更新页面而遗漏引擎,也不要把生成目录中的旧副本当作编辑入口。

当前不需要为本文建立第二份 electron-apps 开发目录,也不需要清空部署目录后重新复制。本次只新增文章及三张配图,未更改这些应用资源。

如果以后采用独立开发副本,应明确唯一源码来源,并在打包前对入口和资源进行内容核对。历史 build 目录或已有 HAP 的存在,只能说明有过产物,不能证明当前目录和当前源码刚刚构建成功。

5.3 HAP 构建与部署检查点

在 DevEco Studio 中打开 ohos_hap 工程后,应按当前配置核对:

检查项当前值或状态
产品default
入口模块electron,type=entry
入口目标default,应用到产品 default
本地依赖模块web_engine,type=har
compatibleSdkVersion5.0.5(17)
runtimeOSHarmonyOS
bundleNamecom.huawei.ohos_electron
AppScope 基础 app_nameElectron
AppScope 版本versionName=1.0.0、versionCode=1000000

产品名、模块名和目标名是不同字段,不能把 electron 或 ohos_hap@electron 直接当作当前产品名。

完成依赖同步、SDK 匹配和签名材料核对后,可使用 IDE 的 HAP 构建入口。签名证书、profile、密钥别名与包名需与实际发布配置匹配,本文不展示私密签名材料,也不虚构一次构建成功记录。

入口模块仍包含快捷方式 metadata,web_engine 仍声明多类权限,包括文件目录访问、位置、相机、麦克风等。是否保留,应根据真实调用链、壳依赖与发布要求逐项评估;本文没有删权限、改包名、改签名或宣称已经满足审核条件。

后续设备验收至少应覆盖:冷启动、目录与文件对话框、窗口尺寸变化、小批改名及部分失败撤销、三种图片算法导出回读、截断文本写入保护、置顶实际表现和本窗口快捷键。本文未执行这些设备操作。

六、常见问题与解决方案

以下问答区分当前源码行为、本文内存验证和后续改进建议。静态风险不等于已经发生过的真机事故,建议也不等于已提交修复。

Q1:窗口已经显示 PowerToys,为什么工程里仍有 Electron 名称?

问题现象: main.js 与 HTML 标题为 PowerToys 工具集,但 AppScope 的基础 app_name 仍是 Electron,bundleName 仍是 com.huawei.ohos_electron。

根因分析: 页面标题、BrowserWindow 标题、AppScope 标签、入口 Ability 标签和多语言资源是不同层次的配置,修改一处不会自动覆盖其余层次。

解决: 发布准备时分别核对 AppScope 与入口模块引用的标签、各语言目录的同名资源,以及包名与签名材料的对应关系。本文只记录当前状态,没有修改这些配置,也没有据此断言某台设备一定显示哪个名字。

教训: 业务 UI 完成与发布元信息完成是两项独立工作,不能用窗口截图替代包配置检查。

Q2:生成计划没有报错,是否可以把批量改名当作事务?

问题现象: 计划中可执行的项目,在实际执行时仍可能失败;对多层目录和交换名称尤其不能保证整批完成。

根因分析: 主进程逐项 renameSync,执行前检查目标占用;冲突键使用文件/目录类别加小写名称,没有父目录路径,可能误判跨目录同名,也可能漏掉同路径文件与目录互相占名。父目录改名还会影响后续子路径。

解决: 当前使用时应优先处理独立目录副本、单层且目标不互相依赖的批次,并逐项核对返回结果。若继续开发,可按规范化父路径建立冲突键,为交换名设计临时名调度,并在部分撤销后仅保留未完成逆操作。这些改进本次未实施。

教训: 可预览、可执行、可撤销不等于事务原子性;撤销失败时还需要人工核对实际文件状态。

Q3:点击“计算目标尺寸”后另存,为什么不是新尺寸?

问题现象: 目标尺寸已经显示,但“另存当前”仍可能输出原尺寸图像。

根因分析: calcTarget 只计算尺寸;saveCurrentImage 调用的是 encodeImage(state.image.img, fmt),没有先调用 resample。真正串联重采样与文件写入的是“缩放并保存”。

解决: 按当前按钮语义使用“缩放并保存”,并从批处理结果对应路径核对输出。若以后希望“另存当前”也应用目标尺寸,需要明确状态更新和按钮语义,不能只更改提示文字。不同目录同名图片还应拆批或先规划唯一输出名。

教训: 预览大小、目标尺寸、内存像素和最终导出文件是四个不同状态,不能靠界面上的数字推断它们已经同步。

Q4:为什么十种颜色格式输出不代表十种字符串都能回填解析?

问题现象: 面板可以输出 Lab、LCh 等格式,但把输出文字直接粘回输入框,不一定得到同样颜色。

根因分析: 数值转换函数、format 输出函数与 parseColor 输入语法是不同接口。parseColor 没有 Lab/LCh 分支,部分带百分号输出与 Number 解析方式也不完全对称。另外,对比度计算未处理 alpha 背景合成。

解决: 按当前解析器支持的写法输入,常用不透明颜色可优先使用 HEX/RGB;需要透明叠加或临界对比度判定时,另行合成和复核。完善格式回读、数值校验与未舍入阈值判断属于后续工作。

教训: “有转换函数”不能推出“所有文本格式双向无损往返”,颜色科学公式也不能替代完整色彩管理流程。

Q5:文本替换已经先备份,是否就能安全处理任意文件?

问题现象: replaceWrite 包含备份、写入、回读三步,但这仍不足以保证原文件内容完整可恢复。

根因分析: 当前读取默认按 UTF-8 返回有限长度文本;截断标记没有成为写入禁用条件。备份写的是缓存文本,不是原始字节;缓存是否重算仅比较新旧替换结果长度,改变为同长度替换内容时可能继续使用旧结果;备份名只含基本名,且没有磁盘版本检查。

解决: 当前不应对唯一副本、超读取上限或非 UTF-8 文件使用该覆盖替换流程。后续应拒绝截断内容写入、保存原始字节备份、按文件版本和完整参数使预览失效,并明确区分写入成功、回读失败与校验失败。本文未进行覆盖写盘测试,也未实施这些修复。

教训: “备份存在”和“回读命中数改变”都不是内容完整性的充分证明;文件工具必须把数据保护作为独立流程设计。

Q6:Peek 的“解析通过”可以当作格式标准校验结论吗?

问题现象: CSV 样例有两行列数不齐,入口仍返回 ok=true;JSON 解析器也接受注释。

根因分析: Peek 面向结构查看,部分异常被记录在 detail 中,而不是统一转换为失败。XML/HTML 使用标签扫描与栈检查,Markdown 使用结构规则,并非完整标准解析器。

解决: 同时检查 ok、error、notes 和 detail 中的异常项;需要严格格式验收时,应使用相应标准验证器。当前 JSONL 扩展名会走单个 JSON 文档解析,也不能据扩展名映射声称已支持逐行 JSONL。预览按钮目前重新展示缓存结果,外部修改文件后应重新打开文件获取新内容。

教训: 结构预览器、容错解析器、格式化器和严格验证器承担不同职责,不能仅凭一个成功标记替代它们之间的区别。

Q7:三张截图和“已实现 5 项”是否说明已经可以直接发布?

问题现象: 截图能够展示导航、参数和关于说明,顶部也显示能力数量,但它们没有提供完整业务验收、构建或审核证据。

根因分析: 数量来自静态注册表;两张功能图尚未进行改名或图像处理;工程保留模板包名、基础应用名及多类权限;关于弹层和 package.json 的项目许可证声明尚未统一。

解决: 将源码能力核对、内存案例、文件写入验证、设备交互、签名打包、许可证确认和发布审核分开记录。许可证范围应由维护者依据实际来源确认,权限与快捷方式按真实需求评估,不能直接沿用其他项目的精简清单。本文只完成文章所需核对,不代替发布验收。

教训: 能力说明、运行截图和发布资格是三类证据,各有作用范围,不能相互替代。

七、总结

PowerToys 工具集的核心适配思路,是把一组有明确输入和输出的本地工具放入统一 Electron 窗口:名称规则先生成计划,图片先解码为 RGBA,结构化文件先解析为数据,再由页面展示和主进程完成文件操作。

特性当前实现方案
工具组织九面板、四类工具、注册表驱动导航和能力标记
批量重命名三种匹配模式、七种大小写、编号、冲突提示、成功项逆操作
图像处理PNG/BMP 字节解析、RGBA、最近邻/双线性/Lanczos3、格式输出
颜色分析十种格式输出、77 个命名色、D65/Lab、ΔE76、WCAG 和中位切分
检索与计算扫描结果排序、文本查找替换、白名单数学解释器
文件预览JSON、Markdown、CSV/TSV、INI、XML/HTML 与文本统计
输入与窗口面板内重音插入、应用内快捷键、本窗口置顶请求
UI 与适配Catppuccin Mocha、自定义下拉、DOM 关于弹层、主进程 IPC
本文验证八文件语法检查与有限引擎案例,未执行 HAP/设备验收

从当前工程中最值得提炼的三个经验是:

  1. 先建立中间结果,再执行有副作用的操作。 改名计划、RGBA 像素和结构化解析结果都让计算过程更容易检查;但计划、执行与回滚仍需分别处理失败,不能将中间结果当作事务承诺。
  2. 共享数据模型比堆叠界面按钮更重要。 图像缩放、像素取色和主色量化复用同一 RGBA 模型;工具导航与命令检索复用注册表;这些复用减少分叉,也要求严格区分注册说明与实际能力。
  3. 把兼容性结论限制在证据覆盖范围内。 一个 PNG 往返一致不代表所有格式兼容,一次 API 回读不代表设备窗口行为完成验收,三张截图也不代表工程配置和发布材料已经准备完毕。

本文展示的是现有 JavaScript 工具链及其鸿蒙壳衔接方式。批量文件操作的数据保护、大图负载控制、格式边界和发布元信息仍有明确的后续工作空间;保留这些边界,才能让技术文章成为可复核的实现说明,而不是超出当前工程状态的功能承诺。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐