手把手教你从零开发一个 NVDA 读屏插件

很多朋友都想自己开发 NVDA插件，扩充想要的功能，但又担心开发 NVDA 插件非常难，需要精通底层原理、熟悉复杂的工具链。实际上不必担心，它并不难。NVDA 插件的开发语言是Python，插件本身的结构也很简单——一个清单文件、若干 Python 源代码文件，按照约定的目录结构组织好，压缩成特定格式的文件就可以分发了。整个过程不需要编译，不需要配置复杂的开发环境，有一台安装了 NVDA 的 Windows 电脑和一个文本编辑器就够了。

本文会通过一个具体的示例插件，完整演示从编写代码、本地测试到打包安装的完整步骤。读完本文，你应当能学会完成一个完整的插件的开发及打包。

本文主要面向没有插件开发经验的朋友。如果你已经有一定的NVDA插件开发经验，本文大部分内容可能对你来说比较基础，可以跳过。

一、NVDA 插件简介

NVDA（NonVisual Desktop Access）是一款免费、开源的 Windows 读屏软件，由 NV Access 及全球贡献者共同开发维护。NVDA 使用 Python 语言编写，这一点对于插件开发来说非常重要，也就是说，插件同样使用 Python 编写，并且直接运行在 NVDA 自带的 Python 环境中，不需要单独安装 Python。

附加组件（Add-on）是为 NVDA 扩展功能的程序包。它可以做很多事情，比如：

·增强对某些应用程序的支持。例如让 NVDA 更好地朗读某个特定软件中的内容。

·扩充对第三方盲文点显器或语音合成器的驱动支持。

·添加、修改 NVDA 自身的功能。比如增加全局快捷键、修改键盘行为、调整语音输出等。

在 NVDA 的插件商店中，已经有大量由社区开发者贡献的插件，全部可以免费下载。你也可以开发自己的插件，解决自己遇到的具体问题，然后分享给其他人。

事实上，从文件结构上看，一个 NVDA 插件本质上就是一个 ZIP 压缩包，只是文件扩展名改成了.nvda-addon。压缩包内部包含一个清单文件（manifest.ini）和若干 Python 代码文件，按照特定的目录结构组织。NVDA 在安装插件时，会读取清单文件获取插件的名称、版本、兼容性等信息，然后将插件代码加载到运行环境中。

二、插件的两种类型

NVDA 插件按照作用范围，分为两种类型：全局插件（Global Plugin）和应用模块（App Module）。理解这两者的区别，是选择插件类型的第一步。

全局插件（Global Plugin）

全局插件在 NVDA 运行期间始终处于活动状态，不论当前焦点位于哪个应用程序。它适合实现全局性的功能，例如：

·添加全局快捷键

·修改键盘行为

·监控系统状态

·调整语音输出

全局插件的代码文件放在插件包的globalPlugins目录下。

应用模块（App Module）

应用模块只在特定应用程序处于活动状态时才生效。它适合针对某个具体应用做适配增强，例如：

·修复某个软件的无障碍支持问题

·为某个软件添加专属命令

·调整某个软件中特定控件的朗读方式

应用模块的代码文件放在插件包的appModules目录下，文件名需要与目标应用程序的可执行文件名一致（不含.exe后缀）。例如，为记事本（notepad.exe）编写的应用模块，文件名应为notepad.py。

怎样选择

判断方式很简单：如果你要做的功能需要在所有应用中都生效，就用全局插件；如果只针对某一个特定程序，就用应用程序模块。

三、开发前的准备工作

在正式开始编写代码前，需要完成以下几项准备。

3.1 掌握 Python 基础

需要了解 Python 的基本语法，包括类（class）、方法（method）、导入模块（import）、条件判断（if/else）等概念。如果你之前没有接触过Python，建议先花一到两个小时阅读 Python 官方教程的前几章，了解基本语法即可。本文不会讲解 Python 语法本身。

3.2 准备文本编辑器

使用任意文本编辑器编写Python 代码都可以。Windows 自带的记事本、VS Code、Notepad++ 都没问题。保存文件时，确保文件编码为UTF-8。如果你使用 Windows 自带的记事本，在”另存为”对话框底部的”编码”下拉框中选择”UTF-8”。

