TranslucentTB 使用指南：让你的任务栏随心变

一、项目结构解密：这些文件都是做什么的？

刚拿到代码包时是不是一脸茫然？那么多文件夹和文件，到底哪个才是关键？别担心，我们按功能模块来梳理，让你秒懂项目架构。

核心功能模块

• TranslucentTB 目录：这是程序的"大脑"，包含了主窗口（mainappwindow.cpp）和任务栏属性控制（taskbarattributeworker.cpp）等核心逻辑。简单说，就是控制任务栏透明效果的核心代码都在这里。

• Common 目录：公共代码库，就像工具包一样，提供了配置管理（config）、颜色处理（color.hpp）等基础功能，被其他模块频繁调用。

• Xaml 目录：负责程序的界面展示，包含了各种页面（Pages）和控件（Controls）的实现。你看到的设置界面、颜色选择器都来自这里。

• AppPackage 目录：存放应用打包相关的资源，包括多语言文件（Strings）和图标资源（Assets）。支持中文、英文、日文等多种语言就是从这里实现的。

辅助模块

• ProgramLog 目录：日志系统，记录程序运行时的各种信息，方便开发人员排查问题。

• Tests 目录：单元测试代码，确保各个功能模块的正确性。

• vcpkg 目录：第三方依赖管理，类似手机的应用商店，负责下载和管理程序需要的外部库。

二、启动程序：两种方式任你选

2.1 快速启动：适合普通用户

不想折腾编译？直接用现成的可执行文件最方便：

1. 从项目发布页面下载 TranslucentTB.zip 压缩包
2. 解压到任意文件夹（比如 D:\Tools\TranslucentTB）
3. 双击运行 TranslucentTB.exe
4. 程序启动后会在系统托盘（屏幕右下角）显示图标，右键点击即可进行设置

注意：便携版仅支持 Windows 11 系统，Windows 10 用户建议通过 Microsoft Store 安装

2.2 手动构建：适合开发者

想体验最新功能或参与开发？自己动手编译源码：

1. 准备环境

   • 安装 Visual Studio 2022 Preview
   • 安装 "Desktop development with C++" 和 "Universal Windows Platform development" 工作负载
   • 安装 Windows 11 SDK (10.0.22621.0)
   • 安装 vcpkg 并运行 vcpkg integrate install

2. 获取代码

   git clone -b develop https://gitcode.com/gh_mirrors/tra/TranslucentTB
   

3. 编译运行

   • 用 Visual Studio 打开 TranslucentTB.sln 解决方案
   • 将 AppPackage 设为启动项目（右键点击项目 -> "设为启动项目"）
   • 按 F5 键编译并运行

首次编译可能需要几分钟时间，Visual Studio 会自动下载并编译依赖项

三、配置说明：打造你的个性化任务栏

3.1 用户常见配置项

通过托盘图标右键菜单就能轻松设置这些常用功能：

• 任务栏状态：提供多种视觉效果

  • 透明（Clear）：半透明效果
  • 模糊（Blur）：轻微模糊效果（仅 Windows 10 和 Windows 11 22000 版本支持）
  • 亚克力（Acrylic）：毛玻璃效果，符合微软 Fluent Design 设计语言

• 动态模式：根据不同场景自动切换任务栏样式

  • 窗口可见时：当桌面有打开的窗口时改变样式
  • 窗口最大化时：当窗口最大化时切换样式
  • 开始菜单打开时：开始菜单打开时的特殊样式

• 开机启动：在托盘菜单中勾选"开机启动"，程序会在系统启动时自动运行

3.2 高级自定义：编辑配置文件

想玩点高级的？直接修改配置文件 settings.json：

1. 找到配置文件位置：通常在 %LOCALAPPDATA%\TranslucentTB 目录下
2. 用记事本或 VS Code 打开 settings.json
3. 修改参数，例如设置桌面状态为亚克力效果：

   "desktop_appearance": {
     "accent": "acrylic",
     "color": "#00000000",
     "show_peek": true,
     "show_line": false
   }
   

4. 保存文件后，程序会自动加载新配置（无需重启）

配置文件采用 JSON 格式，每个设置项都有明确的含义，你可以根据 settings.schema.json 文件了解所有可配置项。

3.3 配置迁移：换电脑也不怕

换了新电脑？想在其他设备上使用相同的配置？简单几步即可迁移：

1. 在旧电脑上找到 settings.json 文件
2. 将文件复制到 U 盘或通过云存储发送到新电脑
3. 在新电脑上安装并运行 TranslucentTB 一次（让程序创建必要的文件夹）
4. 关闭程序，用备份的 settings.json 替换新生成的文件
5. 重新启动程序，配置就会生效

提示：定期备份 settings.json 是个好习惯，防止系统重装或意外删除导致配置丢失

四、常见问题解决：遇到问题不用慌

4.1 任务栏没有变化？

可能原因：程序没有获得必要的权限或被其他软件干扰

解决方案：

1. 确保以管理员身份运行程序
2. 检查是否安装了其他任务栏美化软件（如 StartIsBack、Classic Shell 等），尝试暂时禁用它们
3. 重启 Windows 资源管理器：按下 Ctrl+Shift+Esc 打开任务管理器，找到 "Windows 资源管理器"，右键点击"重新启动"

4.2 程序启动后托盘没有图标？

可能原因：托盘图标被隐藏或配置中设置了隐藏托盘

解决方案：

1. 检查系统托盘是否设置了图标隐藏：点击托盘箭头，查看是否在"显示隐藏的图标"中
2. 修改配置文件：打开 settings.json，将 "hide_tray" 设置为 false
3. 重新启动程序

4.3 Windows 更新后程序无法运行？

可能原因：系统更新改变了任务栏相关接口

解决方案：

1. 检查是否有最新版本的 TranslucentTB，通常开发者会很快适配系统更新
2. 如果使用的是便携版，尝试安装商店版
3. 查看项目的 issue 页面，看看其他用户是否遇到类似问题及解决方法

五、项目参与指南：贡献你的力量

5.1 报告问题

使用中发现 bug？可以通过项目的 issue 系统提交报告，报告时最好包含：

• 操作系统版本（如 Windows 11 22H2）
• 程序版本
• 问题复现步骤
• 错误截图或日志

5.2 代码贡献

想直接参与开发？按照以下步骤：

1. 从项目仓库克隆代码
2. 创建新的分支进行开发
3. 提交 Pull Request
4. 等待审核和合并

5.3 翻译工作

帮助将程序翻译成更多语言：

1. 复制 Xaml\Strings\en-US 和 AppPackage\Strings\en-US 目录
2. 重命名为目标语言代码（如 zh-CN 表示简体中文）
3. 翻译其中的 Resources.resw 文件
4. 提交翻译后的文件

TranslucentTB 是一个开源项目，欢迎所有人参与贡献，让这个工具变得更好用！