🎙️ Lecture 15: 【基礎專案】剪貼簿淨化大師：結合 NVDA API 與模擬鍵盤 (Clipboard Cleaner)

🎧 錄音室開場：用 Vibe Coding 解決日常生活痛點！

• 小咪：「Ray，上節課的『三步驟需求拆解法』真的太好用了！我立刻想到一個痛點：我們在網路上複製資料時，常常連同那些看不到的表格、連結、顏色格式一起複製下來。貼到 Word 時版面整個亂掉，我們視障者又看不出來，真的很尷尬！」
• Ray：「這在無障礙世界裡叫做『格式污染』。今天，我們要帶領大家來拆解這個需求，寫出一張更進階的 Prompt。我們要讓 AI 替我們串接 NVDA 的『剪貼簿 API』，並且讓外掛自動幫我們『按鍵盤貼上』！」

🎯 專案二目標：剪貼簿淨化大師 (Clipboard Cleaner)

按下 NVDA+Shift+V 時，外掛會把剪貼簿裡的花俏內容「洗乾淨」變成純文字，並自動幫你按 Ctrl+V 貼上！

🧠 大導演的思維課：如何為「資料處理與鍵盤模擬」設計 Prompt

當我們的外掛涉及到「修改系統資料（如剪貼簿）」與「模擬使用者動作（如貼上）」時，需求設計必須非常謹慎。我們來進行三步驟拆解：

📋 步驟一：拆解你的「無障礙需求」

1. 觸發時機：按下快捷鍵 NVDA+Shift+V 觸發。
2. 資料來源與處理：
   • 來源：讀取系統剪貼簿。
   • 處理：把裡面的格式（HTML/RTF）過濾掉，只留下純文字。
3. 動作與回饋：
   • 動作一：把過濾後的純文字再塞回剪貼簿。
   • 動作二：自動幫我按下鍵盤的 Ctrl+V。
   • 回饋：用語音跟點字朗讀「已貼上純文字」。

💬 步驟二：翻譯成「AI 聽得懂的 NVDA 行話」

為了避免 AI 使用不安全的方法，我們必須在 Prompt 中指定以下 NVDA 專用 API： * 「讀取與寫入剪貼簿」 ➔ 必須指定 NVDA 官方提供的 api.getClipData() 與 api.copyToClip()，這能防止 Windows 剪貼簿鎖死崩潰。 * 「模擬鍵盤按鍵」 ➔ 指定使用 KeyboardInputGesture.fromName("control+v").send()，這是 NVDA 2026.1 最標準且安全的按鍵注入方式。

📝 實戰演練：大導演的 Prompt 派工單

請將以下 Prompt 貼給你的 AI 工程師：

「你現在是專業的 NVDA 視障輔助軟體外掛工程師。請幫我寫一個全域外掛（GlobalPlugin），檔案名為 purePaste.py。

1. 開發需求描述： - 類型：全域外掛（GlobalPlugin），請綁定快捷鍵 kb:NVDA+shift+v。 - 剪貼簿處理：請使用 NVDA 官方的 api.getClipData() 讀取剪貼簿。如果剪貼簿沒有文字，請呼叫 ui.message("剪貼簿是空的") 並結束。 - 格式淨化：將讀取出來的純文字，使用 api.copyToClip() 重新寫入剪貼簿，以清除 HTML 等格式資訊。 - 模擬貼上：請呼叫 keyboardHandler.KeyboardInputGesture.fromName("control+v").send() 模擬按下 Ctrl+V 完成貼上。 - 播報提示：最後以 ui.message("已淨化並貼上") 提示使用者。

2. 嚴格規範限制： - 嚴禁使用 Python 的 win32clipboard 庫，必須完全採用上述 NVDA 官方的 api 模組，以維持相容性。 - 程式碼必須採用標準縮排，且必須有給一般人看得懂的詳細中文註釋，逐行解釋其運作原理，讓不懂寫程式代碼的人也能完全了解。

請直接輸出完整程式碼。」

🛠️ 看懂 AI 寫的代碼：逐行白話拆解

AI 產出的 purePaste.py 程式碼結構如下，我們一起來讀懂它：

# 引入全域外掛範本
import globalPluginHandler
# 引入快捷鍵裝飾器
import scriptHandler
# 引入 NVDA 官方 API 控制庫（負責剪貼簿讀寫）
import api
# 引入語音/點字播報模組
import ui
# 引入處理鍵盤模擬的模組
import keyboardHandler

class GlobalPlugin(globalPluginHandler.GlobalPlugin):

    # 綁定快捷鍵為 NVDA+Shift+V
    @scriptHandler.script(
        description="Purifies clipboard to plain text and pastes it",
        gestures=["kb:NVDA+shift+v"]
    )
    def script_purePaste(self, gesture):
        # 1. 安全地從系統剪貼簿讀取文字內容
        text = api.getClipData()

        # 2. 檢查剪貼簿是不是空的
        if not text:
            # 如果是空的，報讀提示，並立刻結束函數
            ui.message("剪貼簿是空的")
            return

        # 3. 將純文字重新寫回剪貼簿（這會自動清除所有字型、顏色與表格格式）
        api.copyToClip(text)

        # 4. 建立一個「按下 Control+V」的鍵盤虛擬手勢，並發送出去（模擬貼上）
        keyboardHandler.KeyboardInputGesture.fromName("control+v").send()

        # 5. 發送完成提示，用語音和點字告訴使用者
        ui.message("已淨化並貼上")

💡 核心代碼導讀：

• api.getClipData()：這是 NVDA 寫好的防摔網，能保證抓出來的一定是純文字字串，把所有花俏的樣式丟掉。
• KeyboardInputGesture.fromName("control+v").send()：這行程式碼就像是外掛長出了一隻無形的手，在你的鍵盤上按下 Ctrl+V。

🧪 測試與驗收

1. 將檔案存為 purePaste.py 放進 globalPlugins。
2. 按下 NVDA+Ctrl+F3 重啟。
3. 去複製一段網頁上帶有超連結與顏色的字，按下 NVDA+Shift+V。字會被以純文字自動貼上，大功告成！

👉 下一堂課：Lecture 16 【中階專案】特定軟體專屬守衛：記事本焦點音效提示
👉 回課程大綱：學習地圖