PluginAPI 参考
activate(api) 收到的 api 对象是一个干净的门面，封装了书砚的全部内部能力。
只读属性
| 属性 | 类型 | 说明 |
|---|
api.db | Database | 数据库实例，可查章节 / 人物 / 设置等 |
api.project_id | int | 当前打开的项目 ID |
api.project | dict | 当前项目信息（name / description / target_words...） |
api.editor | NovelEditor | None | 当前活跃的编辑器，没打开章节时为 None |
api.active_chapters | dict | {chapter_id: NovelEditor} 所有已打开的章节 |
api.side_tabs | QTabWidget | 侧边栏（人物 / 地点 / 物品 那一排） |
api.chapter_tabs | QTabWidget | 章节标签页（编辑区域顶部） |
api.toolbar | QToolBar | 顶部工具栏 |
api.menubar | QMenuBar | 菜单栏 |
api.statusbar | QStatusBar | 底部状态栏 |
api.window | QWidget | EditorPage 本身（顶层窗口） |
UI 快捷方法
| 方法 | 返回值 | 说明 |
|---|
api.add_side_tab(widget, label) | int (tab index) | 往侧边栏加一个 QWidget 面板 |
api.add_toolbar_btn(label, slot) | QAction | 往顶部工具栏加一个按钮 |
api.add_menu(parent, label, slot, shortcut=None) | QAction | 加菜单项。parent 可以是字符串（"文件" / "编辑" / "工具"）或 QMenu |
api.toast(msg) | None | 状态栏临时提示（紫色 toast，约 2.5 秒自动消失） |
api.open_chapter(chapter_id) | None | 打开指定章节（自动新建 tab） |
api.jump_to_offset(chapter_id, offset) | None | 打开章节并跳到指定字符位置 |
Hook 注册
Hook 是让插件在某个事件发生时被通知。参数都是函数引用。
| 方法 | 回调签名 | 触发时机 |
|---|
api.on_chapter_saved(func) | func(editor) | 任意章节被保存后 |
api.on_chapter_switched(func) | func(current_widget) | 用户切换 tab 时 |
api.on_text_changed(func) | func(editor) | 任意章节文本变化时（慎用，会频繁触发） |
数据库快捷方法
这些方法等价于 api.db.xxx(project_id)，只是少写一个参数。
| 方法 | 返回 |
|---|
api.list_chapters() | [{id, title, word_count, content, ...}] |
api.list_volumes() | [{id, title, ...}] |
api.list_characters() | [{id, name, identity, appearance, ...}] |
api.list_locations() | [{id, name, description, ...}] |
api.list_items() | [{id, name, description, ...}] |
api.search_text(keyword, case_sensitive=False, whole_word=False) | [{chapter_id, chapter_title, offset, context, keyword}] |
api.get_config(key, default='') | str |
api.set_config(key, value) | None |
静态工具方法
不需要实例也能调用，api.show_info(...) 或直接 PluginAPI.show_info(...) 都行。
| 方法 | 说明 |
|---|
api.log(msg) | 往控制台打一条 [插件] 前缀的日志（调试用） |
api.show_info(parent, title, text) | 信息提示框 QMessageBox.information |
api.show_warn(parent, title, text) | 警告提示框 |
api.show_error(parent, title, text) | 错误提示框 |
api.get_text(parent, title, label, default='') | 文本输入对话框，返回 (text, ok) |
api.choose_file(parent, title, filter_str) | 文件打开对话框，返回文件路径字符串 |
api.save_file(parent, title, filter_str, default_name) | 文件保存对话框，返回路径字符串 |
