LunaTranslator 工具按钮完全指南39 个按钮的功能、配置与源码实现解析【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator本篇指南以 LunaTranslator 的官方文档 docs/zh/alltoolbuttons.md 为主体结合仓库中 按钮栏实现、按钮注册逻辑、工具按钮设置界面 与 默认配置 的源码证据系统讲解翻译窗口工具栏上全部 39 个工具按钮的实际功能、使用场景、默认状态与底层实现原理。读者阅读本文后将能熟练完成按钮的显示/隐藏、对齐、排序、换色、换图标等全部自定义操作并透彻理解每个按钮在 HOOK / OCR / 剪贴板等不同文本输入源下的行为差异从而把工具栏打造成完全贴合自己翻译流程的操控面板。一、工具按钮体系总览LunaTranslator 的翻译窗口顶部/侧边存在一条工具栏其中所有按钮统称为工具按钮。它们是翻译器日常操作的快捷入口手动翻译、暂停自动模式、读取剪贴板、选取 OCR 范围、锁定工具栏、窗口缩放与截图、朗读、查词等操作都可以一键触发。这些按钮并非固定不变的摆设而是一套高度可定制的 UI 组件显示/隐藏所有按钮都可以在显示设置-工具按钮中通过使用开关决定是否显示自由调整位置所有按钮均可随意调整顺序位置并可设置对齐组居左居中居右相对位置的调整都会被限定在对齐组内部颜色自定义点击颜色可以自定义按钮图标的颜色图标自定义点击图标可以自定义按钮使用的图标双状态指示部分按钮有两个图标用来指示两种不同的状态如锁定/解锁、静音/有声部分按钮仅有一个图标不过会用不同的颜色来表示不同的状态。从源码结构看这套体系由三个模块协作完成gui/buttonbar.py负责按钮控件的渲染与事件分发gui/translatorUI.py中的create_buttons()负责定义每个按钮的功能gui/setting/display_buttons.py提供可视化配置界面。二、按钮的基础配置显示、对齐、排序、图标与颜色2.1 配置入口打开显示设置-工具按钮面板对应源码文件 display_buttons.py可以看到一个以sortlist globalconfig[toolbutton][rank2]为顺序渲染的按钮列表display_buttons.py 第 262 行每个按钮占一行包含以下配置列配置列说明使用开关按钮对应buttons[名字][use]控制按钮是否显示特殊功能仅fullscreen窗口缩放与grabwindow窗口截图两个按钮有用于配置左键/右键行为上移/下移调整按钮在工具栏中的排列顺序点击即移动一格长按直接置顶/置底对齐下拉框居左居右居中三选一对应buttons[名字][align]的 0 / 1 / 2图标打开图标选择对话框自定义该按钮的主图标图标2仅双状态按钮显示自定义第二种状态的图标说明按钮的功能简述HOOK/OCR 模式限定按钮还会标注仅XX模式下可用该列表同时将每个按钮关联到官方文档锚点alltoolbuttons.html#anchor-名字见 display_buttons.py 第 352 行点击即可跳转到对应按钮的详细说明。2.2 显示控制与模式限定在源码translatorUI.py中buttondisplaychecker(name)translatorUI.py 第 626 行决定了一个按钮最终是否显示判定逻辑为若按钮带有belong字段限定可用模式则只有当该模式处于启用状态时才显示。如selectgame、selecttext的belong为[texthook]selectocrrange、hideocrrange的belong为[ocr]若按钮配置中use为false则不显示。因此HOOK 模式专属按钮选择游戏/选择文本只在 HOOK 模式启用时出现OCR 模式专属按钮选取范围/显示范围框只在 OCR 模式启用时出现这与你当前使用的文本输入源自动联动。2.3 按钮大小与颜色在工具按钮设置面板顶部可以配置三个与视觉相关的参数display_buttons.py 第 220 行参数配置键默认值范围说明大小buttonsize255 ~ 100按钮图标的基础尺寸颜色buttoncolor#2e2eff-按钮处于关闭/默认状态时的图标颜色颜色2buttoncolor_1#ff03f2-按钮处于激活状态时的图标颜色背景色button_color_normal#FFFFFF-鼠标悬停时按钮的底色这些颜色由refreshtoolicon()buttonbar.py 第 235 行统一刷新如果按钮注册了colorstate回调则回调返回真时用buttoncolor_1激活色返回假时用buttoncolor默认色未注册colorstate的按钮固定使用默认色。双状态切换按钮如自动模式、鼠标穿透、窗口置顶正是靠这种颜色变化来指示开关状态。2.4 图标自定义机制点击某按钮行的图标列会弹出选择图标对话框dialog_selecticon见 display_buttons.py 第 26 行。该对话框从 fontawesome4.7-webfont-charmap.json 加载 FontAwesome 4.7 的全部图标以网格形式供你点击选择也支持手动输入取值有三种形式界面提示为图标 | 字符 | 图片路径 | lunafa.图标名使用 FontAwesome 图标如fa.gear、fa.book图片路径使用本地图片作为按钮图标luna使用当前游戏进程的可执行文件图标。在渲染端IconLabelX.setIconStr()buttonbar.py 第 130 行会判断非fa.开头的字符串走本地图片/可执行图标加载路径fa.开头的走qtawesome.icon(icon, colorcolor)矢量图标渲染路径图标颜色即来自 2.3 节的状态色。2.5 双图标按钮默认配置中注册了icon2的按钮即双图标按钮有automodebutton自动模式fa.forward/fa.playlocktoolsbutton锁定工具栏fa.lock/fa.unlockfullscreen窗口缩放fa.compress/fa.expandmuteprocess游戏静音等。其切换逻辑在refreshtoolicon()中实现若按钮注册了iconstate回调回调返回真时显示icon2返回假时显示icon。例如锁定工具栏按钮的iconstatelambda: globalconfig.get(locktools, False)即锁定状态下显示解锁图标。三、文本输入与翻译核心按钮3.1 手动执行retrans对应锚点anchor-retrans默认启用。实际意义是从当前的文本输入源读取一次输入并执行翻译。例如当前是 OCR 模式时会再执行一次 OCR 识别当前是 HOOK 模式时会重新抓取一次游戏文本。源码中该按钮绑定self.startTranslatertranslatorUI.py 第 378 行它强制绕过自动模式的暂停状态主动发起一次完整的取文本 - 翻译流程。当你关闭了自动模式、或自动模式暂停后用这个按钮可以按需手动触发翻译。3.2 自动模式automodebutton对应锚点anchor-automodebutton默认隐藏。实际意义是暂停/继续自动从当前的文本输入源读取文本。当前是 HOOK 模式暂停/继续读取游戏文本当前是 OCR 模式暂停/继续自动识别图像当前是剪贴板模式暂停/继续自动读取剪贴板。源码中该按钮绑定changeTranslateMode其状态回调为globalconfig.get(autorun, True)translatorUI.py 第 382 行即按钮的图标与颜色都反映autorun配置。这是除显示/隐藏翻译之外另一个高频总开关自动模式开启时翻译器持续跟随文本变化关闭时则完全由手动按钮驱动。3.3 读取剪贴板copy_once对应锚点anchor-copy_once默认启用。与复制到剪贴板方向相反不管当前的默认文本输入源是什么都从剪贴板读取一次文本并传给之后的翻译 / TTS 等流程。左键点击读取剪贴板文本并送入翻译流程实现剪贴板模式下的手动取词右键点击将读取到的文本追加到当前文本之后再进入后续流程。源码实现为textgetmethod(gobject.base.currenttext (getlangsrc().space if ...) ClipBoard.text, False)translatorUI.py 第 563 行追加时会自动在两句之间插入符合源语言习惯的分隔空格。3.4 进行一次 OCR / 再次进行 OCR这两个按钮用于临时性 OCR 需求进行一次 OCRocr_once与读取剪贴板类似不管当前的默认文本输入源是什么都会先进行 OCR 范围选择然后执行一次 OCR再进入翻译流程。典型场景是在 HOOK 模式下遇到选择肢需要临时识别屏幕上的选项文本时临时用一次 OCR 翻译选择肢或在 OCR 模式下临时识别某个偶尔出现的新位置再次进行 OCRocr_once_follow当使用过一次进行一次 OCR后用这个按钮可以在原来的位置再次执行 OCR而无需重新选择识别区域适合连续识别同一区域的动态内容。源码中ocr_once通过信号self.ocr_once_signal.emit()触发ocr_once_follow调用self.ocr_do_function(self.ocr_once_follow_rect)translatorUI.py 第 582 行内部复用上一次的识别矩形。四、HOOK 模式专属按钮以下按钮在默认配置中带有belong: [texthook]字段仅在 HOOK 模式下可用模式启用时自动出现在工具栏。4.1 选择游戏selectgame点击按钮弹出选择游戏进程窗口源码绑定gobject.base.createattachprocess()从中选择要 HOOK 的游戏进程。这是 HOOK 模式的起点先选定进程再选择文本。4.2 选择文本selecttext点击按钮弹出选择游戏文本窗口选择要翻译哪一条 HOOK 到的文本。需要注意选择文本窗口在选择进程后会自动弹出因此这个按钮实际上是用来更换已选的文本或修改相关设置用的如文本编码、指针选项等。4.3 游戏设置open_game_setting当使用 HOOK 模式连接到游戏、或使用 OCR 模式绑定游戏窗口后可通过此按钮直接打开当前游戏的设置窗口源码绑定dialog_setting_game(commonstylebase, gameuid, 1)见 translatorUI.py 第 577 行。这里配置的是该游戏专属的翻译参数与全局设置相互独立。五、OCR 模式专属按钮以下按钮默认配置中带有belong: [ocr]字段仅在 OCR 模式下可用。5.1 选取 OCR 范围selectocrrange在 OCR 模式下用于选取 OCR 区域、更换 OCR 区域或者在激活OCR设置-其他-多重区域模式时增加新的 OCR 区域。左键点击开始选取/更换范围绑定clickRange右键点击先清除所有已选取范围再添加新的区域绑定clickRangeclear。5.2 显示/隐藏范围框hideocrrange用于控制 OCR 范围框的显示状态左键点击切换范围框显示/隐藏当未选择任何 OCR 范围时使用该按钮显示 OCR 范围会自动把范围设置为上一次选择过的 OCR 区域绑定showhideocrrange其状态回调self.showhidestate驱动图标/颜色变化右键点击清除所有已选取范围绑定clear_signal_1.emit。六、翻译优化词典类按钮以下三个按钮效果类似都是快捷打开翻译优化设置窗口、增加新的指定词条用的按钮锚点打开的设置窗口默认配置键翻译前替换anchor-noundict_direct翻译前替换设置vndbnamemap对应 vndbnamemap.pynoundict_direct专有名词翻译anchor-noundict专有名词/名词词典对应 noundict.pynoundict翻译结果修正anchor-fix翻译结果修正对应 transerrorfix.pyfix三者统一定义了绑定游戏优先的打开逻辑鼠标左键点击当有绑定的游戏HOOK 链接游戏 / 剪贴板、OCR 绑定窗口时打开该游戏的专用词典设置否则打开全局的词典设置。源码通过loadpostsettingwindowmethod_maybe(...)实现即尽力使用游戏专用设置鼠标右键点击必然打开全局的词典设置loadpostsettingwindowmethod(...)强制全局。由此可同时维护游戏内专有名词与全局通用词条两套词典且不会互相污染。七、窗口控制与游戏联动按钮7.1 鼠标穿透窗口mousetransbutton激活该按钮后鼠标点击翻译窗口时翻译窗口不会对鼠标点击做出反应而是把点击事件传递给下层窗口。把翻译窗口置于游戏窗口的文本框之上时激活此按钮可以直接点击游戏文本框而不是点到翻译窗口上是悬浮翻译场景下的关键辅助当把鼠标移动到鼠标穿透窗口按钮及其左右一个按钮的区域时会自动退出穿透以便使用工具按钮移出该区域时自动恢复穿透。源码中该按钮绑定changemousetransparentstate(0)状态回调为globalconfig.get(mousetransparent, False)。7.2 窗口背景透明backtransbutton该按钮的作用仅是一键把翻译窗口的不透明度切换到 0。注意当不透明度为 0 时鼠标也会穿透窗口因此它与 7.1 的效果叠加出现。7.3 锁定工具栏locktoolsbutton激活后工具栏将始终显示。未锁定时工具栏的显隐遵循以下规则鼠标移出窗口工具栏自动隐藏鼠标重新进入窗口后恢复显示如果用鼠标右键取消锁定仅当鼠标进入到锁定工具栏按钮及其左右一个按钮的区域时工具栏才恢复显示源码中右键绑定的是changetoolslockstateEx即扩展锁定逻辑未锁定时若同时激活了鼠标穿透窗口仅当鼠标移动到鼠标穿透按钮及其左右区域时工具栏才显示否则只要鼠标进入翻译窗口工具栏就显示。此外文档特别说明了窗口特效下的渲染细节如果当前使用了窗口特效Aero/Acrylic且不锁定工具栏工具栏会处于文本区的 z 轴之上的区域而非处于文本区的 y 轴上面。原因是 Windows 平台下使用窗口特效时若工具栏只是被隐藏而非将其窗口高度缩去被隐藏的工具栏仍会渲染亚克力/Aero 背景导致工具栏所在区域出现一块空白。7.4 移动move用于拖动翻译窗口。实际上当按钮栏存在没有按钮的额外空白区域时都可以随意拖动窗口该按钮仅用来预留一个拖动位置方便工具栏被按钮填满时仍可拖动。7.5 窗口缩放fullscreen当绑定游戏窗口后可以一键使用内置的 Magpie对游戏窗口进行缩放。默认左键为窗口化缩放右键为全屏缩放可以在工具按钮设置面板中通过特殊功能开关LeftRightFunctionSetter配置键fullscreen_left_full切换右键和左键点击功能。源码中左键调用_fullsgame(not fullscreen_left_full)、右键调用_fullsgame(fullscreen_left_full)translatorUI.py 第 510 行即左键与右键行为严格对调。7.6 窗口截图grabwindow如果当前正在使用 Magpie 进行缩放会对放大后的窗口进行截图当绑定游戏窗口后可以对绑定的窗口进行截图。截图方式优先使用 GDI 截图若失败则使用 Windows.Capture 截图默认左键点击把截图保存到文件右键点击把截图保存到剪贴板同样可通过工具按钮设置面板的特殊功能开关配置键grabwindow_left_savefile切换左右键功能。7.7 游戏静音muteprocess当绑定游戏窗口后可以一键对游戏进程进行静音/取消静音省去在系统音量合成器中手动寻找游戏进程的麻烦。按钮为双图标状态静音/有声状态回调为self.processismuteed。7.8 绑定窗口bindwindow文档强调该按钮非常重要许多功能都依赖于先设置它才可用。绑定游戏窗口后窗口缩放、窗口截图、游戏静音、跟随游戏窗口-游戏失去焦点时取消置顶与游戏窗口移动时同步移动以及记录游戏时间等功能才可用。关键行为不论 HOOK / OCR / 剪贴板模式该按钮都可用HOOK 模式下会自动根据连接的游戏自动绑定游戏窗口但也可以用该按钮重新选择其他窗口OCR 模式下绑定窗口后还额外允许游戏窗口移动时同步自动移动 OCR 区域和范围框OCR / 剪贴板模式下绑定窗口后也可以和 HOOK 模式一样关联到当前游戏的游戏设置从而使用当前游戏的专用翻译优化词典等。源码中该按钮通过信号bindcropwindow_signal.emit()触发绑定流程按钮状态由self.isbindedwindow驱动。7.9 窗口置顶keepontop取消/置顶翻译窗口状态回调为globalconfig.get(keepontop, True)默认置顶。绑定窗口后再配合跟随游戏窗口相关配置即可实现翻译窗口始终覆盖在游戏窗口之上的经典布局。7.10 可选取的selectable使得翻译窗文本区中的文本可以进行选择默认开启selectable配置为true。左键点击切换文本可选状态绑定setselectable右键点击若激活时点击的是鼠标右键setselectableEx则会禁止拖拽非文本区域以移动窗口适合需要频繁框选文本复制场景的用户。八、文本处理与辅助功能按钮8.1 显示/隐藏原文showraw切换是否显示原文日文/英文等源语言文本立即生效。状态回调为globalconfig.get(isshowrawtext, True)。适合只看翻译、或需要对译对照的阅读偏好。8.2 显示/隐藏翻译showtrans切换是否使用翻译是翻译的总开关关闭后将不会进行任何翻译。行为细节如果已经进行过翻译关闭后隐藏翻译结果重新打开时重新显示本次的翻译结果如果未进行过翻译从隐藏切换到显示时会触发对当前句子的翻译。状态回调为globalconfig.get(showfanyi, True)。这是区分暂停翻译与隐藏结果两个概念的关键按钮。8.3 朗读langdu左键点击对当前文本进行语音合成TTS朗读源码为gobject.base.readcurrent(forceTrue)force参数保证即使文本被判为跳过也强制朗读右键点击中断当前朗读gobject.base.audioplayer.stop()。该朗读无视跳过如果在语音指定中匹配当前文本目标为跳过使用按钮朗读时仍会强制朗读。朗读使用的引擎在语音设置中配置参见 ttsengines.md。8.4 复制到剪贴板copy复制当前提取到的文本到剪贴板一次源码为NativeUtils.ClipBoard.setText(gobject.base.currenttext)。文档特别提示如果想要自动输出到剪贴板应当激活文本输入-剪贴板-自动输出-自动输出文本而不是依赖手动点击此按钮。8.5 显示/隐藏历史文本history打开或关闭历史文本窗口源码发送transhis.showsignal信号用于回看本次会话中已经翻译过的所有句子可回溯查询之前出现的名词或剧情信息。8.6 游戏管理gamepad_new打开游戏管理器界面源码绑定dialog_savedgame_integrated用于管理已记录的游戏列表、游戏时间与各游戏的专属配置。8.7 编辑edit打开编辑窗口用于运行编辑当前提取到的文本。在该窗口中可以修改文本后再去进行翻译对 OCR 识别错字、HOOK 抓取的乱码做人工修正再翻译或者翻译任何自行输入的文本把编辑器当作一个手动翻译输入框。8.8 编辑 翻译记录edittrans打开当前游戏的翻译记录编辑窗口直接查看并修正当前游戏已保存的翻译记录源码绑定edittrans(gobject.base.commonstylebase)。8.9 查词searchwordW如果当前有文本被选取则查询选取的文本并打开查词窗口searchwordW.search_word.emit(选中文本)否则只是打开或关闭查词窗口。源码实现见callopensearchwordwindow()translatorUI.py 第 654 行与内置词典系统联动参见 internaldict.md。8.10 备忘录memory针对当前正在玩的游戏打开备忘录窗口左键点击打开当前游戏的备忘录右键点击打开全局备忘录源码dialog_memory(commonstylebase, True)第二个参数为真表示全局。适合记录剧情猜测、道具清单等与当前游戏强相关的临时信息。8.11 模拟按键 Ctrl / Entersimulate_key_ctrl / simulate_key_enter向游戏窗口发送一次模拟按键主要用于串流 / 平板等无法直接操作键盘的场景。源码实现translatorUI.py 第 360 行先SetForegroundWindow将游戏窗口置前再通过keybd_event发送VK_CONTROL或VK_RETURN的按下与抬起事件。8.12 重置翻译状态reset_TS_status重置翻译状态主要针对日益增长的大模型翻译需求可以清除大模型保存的上下文和其他信息避免长对话累积导致上下文污染、token 膨胀或翻译风格漂移。源码绑定gobject.base.prepare即重新初始化翻译上下文。九、窗口管理按钮9.1 最小化到托盘minmize一键将翻译窗口最小化到系统托盘配合后台挂机翻译场景使用。9.2 退出quit退出翻译器。十、从源码看按钮体系的实现原理10.1 按钮控件IconLabelX所有工具按钮都是自定义控件IconLabelXbuttonbar.py 第 33 行它继承自LLabel本质是一个可响应用户交互的图标标签定义了三类信号clicked左键、rightclick右键、middleclick中键通过setIconStr(icon, color)支持 FontAwesome 矢量图标与本地图片两种渲染方式在mouseReleaseEvent中根据按下位置与鼠标按键分发对应信号buttonbar.py 第 183 行尺寸由buttonsize、toolwdivh、toolscale等常量共同决定buttonbar.py 第 38 行。10.2 按钮注册takusanbuttons 与 buttonfunctionsButtonBar.takusanbuttons()buttonbar.py 第 283 行负责把一个按钮接入工具栏参数包括点击回调、右键回调、tooltip、按钮名以及可选的状态回调iconstate驱动双图标切换colorstate驱动状态颜色切换。而translatorUI.py的create_buttons()translatorUI.py 第 374 行使用元组列表集中注册全部按钮其中复杂按钮用buttonfunctions类buttonbar.py 第 15 行同时挂载左右键与状态回调。例如locktoolsbutton注册了左键changetoolslockstate、右键changetoolslockstateEx、iconstate与colorstate均指向locktools配置——这解释了文档中右键取消锁定后需进入按钮区域才恢复显示的特殊行为。10.3 布局与对齐三栏结构ButtonBar内部维护三个子布局_left、_center、_rightbuttonbar.py 第 225 行对应居左/居中/居右三个对齐组。adjustbuttons()遍历buttonrank()返回的排序列表把每个可见按钮按buttonalight(name)返回的 0/1/2 放入对应子布局buttonbar.py 第 321 行。因此相对位置的调整都被限定在对齐组中——你只能在一个对齐组内部调整按钮先后顺序跨组的绝对位置由对齐组决定。10.4 默认配置config.json所有按钮的默认状态是否启用、图标、提示、对齐、模式限定定义在 defaultconfig/config.json 的toolbutton字段中第 287 行起。每个按钮的完整配置结构如下selectgame: { use: true, tip: 选择游戏, belong: [texthook], icon: fa.link, align: 2 }字段含义可选值use是否显示该按钮true/falsetip鼠标悬停提示与设置面板中的说明文字任意字符串icon主图标fa.xxx或图片路径或lunaicon2第二种状态图标可选同上belong限定可用模式可选[texthook]、[ocr]align对齐组0居左 /1居右 /2居中用户的实际配置会覆盖默认配置做到开箱即用 高度可定制。十一、总结与使用建议工具按钮是 LunaTranslator 操作频率最高的界面元素其设计体现出两个鲜明特点模式自适应belong机制让 HOOK/OCR 专属按钮随输入源自动出现与隐藏工具栏始终只呈现与当前模式相关的操作一钮多用左键/右键/中键分别承载不同功能如朗读 vs 中断、游戏词典 vs 全局词典、截图到文件 vs 剪贴板配合双图标、状态色与按钮左右区域悬停的辅助机制在极小的空间内容纳了极高的操作密度。建议的使用路径是先在显示设置-工具按钮中按自己的翻译习惯决定每个按钮的显示与对齐把高频操作手动执行、读取剪贴板、锁定工具栏、窗口置顶放在顺手的位置再根据自己常用的模式HOOK 为主还是 OCR 为主确认专属按钮是否可见最后为窗口缩放和窗口截图配置好左/右键行为。如需对某个按钮进行更深入的设置如朗读引擎、OCR 范围、翻译优化词典可通过对应文档章节继续深入basicuse.md、hooksettings.md、ocrparam.md、textprocess.md。【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考