NVDA 插件开发实践第三篇： 敢想敢做——写出你的第一行代码，控制台不可怕

时隔几个月，插件开发实践的第三篇来了！

这是 NVDA 插件开发实践系列文章的第三篇。你可以通过下面的“传送门”查看之前的章节：

• 第一篇（画饼篇）
• 第二篇：预备篇—确定需求，寻找已有方案

前言

在上一篇，我找到了一个实际需求——在 Visual Studio Code 中读出编辑器中当前光标所在行号。作为一个懒人，我给你的第一建议不是说干就干，，而是确定需求，检索已有方案，最终思考是否适合自己。这个过程中，相信你我收获的不只是源于最初问题的那一个一个答案。

想法可以有，路要一步一步走

在分析了已有方案后，我并不满意，原因如下：

1. 状态栏上的信息很多，对于读出行号这一需求而言，其他的内容显然是冗余的。
2. Ctrl+G 足够快捷但改变了系统焦点位置，实际上，想读出行号我需要两步： Ctrl+G 后按 ESC 返回编辑器。

如果第二个方案可以勉强接受，那么能不能改进一下，解决我提到的槽点——获取行号需要执行两步的问题。当然可以，对于 NVDA 来说，插件的能量是巨大的。这种需求自然不在话下。

那么，从一个最符合直觉的角度来考虑，我们的插件可以是怎样的呢？我的初步构想大概如下：

1. 提供一个快捷键用于在需要的时候读出行号。
2. 最好能跟随 NVDA “文档格式”面板中“读出行号”的选项，如果开启该选项则支持自动读出行号。

先考虑实现第一个功能，至少需要解决两个小问题，一是如何以编程方式获取到当前光标所在的行号，可能是一个 string；二是如何让 NVDA 将获取到的行号信息读出来。

不忘重申： 在“预备篇”我也说过，这个系列不是面向初学者的入门指南，你至少应该熟练掌握甚至精通 NVDA 的使用，其次，你至少应该对 python 有所了解，能够用 python 编写一些处理日常任务的脚本应该是最基本的要求。
从第二篇你也能看到，能够熟练应用浏览器检索/分析资料也会让这一切变得更简单。

写代码从学会 Copy 开始

没错，我就是要先教你怎么学会复制粘贴。这里的复制粘贴不完全等价于 Ctrl+C、Ctrl+V，实际上我们要知道的是去哪里复制；复制哪些内容；粘贴到哪里。

我们常说照葫芦画瓢，是有道理的，写代码当然要先看看别人怎么写的。

既然是开发 NVDA 插件，我更推荐你从 NVDA Core 中去阅读代码，原因有三：一是更具体，更有针对性，有助于你了解 NVDA 的核心 API 及其实现原理，长远来看，这就是在学习从哪里复制的一个过程。二是严谨性，要知道，能合并入 NVDA 核心的代码是经过了社区开发者的多轮 Review 的，代码质量有一定的保障；三是学习这个项目的一些 Best Practice 有助于未来做核心贡献，NVDA 的 code base 目前采用了 Ruff 进行 Lintting Check，即便不是每个学习 NVDA 插件开发的人都会成为未来的 code contributor 仅从培养新手的 coding style 的角度来看，阅读高质量的代码也是益处多多。

所以，建议先安装一个 Git 将 NVDA 的 GitHub 仓库 clone 到本地，每个合格的 Plagiarist 人手一份哦。注意，不是 Download ZIP 哈！具体的步骤我就不写了，相信聪明的你可以利用搜索引擎学到这部分内容。

去哪里复制

思考一下，我们要实现的功能类似于哪个已有功能？去看看那部分代码，会不会从中得到一些启发呢？

按下某个按键，读出一些内容。 NVDA 里类似的功能很多，比如 NVDA+F12 读出时间。让我们去 NVDA 的代码库中找找这部分代码：

1. 打开 Clone 回来的 NVDA 代码库，探索下目录结构，发现这个目录里包含了一些 Build NVDA 所需的文件；
2. 看到了 source 这个目录（猜想，这就是存放源代码的地方喽）；
3. source 目录里的内容，从名字上看大致也就知道其作用了，所以，懂一点英文可能还是有用的，别听他们忽悠你了——英文无用论。

• appModules 应用程序模块，打开看看，存放了一些对特定程序的特殊支持代码；
• brailleDisplayDrivers 显然，这是盲文点显器驱动；
• brailleViewer 这是盲文查看器；
• synthDrivers 这是语音合成器驱动；
• globalCommands.py 从名字上看，这是全局命令的意思。

经过粗略的探索，我们猜想， NVDA+F12 这个功能最有可能在 globalCommands.py 里面，打开看看，文件的顶部是这个文件的版权声名：遵循的开源协议、贡献者等信息，不得不说，贡献者很多，大呼开源大法好。

尝试在 globalCommands.py 中搜索 NVDA+F12 这个字符串，你已经找到了。

复制哪些内容

学过 Python 的你，应该能很轻松看懂 script_dateTime 方法的执行逻辑，此处省略其他的代码，看 script_dateTime 的最后一行，

ui.message(text)

似乎朗读文本的功能就是这一行，能不能验证一下呢？此时，我们应该想到 NVDA 的 Python 控制台。

在 NVDA 菜单的“工具”子菜单下，或者按 NVDA+Ctrl+z 打开 NVDA Python 控制台，键入以下代码：

import ui
ui.message("Hello World!")

当你键入 ui.message("Hello World!") 这一行并按下回车的时候， NVDA 果然朗读了 "Hello World!"，好了，这行代码可以被我们复制。

