FlexiTools - 開發者指南

1

環境建置 (Environment Setup)

FlexiTools 基於 Python 3.9+ 與 Tkinter 構建。為了確保開發環境的一致性，我們強烈建議使用 Conda。

快速開始

1. Clone 專案並進入目錄：

git clone https://github.com/jacky09299/FlexiTools.git
cd FlexiTools

2. 建立並啟用 Conda 環境：

conda env create -f environment.yml
conda activate tools

3. 驗證安裝：

python check_imports.py

若 check_imports.py 顯示 "All modules imported successfully"，即代表環境設定完成。

2

專案架構 (Project Structure)

核心目錄

modules/ - 功能模組存放處。每個子資料夾代表一個獨立功能。
locales/ - 全域語言檔 (en_US.json, zh_TW.json)。
tools/ - 建置腳本 (NSIS 生成、插件打包)。
docs/ - 專案文件與網站源碼 (GitHub Pages)。

關鍵檔案

main.py - 程式入口點。
ui.py - ModularGUI 與 Module 基底類別定義。
main.spec - PyInstaller 打包設定檔。
installer.nsi.template - Windows 安裝程式腳本模板。

3

模組開發 (Module Development)

FlexiTools 採用高度模組化設計。開發新功能只需在 modules/ 目錄下建立新資料夾即可。請參考 modules/template_module。

Step 1: 定義 Metadata (manifest.json)

在模組資料夾中建立 manifest.json。這是版本控制與插件系統的依據。

{
  "name": "my_new_tool",
  "version": "1.0.0",
  "title": "My New Tool",
  "description": "A short description of the tool.",
  "author": "Your Name"
}

Step 2: 實作邏輯 (init.py)

建立 __init__.py 並繼承 Module 類別。這是模組的進入點。

import tkinter as tk
from tkinter import ttk, messagebox
from ui import Module

class MyNewTool(Module):
    def __init__(self, master, shared_state, module_name="MyTool", gui_manager=None):
        # 初始化基底類別
        super().__init__(master, shared_state, module_name, gui_manager)

        # 初始化 UI 元件變數
        self.label = None
        self.btn = None

        # 建立介面
        self.create_ui()

        # 套用語言設定
        self.update_language()

    def create_ui(self):
        """建立 UI 元件，初始使用英文"""
        self.label = ttk.Label(self.frame, text="Hello World")
        self.label.pack(pady=20)

        self.btn = ttk.Button(self.frame, text="Click Me", command=self.on_click)
        self.btn.pack()

    def update_language(self):
        """
        當語言切換時被呼叫。
        必須使用 self.tr(key, default) 更新所有顯示文字。
        """
        super().update_language() # 更新視窗標題

        # Guard Clause: 確保 UI 已建立
        if not getattr(self, 'label', None):
            return

        # 更新元件文字
        self.label.config(text=self.tr("module_mytool_hello", "Hello World"))
        self.btn.config(text=self.tr("module_mytool_click", "Click Me"))

    def on_click(self):
        msg = self.tr("module_mytool_msg", "You clicked the button!")
        messagebox.showinfo(self.module_name, msg)

4

多語言支援 (Localization)

我們採用 "Develop First, Localize Later" (先開發，後翻譯) 的工作流。

實作步驟

開發功能： 在 create_ui 中直接使用英文字串開發。
提取字串： 功能完成後，找出所有使用者可見的文字。
新增 Key： 在 locales/en_US.json 與 zh_TW.json 中加入對應的翻譯。
格式：module_模組名_元件_描述
替換程式碼： 將原字串替換為 self.tr("KEY", "Default")。
實作更新： 在 update_language() 中重新設定元件文字。

JSON 範例

// locales/en_US.json
{
  "module_mytool_hello": "Hello World",
  "module_mytool_click": "Click Me"
}

// locales/zh_TW.json
{
  "module_mytool_hello": "你好，世界",
  "module_mytool_click": "點擊我"
}

5

建置與測試 (Build & Test)

在提交程式碼前，請確保您的模組能通過建置流程。

本地測試 (Run Source)

# 啟動應用程式
python main.py

# 執行自動化測試
python verify_tutorials.py

打包 EXE 與安裝檔 (Build Artifacts)

需要安裝 NSIS。

# 1. 使用 PyInstaller 打包主程式
pyinstaller main.spec

# 2. 生成 NSIS 腳本 (自動掃描 modules/)
python tools/generate_nsis.py

# 3. 編譯安裝檔
makensis installer.nsi

編譯完成後，您將在根目錄看到 FlexiToolsInstaller.exe。

6

CI/CD 與發布

Github Actions Workflow

我們使用 .github/workflows/build.yml 自動化建置流程：

Trigger: Tag 推送 (v*)。
Jobs:
- Setup Conda Environment
- Build EXE (PyInstaller)
- Generate NSIS Script
- Compile Installer (NSIS)
- Upload Release Asset

插件系統 (Plugin System)

模組也可以獨立更新。更新 docs/plugins.json 會觸發 tools/package_changed_plugins.py：

比對 JSON 版本號。
將變更的模組打包為 ZIP。
發布至 gh-pages 分支供使用者下載。

7

貢獻流程 (Workflow)

1. Fork & Branch

Fork 專案並建立分支：feature/your-module-name。

2. Commit

遵循 Commit Message 規範，保持簡潔。

3. Pull Request

發送 PR 至 develop 分支。我們將會審查您的程式碼。

Contents