Anki 插件如何用 aqt 添加一个显示卡片数量的菜单项？

Anki 插件如何用 aqt 添加一个显示卡片数量的菜单项？

【免费下载链接】ankiAnki is a smart spaced repetition flashcard program项目地址: https://gitcode.com/GitHub_Trending/an/anki

这篇文章解决一个具体的插件开发任务：给 Anki 写一个最小插件，通过aqt在"工具"菜单里添加一个菜单项，点击后弹出对话框显示当前牌组（collection）中的卡片总数。以下内容基于 Anki 仓库中官方插件文档的示例代码，适用于在本地开发环境中编写并测试插件的场景。

准备工作：定位插件目录

Anki 的插件是 Python 模块，Anki 启动时自动加载（见 插件概述）。插件文件放在顶层插件目录中，每个插件占用一个文件夹，Anki 会查找文件夹内的__init__.py文件，例如：

addons21/myaddon/__init__.py

目录说明与操作路径（见 插件目录）：

• 在 Anki 主窗口中打开工具 > Add-ons菜单，点击View Files按钮即可弹出顶层插件目录。如果没有安装过插件，弹出的就是顶层目录；如果选中了某个插件，弹出的是该插件的模块目录，需要上一级。
• 插件目录名为addons21，对应 Anki 2.1。如果你看到名为addons的目录，说明之前用过 Anki 2.0.x。
• 文件夹内没有__init__.py时，Anki 会忽略该文件夹。
• 自建插件的文件夹名建议只使用 a-z 和 0-9 字符，避免 Python 模块系统出问题。

可选分支：如果你习惯用 IDE 开发，可以在 PyCharm 中新建 Python 项目并创建名为myaddon的包，然后在 Python Console 中安装aqt以获得类型补全（见 编辑器配置）。前提是 Anki 2.1.24 及以上版本，且必须使用 64 位 Python、Python 版本要与你获取的 Anki 版本所支持的版本一致：

import subprocess subprocess.check_call(["pip3", "install", "--upgrade", "pip"]) subprocess.check_call(["pip3", "install", "mypy", "aqt[qt6]"])

安装后在文件中输入from anki import hooks再敲hooks.，出现补全列表即为成功。注意：插件不能直接在 PyCharm 里运行，会得到错误；插件必须在 Anki 内运行。

编写插件代码

在插件目录中创建addons21/myaddon/__init__.py，加入 官方基础插件示例中的完整代码：

# import the main window object (mw) from aqt from aqt import mw # import the "show info" tool from utils.py from aqt.utils import showInfo, qconnect # import all of the Qt GUI library from aqt.qt import * # We're going to add a menu item below. First we want to create a function to # be called when the menu item is activated. def testFunction() -> None: # get the number of cards in the current collection, which is stored in # the main window cardCount = mw.col.card_count() # show a message box showInfo("Card count: %d" % cardCount) # create a new menu item, "test" action = QAction("test", mw) # set it to call testFunction when it's clicked qconnect(action.triggered, testFunction) # and add it to the tools menu mw.form.menuTools.addAction(action)

各部分作用：

• from aqt import mw导入 Anki 主窗口对象，mw.col即当前牌组。
• testFunction通过mw.col.card_count()获取卡片数量，再用aqt.utils的showInfo弹出消息框。
• QAction("test", mw)创建名为 "test" 的菜单项，qconnect(action.triggered, testFunction)绑定点击回调，mw.form.menuTools.addAction(action)把它挂到"工具"菜单。

部署并验证

插件写完后的加载方式（见 插件目录）：

1. 在 IDE 中开发时，把myaddon文件夹整体复制进 Anki 的插件目录；或者在 Mac / Linux 上，从开发目录向插件目录创建符号链接。
2. 重启 Anki。

成功条件：重启后，"工具"菜单中应出现一个test菜单项；点击它，会弹出显示卡片数量的对话框。这是该示例文档明确给出的验证方式。

出错时如何定位

• 启动时报错：如果插件代码有错，Anki 启动时会弹出错误消息，并指出问题所在的位置，按提示修好代码再重启即可。

• 调试输出：Anki 是 GUI 程序，print()的内容默认不可见。开发插件时建议显示控制台输出（见 控制台输出）：

  • Windows：通过C:\Users\user\AppData\Local\Programs\Anki（或C:\Program Files\Anki）下的anki-console.bat启动 Anki，会多出一个控制台窗口。
  • macOS：打开 Terminal.app，运行/Applications/Anki.app/Contents/MacOS/anki。
  • Linux：在终端中运行anki。

  另外要注意，打印到 stderr 的内容会被 Anki 的异常处理器捕获并以弹窗形式呈现给用户，开发时不要往 stderr 随意输出。

• 交互式排查：Anki 自带 REPL（Debug Console），在程序内按对应快捷键打开窗口，输入表达式后按 Ctrl+Return（macOS 为 Command+Return）执行，例如输入mw查看主窗口对象，详见 调试。

限制与下一步

• 插件不能脱离 Anki 独立运行（包括在 PyCharm 中直接启动），这是文档明确的限制。
• 本例只涉及aqt与标准库，不依赖任何 PyPI 第三方包，因此不需要打包模块。如果插件用到未内置的标准模块或 PyPI 包，则需要在插件内自行捆绑（见 Python 模块）。
• 获取卡片数量的另一种写法是直接查询数据库，anki 模块文档中给出了示例：showInfo("card count: %d" % mw.col.db.scalar("select count() from cards"))。文档同时提醒：直接写数据库容易出问题，应优先使用col上的方法。

完成这个最小插件后，可以继续阅读 hooks 与 filters、插件配置 等文档，扩展插件的事件响应和配置能力。

【免费下载链接】ankiAnki is a smart spaced repetition flashcard program项目地址: https://gitcode.com/GitHub_Trending/an/anki