3.3 开启 NVDA 的开发者实验目录

NVDA 提供了一个名为”开发者实验目录”（Scratchpad）的功能，能让开发者在不打包插件的情况下直接测试代码。开启方法如下：

1.在NVDA启动后，按NVDA+N打开 NVDA 菜单。

2.弹出菜单后，按P，进入”选项”子菜单。

3.按S，打开”设置”对话框。

4.在设置对话框类别列表中，使用下光标键找到”高级”类别，然后按Tab找到“我清楚更改这些设置可能导致NVDA 无法正常运行。”复选框，空格选中。

5.此时会出现一个确认提示，告知更改高级设置可能导致 NVDA 无法正常运行。勾选”我清楚更改这些设置可能导致 NVDA 无法正常运行”复选框，并点击确认。

6.按 Tab 键移动到”允许从开发者实验目录加载代码”复选框，按空格键勾选。

7.继续按 Tab 键找到”确定”按钮，按回车键保存并关闭对话框。

开启之后，你可以在 NVDA 菜单 → 选项→设置 → 高级中找到“打开开发者实验目录”，点击后会打开该目录。

3.4 重新加载插件的快捷键

在开发过程中，修改代码后不需要重启NVDA。按下默认快捷键NVDA+Ctrl+F3即可重新加载全局插件和应用模块。

四、示例插件

本文就以一个更改NVDA键盘处理行为的插件为例，手把手带你玩转NVDA插件开发。

在开始之前，先讲清楚这个示例插件要做什么。

NVDA 可以让用户将 Caps Lock 键设置为 NVDA 键。一旦这样设置，Caps Lock 键原本的大小写切换功能就不再直接可用了。为了保留按键的原有功能，NVDA 统一设计了一个规则：快速双击该键，即可触发按键的原功能。也就是说，如果你把 Caps Lock 设为 NVDA 键，想要切换大小写，需要快速按两下 Caps Lock。

这个设计有它的合理之处——它用一套统一的规则处理了所有被设为 NVDA 键的按键。但有些朋友并不习惯这种方式，更喜欢类似于争渡读屏的处理模式：单击 Caps Lock 后，如果抬起前没有组合其他按键，就切换大小写；如果组合了其他按键，则作为 NVDA 修饰键使用，抬起时不切换大小写。

本文就开发个小插件来实现这个功能。通过这个例子，可以了解NVDA全局插件的完整开发流程，包括如何注册扩展点、如何拦截键盘事件、如何读取配置、如何模拟按键、如何操控语音模块，以及最终的打包和安装。

五、插件的文件结构

一个完整的 NVDA 插件包，内部结构如下：

插件包根目录/├── manifest.ini← 插件清单文件（必须）├── globalPlugins/← 全局插件代码目录│└── capsLockModifier.py← 插件代码文件└── doc/← 插件文档目录（可选）└── en/└── readme.html← 英文说明文档

对于开发阶段使用实验目录测试，你只需要在实验目录的globalPlugins子目录下创建capsLockModifier.py文件即可，不需要manifest.ini。manifest.ini是打包分发时才需要的。

六、清单文件 manifest.ini

manifest.ini是插件的元数据文件，NVDA 通过它识别插件的基本信息。以下是本插件的清单文件内容：

name ="capsLockModifier"summary = "CapsLock Modifier Enhancer"version = "1.0.0"description = "Replaces NVDA's default double-press toggle for CapsLock with a single-press toggle when CapsLock is set as the NVDA key."author = "Arno <arno@prc.cx>"url ="https://github.com/cingzeoi"docFileName ="readme.html"minimumNVDAVersion ="2025.1.0"lastTestedNVDAVersion ="2027.4.4"

各字段的含义如下：

·name：插件的内部标识符，只能包含字母、数字、下划线和连字符。这个名称会作为插件在用户配置目录中的文件夹名。

·summary：插件的显示名称，会出现在插件商店和插件管理界面中。

·version：插件版本号，格式为主版本.次版本.修订号。

·description：插件的功能描述，一两句话即可。

·author：作者姓名和邮箱，格式为姓名<邮箱>。

·url：插件的主页地址，可以填GitHub 仓库地址。

·docFileName：插件说明文档的文件名。NVDA会在doc目录下按语言查找这个文件。