我们知道了怎么让 NVDA 朗读一段文本，那么行列信息怎么获取呢？举一反三一下。

已知这个信息在状态栏上，那么 NVDA是怎么获取状态栏信息的呢？我们知道有个朗读状态栏的快捷键，对于笔记本布局来说是 NVDA+Shift+End 一样，我们去 globalCommands.py 里再搜一下。

是不是很容易就找到了 script_reportStatusLine 这个方法，稍微读一下，实际上第一步是有效性检查，在执行后续逻辑之前，Check 一下有没有状态栏文本。

那么我们再读一下 _getStatusBarText 这个私有方法，很好，我们发现它是调用了 api.getStatusBar 进而通过 api.getStatusBarText 获得了状态栏的文本，似乎有了眉目，我们一样用 NVDA Python 控制台来看看这两个方法具体是怎么用的。

在控制台中键入以下代码：

import api
help(api.getStatusBar)

输出了以下内容：

>>> help(api.getStatusBar)
Help on function getStatusBar in module api:

getStatusBar() -> Optional[NVDAObjects.NVDAObject]
    Obtain the status bar for the current foreground object.
    @return: The status bar object or C{None} if no status bar was found.

getStatusBar 函数的功能是获取当前前台对象的状态栏对象。
返回值：状态栏对象或如果没有找到状态栏则返回 None 。状态栏对象的类型是 Optional[NVDAObjects.NVDAObject]，也就是说，它可以是 NVDAObjects.NVDAObject 类型的对象，或者是 None 。

NVDA Python 控制台

想必你已经发现了，NVDA Python 控制台（下称“控制台”）是我们开发插件不可缺少的工具。这并不属于 Python 基础，它有哪些奇技淫巧我可能有必要在进行下一步之前跟你啰嗦一下。

实际上这个工具大多数用法跟普通的 Python 控制台并无二致，既然叫 NVDA Python 控制台自然有一些 NVDA 特定的用法。比如可以导入 NVDA 自有的 module，可以动态执行代码，对 NVDA Object 进行检查。

控制台支持的基本操作

1. F6: 在输入区域和输出区域之间切换。
2. 在输出区域：

• Alt+上箭头：上一个输出块。
• Alt+下箭头：下一个输出块。

3. 在输入区域：

• Tab：缩进和补全代码。
• 上/下箭头：切换输入历史。
• 回车执行代码/代码块。

控制台实践演练

NVDA Python 控制台对于新手也是非常友好的，它支持 NVDA 的标准语法，你不仅可以用来开发调试 NVDA 代码，你也可以把它当做一个 playground 用来熟悉 Python 语法，简直就是随身携带的 Python 执行环境。

下面我会给你几个好玩的任务让你彻底熟悉该控制台的用法。

蜂鸣音

在控制台执行以下代码：

import tones
tones.beep(640,500)

获取帮助

上面我们用简单的两行代码就可以播放出0.5秒的 beep 声音。

想知道 beep 这个函数的帮助信息吗？这当然难不倒聪明的你：

help(tones.beep)

跟上面一样， help 可以将 beep 的 docstring 打印出来。

如果想知道 tones 的更多信息呢？ help(tones) 自然是可以的。还记得 python 的 dir 函数吗，不妨试一下 dir(tones)。

想一下，假如你把 beep 写成了 beap 必然会出错，可是死活想不起 beep 是怎么拼的，怎么办呢？使用 dir 当然可以，但一般没人会这么做！

然而，别忘了控制台的自动补全功能，输入 tones.b 案两次 Tab 你会发现，控制台在一个菜单里列出了 tones 内，以 b 开头的匹配项，回车即可完成输入。

如果你把范围进一步缩小，先输入 tones.be（多输入个 e） 再案两次 Tab，你会发现 tones.beep 已经被自动补全了。

在控制台里输入代码块

题目：打印10以内（包含10）的所有偶数

要求：

1. 10以内（包含10）指从1到10的所有整数。
2. 偶数是指能够被2整除的整数。
3. 输出每个偶数，每个数占一行。

在控制台执行以下代码：

for num in range(1, 11):
    if num % 2 == 0:
        print(num)

提示： 输入完 for num in range(1, 11):案回车后案 Tab 即可插入制表符增加一层缩进，输入完代码块的最后一行案两次回车即可执行代码块。

控制台的隐式导入

实际上上面用到的 api这个 Module 在控制台里已经被隐式导入了，这是为了方便开发者调试，我写出来只是为了提醒你，在后续写代码的时候千万不要忘记。

还有一些常用的 Module 或 NVDAObject 也已经在控制台里被隐士导入/定义了，如下：

• api： 在NVDA 里非常常用的 Module。
• focus:当前系统焦点
• fg:前台对象，（foreground object）注意，这是打开控制台之前的前台对象。
• nav: 当前导航对象（navigator object）。

举一反三

我已经把强大的控制台工具介绍给你了，你可以大胆探索一下，下面几个函数/技巧可能会帮到你。

• type()
• help
• dir
• module.__file__

举例：

• type(fg)
• fg.name
• focus.name
• focus.role
• focus == nav
• nav.devInfo

上面的内容似乎有一点神秘，在开始下一篇之前，我希望你已经进行了一些探索，相信我，动手探索会有收获的。

写在最后

工具、搜索、阅读，探索，英文和英文无用论，结语我只能想到这么几个关键词。

好啦，这一篇也就写到这里吧！

最后，我希望听到你的赞美和批评，请通过任意一种你喜欢的方式给我一些反馈。