🎙️ Lecture 19: 【實戰演練六】Browse Mode 網頁快鍵導航 (clickable_nav)

🎧 錄音室開場：解放網頁導航的全新快捷鍵！

• Ray：「各位聽眾，我們在 L17 學過如何用 TreeInterceptor 掃描網頁上的核取方塊。今天，我們要介紹一個真實開發出來的外掛案例：『網頁可點擊元素導航 (clickable_nav)』！」
• 小咪：「這個外掛有什麼特別的？」
• Ray：「NVDA 內建了很多單鍵導航，比如按 H 跳到標題，按 B 跳到按鈕。但在現代網頁裡，很多工程師不用傳統按鈕，而是把普通的文字加上 onclick 變成『可以點擊的元素』。NVDA 內建沒有快捷鍵可以跳轉到這些元素。所以，這個外掛實作了：按下 Z 或 Shift+Z，就能直接跳到網頁中下一個或上一個『可點擊 (Clickable)』的隱藏按鈕！」

🎯 專案解密：clickable_nav 的核心運作原理

如果我們打開這個外掛的原始碼（clickable_nav/__init__.py），我們會看到幾個高階大師技巧。我們不改代碼，但我們要學會「看懂」它為什麼這樣寫！

1. 確保只在「網頁模式」下生效

網頁跳轉只有在瀏覽器中才有意義。代碼中有一段安全判斷：

vbuf = getattr(api.getFocusObject(), 'treeInterceptor', None)
if not vbuf or not vbuf.isAlive:
    return gesture.send()

這段話的意思是：「如果你現在不在網頁虛擬緩衝區 (TreeInterceptor)，那這個快捷鍵 Z 就不歸我管，請把按鍵 send() 還給 Windows，讓使用者可以正常打出英文字母 Z。」這就是我們說過的安全邊界！

2. 多重特徵搜尋（找尋目標）

怎麼在茫茫網頁中找到「可以點擊」的東西？ 外掛寫了三個搜尋條件 (search_options)： 1. states 包含 CLICKABLE：NVDA 認定的可點擊狀態。 2. clickable 屬性為 True。 3. IAccessibleAction_click：這是底層的無障礙點擊行為。 AI 透過這三個條件，呼叫 vbuf._iterNodesByAttribs，瞬間在虛擬樹中搜出下一個目標，並將游標移過去 (item.moveTo())！

📝 大導演的 Vibe Coding 派工單 (Prompt)

如果你想要 AI 幫你重頭寫出這個外掛，你的 Prompt 該怎麼下？

「你現在是頂尖的 NVDA 外掛工程師。請幫我寫一個全域外掛，實現網頁中的『可點擊元素單鍵導航』。

開發規範： 1. 請使用 @scriptHandler.script 綁定快捷鍵 Z (下一個) 與 Shift+Z (上一個)。 2. 【安全檢查】：執行前，先獲取 api.getFocusObject().treeInterceptor。如果不在 Browse Mode，請使用 gesture.send() 將按鍵放行給系統。 3. 【元素搜尋】：請使用 vbuf._iterNodesByAttribs 向下或向上搜尋。搜尋條件必須涵蓋 controlTypes.State.CLICKABLE 狀態、clickable 屬性，以及具備 IAccessibleAction_click 動作的節點。 4. 找到後，請呼叫節點的 moveTo() 與 report() 來移動焦點並朗讀。找不到則用語音提示。

請給我完整的 __init__.py 程式碼。」

🎓 學習總結

透過閱讀 clickable_nav 的代碼，我們學到了非常實用的技巧：在寫全域外掛時，如果你的快捷鍵是普通字母（如 Z），請務必在判斷條件不符時，呼叫 gesture.send() 放行按鍵。否則你的 NVDA 會把你鍵盤上的 Z 鍵永遠吃掉，讓你再也打不出 Z！

👉 下一堂課：Lecture 20 【實戰演練七】進階語音過濾與正則運算 (brlReader)
👉 回課程大綱：學習地圖