·minimumNVDAVersion：插件兼容的最低 NVDA 版本。格式为年份.主版本.次版本，例如2024.1.0。

·lastTestedNVDAVersion：插件经过测试的最高 NVDA版本。

在开发测试阶段，你暂时不需要这个文件。等到打包时再创建即可。

七、插件代码

以下是完整的插件代码。先看完整的，之后逐步解释。

# -*- coding: utf-8 -*-

# 导入 NVDA 插件所需的基础模块importglobalPluginHandler# 全局插件基类import inputCore# 输入核心，用于拦截按键事件import keyboardHandler# 键盘事件处理，管理修饰键状态import winUser# Windows API 封装，含虚拟键码和键盘操作import config# NVDA 配置import core# 核心功能，如定时器import ui# 用户界面，用于显示消息import speech# 语音输出控制from config.configFlags import NVDAKey# NVDA 修饰键标志（如Caps Lock）from keyLabels importlocalizedKeyLabels# 本地化键名classGlobalPlugin(globalPluginHandler.GlobalPlugin):"""
全局插件：自定义Caps Lock 键行为。
当 Caps Lock 被设置为 NVDA 修饰键时，插件拦截其按键事件。
- 若按下 Caps Lock 后与其他键组合（同时按下其他键），则作为修饰键使用，不改变 Caps Lock 实际状态。
- 若单独按下并释放Caps Lock（无组合），则模拟一次 Caps Lock 切换，并播报当前状态（开/关）。
"""

def__init__(self):"""
初始化插件实例。
- 调用父类初始化。
-初始化内部状态变量：
_isCapsDown: 标记 Caps Lock 键是否正处于按下状态。
_hasCombined: 标记在按下Caps Lock 期间是否与其他键组合。
_isSendingCaps : 标记是否模拟发送Caps Lock 按键，防止无限递归。
- 注册原始按键处理回调函数到 inputCore，以便在按键被 NVDA 处理前进行拦截。
"""
super().__init__()self._isCapsDown =False# Caps Lock 是否按下self._hasCombined =False# 是否在按住期间组合了其他键self._isSendingCaps =False# 是否正在模拟Caps Lock 键（防止重入）# 注册_onRawKey 到 inputCore 的 decide_handleRawKey 钩子，该钩子在每个原始按键事件时调用inputCore.decide_handleRawKey.register(self._onRawKey)def terminate(self):"""
插件终止时的清理工作。
- 从inputCore 注销按键处理回调。
- 如果 Caps Lock 仍然处于按下状态（例如插件被禁用时键未释放），则从当前修饰键集合中移除，
避免 NVDA 认为修饰键一直按住。
- 调用父类terminate。
"""
# 注销回调，防止后续事件调用inputCore.decide_handleRawKey.unregister(self._onRawKey)# 如果 Caps Lock 还在按下状态，手动从 currentModifiers 中清除ifself._isCapsDown:# 从修饰键集合中移除(VK_CAPITAL, False) 和 (VK_CAPITAL, True) 两种扩展状态keyboardHandler.currentModifiers.discard((winUser.VK_CAPITAL, False))keyboardHandler.currentModifiers.discard((winUser.VK_CAPITAL, True))super().terminate()def _onRawKey(self, vkCode, scanCode, extended, pressed):"""
原始按键事件处理回调（由 inputCore 调用）。
参数：
vkCode: 虚拟键码
scanCode : 扫描码
extended : 是否为扩展键（如右Alt 等）
pressed: True 表示按下，False表示释放
返回值：
True: 允许该按键继续由NVDA 正常处理（传递给后续步骤）
False : 阻止该按键进一步处理（已由本插件消费）
逻辑：
1. 若 NVDA 当前正在处理注入的按键（如模拟按键），则直接放行，避免干扰。
2. 若配置中未将Caps Lock 设为 NVDA 修饰键，则放行。
3. 若当前正有按键需要“穿透”（passKeyThroughCount >= 0），则放行。
4. 如果当前按键是Caps Lock：
a. 按下时：标记_isCapsDown = True，清除 _hasCombined，将该键加入修饰键集合，
返回 False 阻止系统默认行为（让 NVDA 接管）。
b. 释放时：清除标记，从修饰键集合中移除。如果期间没有组合其他键，
则模拟一次Caps Lock 的按下和释放（切换状态），并延迟播报状态。
返回 False。
5. 如果当前按键不是Caps Lock，且 Caps Lock 正处于按下状态并且本次是按下事件，
则标记_hasCombined = True（表示有组合），然后返回 True 让 NVDA 正常处理组合键。
"""
# 如果 NVDA 设置了忽略注入按键的标记，则直接放行（例如模拟按键时避免再次触发）ifkeyboardHandler.ignoreInjected:returnTrue# 检查配置：是否将Caps Lock 作为 NVDA 修饰键之一ifnot (config.conf["keyboard"]["NVDAModifierKeys"] & NVDAKey.CAPS_LOCK):returnTrue# 如果passKeyThroughCount >= 0，表示某些按键需要直接穿透（不拦截），放行ifkeyboardHandler.passKeyThroughCount >=0:returnTrue# 当前按键是否为Caps Lockif vkCode == winUser.VK_CAPITAL:# 构造该键的标识元组(虚拟键码, 扩展标志)keyCode =(winUser.VK_CAPITAL, extended)if pressed:# Caps Lock 按下self._isCapsDown =True# 记录按下状态self._hasCombined =False# 重置组合标志# 将该键加入到当前修饰键集合，以便 NVDA 识别为活动修饰键keyboardHandler.currentModifiers.add(keyCode)# 记录最后一个 NVDA 修饰键，用于后续组合键识别keyboardHandler.lastNVDAModifier = keyCode# 返回 False 阻止系统进一步处理该按下事件（防止系统切换Caps Lock 状态）returnFalseelse:# Caps Lock 释放self._isCapsDown =False# 清除按下状态keyboardHandler.currentModifiers.discard(keyCode)# 从修饰键集合移除# 如果在按住 Caps Lock 期间没有组合任何其他键，则执行单独的切换操作ifnotself._hasCombined:# 设置标志，表示正在模拟发送 Caps Lock，防止重入self._isSendingCaps =Truetry:# 使用ignoreInjection 上下文，避免模拟的按键被 NVDA 再次拦截withkeyboardHandler.ignoreInjection():# 模拟一次 Caps Lock 键按下和释放（系统会切换状态）winUser.keybd_event(winUser.VK_CAPITAL, 0, 0, 0)# 按下winUser.keybd_event(winUser.VK_CAPITAL, 0, 2, 0)# 释放（KEYEVENTF_KEYUP）finally:# 确保清除模拟标志，即使发生异常self._isSendingCaps =False# 延迟 30ms 后播报 Caps Lock 当前状态（等待系统状态更新）core.callLater(30, self._reportCapsLockState)# 返回 False 阻止系统默认处理该释放事件（避免系统在释放时切换）returnFalseelse:# 当前按键不是Caps Lock# 如果 Caps Lock 正处于按下状态，并且本次是按下事件，说明用户按下了其他键进行组合ifself._isCapsDown and pressed:self._hasCombined =True# 放行该按键，让NVDA 继续处理（例如执行组合键命令）returnTruedef_reportCapsLockState(self):"""
播报 Caps Lock 的当前状态（开/关）。
由core.callLater 延迟调用，确保系统 Caps Lock 状态已更新。
- 取消当前正在进行的语音，避免干扰。
- 通过winUser.getKeyState 获取实际切换状态（最低位为 1 表示开启）。
- 使用本地化键名和状态文本，通过 ui.message 显示在屏幕上并语音读出。
"""
# 取消任何正在播放的语音，使播报清晰speech.cancelSpeech()# 获取 Caps Lock 切换状态：最低有效位为 1 表示打开，0 表示关闭toggleState = winUser.getKeyState(winUser.VK_CAPITAL) &1# 获取本地化的键名（如 "caps lock" 或对应翻译）key =localizedKeyLabels.get("capslock", "caps lock")# 构建并显示消息，状态使用下划线 _ 函数进行翻译（NVDA 支持多语言）ui.message("{key}{state}".format(key=key,state=_("on") if toggleState else _("off"),),)

八、代码解释

8.1 导入模块

import globalPluginHandlerimport inputCoreimport keyboardHandlerimport winUserimport configimport coreimport uiimport speechfrom config.configFlags import NVDAKeyfrom keyLabels import localizedKeyLabels

这些模块都是 NVDA 内部提供的，不需要额外安装。各模块的用途如下：

8.2 插件类的定义与初始化

class GlobalPlugin(globalPluginHandler.GlobalPlugin):def__init__(self):super().__init__()self._isCapsDown =Falseself._hasCombined =Falseself._isSendingCaps =FalseinputCore.decide_handleRawKey.register(self._onRawKey)

全局插件必须定义一个名为GlobalPlugin的类，继承自globalPluginHandler.GlobalPlugin。NVDA 加载插件时会自动实例化这个类。类名必须叫GlobalPlugin，这是 NVDA 的约定。

__init__方法在插件加载时执行。这里做了两件事：

第一，初始化三个内部状态变量：

·_isCapsDown：记录 Caps Lock 当前是否处于按下状态。

·_hasCombined：记录 Caps Lock 按下期间是否组合了其他按键。

·_isSendingCaps：记录当前是否正在发送模拟按键，用于防止循环。

第二，将_onRawKey方法注册到inputCore.decide_handleRawKey扩展点。注册之后，每一个键盘按键事件（按下和抬起）到达 NVDA 时，都会先调用_onRawKey方法。

NVDA 在内部的关键流程中预留了一些”挂载点”，允许插件把自己的函数注册上去。当流程执行到这些挂载点时，NVDA 会依次调用所有已注册的函数。decide_handleRawKey就是其中一个扩展点，它位于键盘事件处理的最前端。插件可以在这里决定一个按键是被 NVDA 继续处理，还是被拦截下来。

8.3 插件终止时的清理

def terminate(self):inputCore.decide_handleRawKey.unregister(self._onRawKey)ifself._isCapsDown:keyboardHandler.currentModifiers.discard((winUser.VK_CAPITAL, False))keyboardHandler.currentModifiers.discard((winUser.VK_CAPITAL, True))super().terminate()

terminate方法在插件终止时（例如 NVDA 退出，插件被重载等）都会执行。这里做了两件事：

第一，从扩展点中注销_onRawKey方法。

第二，如果插件禁用时 Caps Lock 恰好处于按下状态，需要从currentModifiers集合中移除 Caps Lock的记录，避免残留状态影响后续操作。这里同时移除了extended为False和True两种情况，确保清理干净。

8.4 _onRawKey 方法

这个方法是插件的核心。每当有键盘事件发生时，NVDA 会调用该方法，传入四个参数：

·vkCode：虚拟键码，标识是哪个按键。

·scanCode：扫描码，硬件层面的按键编码。

·extended：是否为扩展键。

·pressed：True表示按下，False表示抬起。

方法返回True表示放行，NVDA 继续正常处理该按键。返回False表示拦截，NVDA 不再处理该按键。

下面逐步说明。

第一步：放行模拟按键

if keyboardHandler.ignoreInjected:returnTrue

keyboardHandler.ignoreInjected是 NVDA 内部的一个标志位。当我们在ignoreInjection()上下文中发送模拟按键时，这个标志位为True。此时直接放行，避免插件处理自己发出的按键，造成死循环。

第二步：检查 Caps Lock 是否被设为 NVDA 键

ifnot (config.conf["keyboard"]["NVDAModifierKeys"] & NVDAKey.CAPS_LOCK):returnTrue

NVDA 使用一个整数的位掩码来记录哪些按键被设为 NVDA 键。NVDAKey.CAPS_LOCK的值为1（二进制001）。通过按位与运算，可以判断Caps Lock 是否在 NVDA 键列表中。如果用户没有将 Caps Lock 设为 NVDA 键，插件不做任何干预，直接放行。

第三步：尊重”跳过下一个按键”功能

if keyboardHandler.passKeyThroughCount >=0:returnTrue

NVDA 有一个”跳过下一个按键”的功能（快捷键NVDA+F2），按下后下一个按键会直接传递给当前应用程序，NVDA 不做处理。如果该功能处于激活状态，插件同样不做干预。

第四步：处理 Caps Lock 按下

if vkCode == winUser.VK_CAPITAL:keyCode = (winUser.VK_CAPITAL, extended)if pressed:self._isCapsDown =Trueself._hasCombined =FalsekeyboardHandler.currentModifiers.add(keyCode)keyboardHandler.lastNVDAModifier = keyCodereturnFalse

当 Caps Lock 被按下时：

1.将_isCapsDown设为True，记录 Caps Lock 已按下。

2.将_hasCombined重置为False，开始新一轮的组合检测。

3.将 Caps Lock 加入keyboardHandler.currentModifiers集合。这个集合记录了当前所有处于按下状态的修饰键。后续按下其他键时，NVDA 会检查这个集合来判断组合键。

4.设置keyboardHandler.lastNVDAModifier，告诉 NVDA 最后按下的 NVDA 修饰键是 Caps Lock。

5.返回False，拦截该按键。NVDA 不会继续处理这个按键，也不会触发默认的双击检测逻辑。

第五步：处理 Caps Lock 抬起

else:self._isCapsDown =FalsekeyboardHandler.currentModifiers.discard(keyCode)ifnotself._hasCombined:self._isSendingCaps =Truetry:with keyboardHandler.ignoreInjection():winUser.keybd_event(winUser.VK_CAPITAL,0, 0, 0)winUser.keybd_event(winUser.VK_CAPITAL, 0, 2, 0)finally:self._isSendingCaps =Falsecore.callLater(30, self._reportCapsLockState)returnFalse

当 Caps Lock 被抬起时：

1.将_isCapsDown设为False。

2.从currentModifiers集合中移除 Caps Lock。

3.检查_hasCombined：如果为False，说明 Caps Lock 按下期间没有组合其他按键，属于”单按”。此时执行大小写切换。

切换大小写的方式是：调用winUser.keybd_event向操作系统发送一个 Caps Lock 的按下和抬起事件。操作系统收到后会切换大小写状态。

这里有一个关键点：发送模拟按键时，必须包裹在keyboardHandler.ignoreInjection()上下文中。如果不这样做，模拟发出的按键会再次触发_onRawKey方法，导致插件处理自己发出的按键，形成死循环。ignoreInjection()的作用是告诉 NVDA 忽略这两个模拟按键。

切换之后，使用core.callLater(30, self._reportCapsLockState)延迟 30 毫秒后调用状态播报方法。延迟的原因是：keybd_event发送的按键事件需要一小段时间才能被操作系统处理完毕，立即读取状态可能得到旧值。

最后返回False，拦截抬起事件。

第六步：处理其他按键

else:ifself._isCapsDown and pressed:self._hasCombined =TruereturnTrue

如果按下的不是 Caps Lock，且 Caps Lock 当前处于按下状态，则将_hasCombined设为True，标记已发生组合。然后返回True放行，让 NVDA 正常处理该按键（例如执行对应的 NVDA 命令）。

8.5 状态播报方法

def _reportCapsLockState(self):speech.cancelSpeech()toggleState = winUser.getKeyState(winUser.VK_CAPITAL) &1key = localizedKeyLabels.get("capslock", "caps lock")ui.message("{key}{state}".format(key=key,state=_("on") if toggleState else _("off"),),)

1.speech.cancelSpeech()：取消当前正在朗读的语音。这样做的目的是让状态播报能够立即播出，而不必等待前面的语音朗读完毕。

2.winUser.getKeyState(winUser.VK_CAPITAL) & 1：读取 Caps Lock 的当前开关状态。返回值的最低位为 1 表示开启（大写），为 0 表示关闭（小写）。

3.localizedKeyLabels.get("capslock", "caps lock")：获取”Caps Lock”在当前语言下的翻译名称。中文环境下会返回”大写锁定”。

4.ui.message(...)：播报一条消息。_("on")和_("off")是 NVDA 的国际化函数，会根据当前语言返回对应的翻译。

九、本地测试

代码编写完成后，按以下步骤测试。

9.1 将文件放入实验目录

1.打开 NVDA 的实验目录，通常位于C:\Users\yourusername\AppData\Roaming\nvda\scratchpad。

2.在实验目录中找到globalPlugins子目录。如果该目录不存在，手动创建一个。

3.将capsLockModifier.py文件复制到globalPlugins目录中，随后重启 NVDA。