README.md

輸入框（InputBox）⌨️

一款適用於 Windows 電競掌機的文字輸入輔助應用程式，用於改善在《FINAL FANTASY XIV 繁體中文版》遊戲環境中，於特定操作情境下無法直接使用 Windows 觸控式鍵盤輸入中文的使用體驗。✨

專案網頁 🌐

• 專案網頁：https://rubujo.github.io/InputBox/
• 下載最新版本：https://github.com/rubujo/InputBox/releases

一、功能說明 💡

• 輔助輸入 ⌨️：提供單一文字方塊，方便使用控制器開啟 Windows 觸控式鍵盤（TabTip.exe）並輸入文字。
  • 需要配合輸入法（微軟注音、微軟倉頡及 Microsoft 速成）的「遊戲控制器」鍵盤配置使用。
  • 此鍵盤配置為 Windows 11 在部分版本中提供的系統功能，並採用微軟的 Controlled Feature Rollout（CFR） 分階段下放機制。
    • 實際可用性可能因系統版本、裝置與功能下放進度而異。
• 支援全域快速鍵 🎹：可快速喚出應用程式，具備快速鍵註冊衝突自動回退機制。
• 智慧邊界彈回 🎯：當視窗因拖曳、解析度變更或 DPI 縮放而超出螢幕範圍時，會自動彈回可視區域內。
• 支援不透明度調整 🌓：可自訂視窗透明度（10% ~ 100%），低於 50% 時會顯示可讀性警告，並支援控制器快速鍵組合快速微調。
• 支援 XInput 與 GameInput 遊戲控制器輸入 API 🎮：
  • XInput：適用於 Xbox 控制器及絕大多數模擬控制器。（預設）
  • GameInput：支援現代標準，無控制器數量限制。
    • 本應用程式具備自動退避機制（GameInput 初始化失敗將自動切換至 XInput）。
• 控制器校正狀態視覺化 🧭：可從右鍵選單中的遊戲控制器調校設定開啟即時診斷視窗，直接查看左、右搖桿的原始點、校正後位置與目前死區範圍，方便檢查飄移、偏移與校正效果，並採用低刺激、易辨識的呈現方式。
• 隱私模式 🔒：支援不記錄輸入內容的隱私模式。開啟瞬間將自動清空目前的輸入框與歷程記錄，提供最高等級的防偷窺保護（可於右鍵選單切換）。此外，開啟後無障礙播報會改為隱私安全訊息，不朗讀實際選取文字或被刪除的字元內容。
• 光敏安全視覺警示 🚨：警示與驗證回饋預設採用單次靜態脈衝，避免連續動畫造成不適；若使用者明確需要，可於右鍵選單重新啟用 1Hz 動畫式視覺警示。
• 支援輸入歷程記錄 📜：僅存在於記憶體中，關閉程式即清除。
• 片語庫 📝：可預先儲存常用文字片段，並於輸入時透過右鍵選單快速插入，節省重複輸入的時間。支援最近使用置頂顯示、分頁瀏覽，以及新增、編輯、刪除、排序、匯出與匯入管理。片語存放於 %AppData%\InputBox\phrases.json，最多可儲存 50 個片語。
• 多控制器自動切換 🔄：支援同時連接多個控制器，並能自動偵測並切換至目前正在活動（有按鍵或搖桿操作）的裝置。
• 控制器主按鍵配置模式 🎮：支援自動、Xbox、PlayStation（○ 確認）、PlayStation（× 確認）與 Nintendo 等配置，可依控制器型別或個人習慣切換，並讓畫面提示、助記詞與實際功能保持一致。
• 動態標題資訊 ℹ️：視窗標題列會即時顯示目前使用的遊戲控制器輸入 API（XInput／GameInput）、硬體裝置名稱，以及目前生效的控制器主按鍵配置。
• 單一執行個體保護 🔐：同一使用者工作階段中僅允許執行一個實例。若重複啟動，將自動喚醒並帶出已在執行中的視窗。
• 多語系支援 🌐：自動跟隨系統語系顯示對應的介面文字，目前支援正體中文（zh-Hant）、簡體中文（zh-Hans）、日文（ja）、韓文（ko）、德文（de）、法文（fr）與英文（en）。
• 深色模式支援 🌙：自動偵測 Windows 系統主題（淺色／深色／高對比），並在偵測到主題變更時提示重新啟動以套用新配色。
• 日誌服務與故障排除 📝：具備例外錯誤記錄功能，當程式發生未捕捉的嚴重錯誤或設定檔存取失敗時，會自動記錄詳細資訊（包含堆疊追蹤）至本地日誌檔中。
  • 日誌檔位置：%LocalAppData%\InputBox\Logs\InputBox.log。
  • 日誌檔輪替：具備自動容量管理（單一檔案 5MB）與備份機制（最多保留 5 個備份檔），確保不佔用過多硬碟空間。

二、系統要求與相容性 🖥️

• 作業系統 🪟：Windows 11 22H2（Build 22621）以上版本。
  • 本需求僅代表本應用程式本身的最低執行環境；部分系統功能（如「遊戲控制器」鍵盤配置）可能採用分階段下放，實際可用性視系統狀況而定。
• 遊戲控制器輸入 API 支援 🎮：
  • XInput：系統原生支援，無需額外安裝。
  • GameInput：系統需具備 GameInput 執行階段。
    • 多數 Windows 11 系統已內建 GameInput 執行階段；若系統未提供或載入失敗，本應用程式會自動退避至 XInput 相容模式。
    • 可轉散發組件（選用）：可透過微軟 Microsoft.GameInput NuGet 套件取得。
      • 安裝方式：執行套件 redist 目錄下的 GameInputRedist.msi。

Steam Deck／SteamOS 3 使用說明 🎮

目前版本已針對 WINE／Proton 與 SteamOS 3 的遊戲模式（Gamescope） 加入相容性調整。整體原則是：Steam Deck 桌面模式盡量保留完整功能；只有遊戲模式（Gamescope）會套用保守限制。

• Steam Deck 桌面模式（KDE Plasma）：
  • 不套用 Gamescope 專用限制。
  • 高風險快捷鍵與返回行為維持可用。
  • 若執行於 WINE／Proton，開啟螢幕鍵盤時會優先嘗試使用 Steam 虛擬鍵盤。
• Steam Deck 遊戲模式（Gamescope）：
  • 會套用單一視窗與焦點安全限制，避免切換視窗、彈出選單或視窗狀態變更造成黑畫面、失焦或渲染表面異常。
  • 開啟螢幕鍵盤時會優先使用 Steam 虛擬鍵盤。
  • 下列功能目前會停用或受限制：
    • 返回前一個視窗（包含複製成功後自動返回）。
    • 視窗透明度調整與重設。
    • 隱私模式快捷切換。
    • 右鍵選單與說明對話框。
    • 重新朗讀全文（R3）。
    • LT／RT 的控制器快捷功能，避免與 Steam 虛擬鍵盤的保留按鍵衝突。
• 注意事項：
  • 本專案目前的 Linux 相容性調整，重點在於 Steam Deck／SteamOS 3 + WINE／Proton 的實際使用情境。
  • 即使在桌面模式下可保留完整功能，螢幕鍵盤、輸入法候選窗與焦點恢復行為仍可能受桌面環境設定影響。
  • 若應用程式在 Steam Deck 上無法正常啟動、顯示異常或行為不穩定，可嘗試改用較新的 Proton 版本，或切換至 Proton Experimental 再重新測試。
  • 若要在 SteamOS 3 的 Steam 啟動選項中明確指定正體中文語系，可加入：

    HOST_LC_ALL=zh_TW.UTF-8 %command%

    • 此設定可讓 WINE／Proton 優先繼承 zh_TW.UTF-8 語系，改善介面語系、資源挑選與部分在地化行為的穩定性。
    • 前提：SteamOS 本機需先生成對應的 zh_TW.UTF-8 語系；若系統尚未提供該 locale，則這個啟動參數不會生效，WINE／Proton 仍可能回退到預設語系。

三、使用方式 📖

0. 一分鐘快速設定教學 🚀

副標：如何在《FINAL FANTASY XIV 繁體中文版》遊戲中使用輸入框？

輸入框不是自動代打工具，而是將「輸入」與「貼上」拆分為兩個步驟。您只需手動觸發每一步，整體流程清楚、直覺、容易上手。

• 步驟一：叫出輸入框
  • 在遊戲中按下您在 Windows 掌機公用程式（例如 Armory Crate SE）中預先設定的呼叫組合鍵，即可快速切換到輸入框。
  • 使用前請先啟動輸入框。
• 步驟二：輸入後按目前配置下的確認鍵
  • 使用 Windows 觸控式鍵盤完成輸入與選字後，先關閉 Windows 觸控式鍵盤，再按下目前控制器主按鍵配置所對應的確認鍵。
  • 例如 Xbox 預設為 A、PlayStation 可依模式使用 ○ 或 ×、Nintendo 則為 A。
  • 系統會將文字複製到 Windows 剪貼簿，並返回前一個視窗。
• 步驟三：在遊戲中按貼上組合鍵
  • 回到《FINAL FANTASY XIV 繁體中文版》遊戲後，在遊戲內的聊天輸入框按下遊戲中預設的貼上組合鍵（需先於遊戲設定中啟用），貼上剛才複製的文字，最後送出即可。

補充說明：這是一套半自動、手動觸發的聊天輔助流程，重點在於穩定輸入與快速貼上。

1. 鍵盤操作 ⌨️

• Ctrl + Alt + Shift + I（預設）：全域快速鍵，用於顯示本應用程式。（可於設定檔中自訂修改）
  • 需先啟動並在背景執行後，快速鍵才會生效。
• Enter：
  • 文字方塊為空時：開啟 Windows 觸控式鍵盤（TabTip.exe）。
  • 文字方塊有文字時：將文字複製到 Windows 剪貼簿，並在系統允許的情況下，將焦點切換回先前的前景視窗。
• Alt + A：功能等同於 Enter。
• Alt + B：不複製直接返回前一個視窗。（與控制器 LB + RB + B 對等）
• Alt + M 或 F10：開啟功能選單。（與控制器目前配置下的選單鍵對等）
• Alt + 方向鍵 ↑／↓：即時增加或減少視窗不透明度（每次增減 5%）。（與控制器 Back／View 鍵 + 方向鍵 ↑／↓ 對等）
• Alt + 0（數字 0）：將視窗不透明度重設為 100%。（與控制器 Back／View 鍵 + 目前配置下的刪除鍵對等）
• Alt + P：切換隱私模式。
• Shift + Enter：換行。
• Shift + 方向鍵：選取文字。
• ESC 鍵：清除輸入。若輸入框已為空，則直接返回前一個視窗。
• F1：開啟說明對話框，顯示鍵盤快速鍵與控制器按鍵對應表。
• Ctrl + M：將焦點跳至文字輸入框。
• 方向鍵 ←／→：移動輸入游標。
• 方向鍵 ↑／↓ 或滑鼠滾輪：瀏覽輸入歷程記錄。
• Home／End：快速跳轉游標至行首或行尾。
• Ctrl + ←／→：按字詞跳轉游標位置。
• Backspace：刪除游標前一個字元或選取的文字。
• Delete：刪除游標後一個字元。

2. 控制器操作（XInput／GameInput）🎮

本應用程式支援動態 控制器主按鍵配置模式。畫面上的按鍵提示、助記詞與實際功能會隨目前設定同步切換，避免 Xbox、PlayStation 與 Nintendo 控制器在顯示與操作上不一致。

• 自動：在使用 GameInput 且成功辨識裝置時，會自動選用最合適的配置。PlayStation 預設採 PlayStation（× 確認），Nintendo 採 Nintendo 配置，其餘則以 Xbox 配置為準。
• 手動指定優先：若您在選單中手動指定 Xbox、PlayStation 或 Nintendo 配置，會優先於自動判斷。
• 按鍵名稱對照：本文中的 Start 鍵 與 Back 鍵，在部分新式控制器上會分別標示為 Menu 與 View；實際功能以本文說明為準。

模式	X（左側鍵）	Y（上側鍵）	A（下側鍵）	B（右側鍵）
Xbox	X（刪除鍵）	Y（選單鍵）	A（確認鍵）	B（取消／清除鍵）
PlayStation（× 確認）	□（刪除鍵）	△（選單鍵）	×（確認鍵）	○（取消／清除鍵）
PlayStation（○ 確認）	□（刪除鍵）	△（選單鍵）	×（取消／清除鍵）	○（確認鍵）
Nintendo	Y（刪除鍵）	X（選單鍵）	B（取消／清除鍵）	A（確認鍵）

• 目前配置下的確認鍵：多功能確認鍵。
  • 文字方塊有文字時：執行確認（複製並返回前一個視窗）。
  • 文字方塊為空時：開啟 Windows 觸控式鍵盤（TabTip.exe）。
  • 選單開啟時：執行選取項目或展開子選單。
• 目前配置下的取消鍵：取消／清除。
  • 選單開啟時：退回上一層選單或關閉選單。
  • 文字輸入時：清除目前輸入內容。
• 目前配置下的刪除鍵：刪除選取文字或游標前一個字元。
  • 功能等同鍵盤 Backspace。
• 目前配置下的選單鍵：開啟右鍵選單（智慧功能選單）。
• 方向鍵 ↑／↓：瀏覽輸入歷程記錄。
• 方向鍵 ←／→：移動輸入游標。
• LB／RB（單按）：在主輸入區中，將歷程記錄一次向上／向下快速翻動 5 筆。
• LB／RB（按住）：持續以 5 筆為單位連續翻動歷程記錄。
• LB + 方向鍵 ←／→ 或 RB + 方向鍵 ←／→：單字跳轉。快速跳轉游標至下一個空白、標點或字元類型邊界。
• 左搖桿：功能等同鍵盤方向鍵。
  • 用於瀏覽輸入歷程記錄或移動游標。
• 右搖桿 ←／→：虛擬選取模式。直接擴張或縮減文字選取範圍；快速連續選取時會有更細緻的「拉鏈感」觸覺／輕量音效同步回饋，按住 LB／RB 時可改為單字粒度的選取擴張／縮減。
• LT／RT：快速將游標跳到文字開頭／結尾。
• LT + RT：快速切換隱私模式。
• 接近 500 字輸入上限時：會逐步提供更緊密的觸覺預警；達到上限後若無法再插入文字，會出現更明顯的「硬牆」回饋。
• Start／Menu 鍵：開啟 Windows 觸控式鍵盤（TabTip.exe），可在已有內容時直接叫出鍵盤進行修正。
• Back／View 鍵：在放開按鍵時，嘗試將焦點切換回先前的前景視窗。
• 按住 LB 與 RB 不放，再按下目前配置下的取消鍵：功能等同於控制器 Back／View 鍵。
  • 避免誤觸 Back／View 鍵時意外切換回先前的前景視窗。
• 按住 LB 與 RB 不放，再按下目前配置下的刪除鍵並維持約 0.8 秒：快速結束並關閉應用程式（加入長按防誤觸保護）。
• 不透明度調整組合鍵：
  • 按住 Back／View 鍵 + 方向鍵 ↑／↓：即時增加或減少視窗不透明度（每次增減 5%）。
  • 按住 Back／View 鍵 + 目前配置下的刪除鍵：將視窗不透明度重設為 100%。
• Back／View 鍵 + 下側鍵（A／×／B）：復原（Undo）上一步輸入操作。
• Back／View 鍵 + 上側鍵（Y／△／X）：全選輸入框中的所有文字。
• 右搖桿按壓（R3）：重讀輸入框中的全部文字內容（無障礙輔助功能）。
• 打字觸感回饋：字元插入時會觸發輕柔脈衝，使打字節奏具有可感知的觸覺確認。批次貼上、片語插入、接近字數上限，或透過觸控式鍵盤搭配注音等輸入法（IME）輸入時不觸發此回饋。

3. 右鍵選單與對話框控制器操作 🖱️

當右鍵選單或數值輸入對話框開啟時，控制器行為會自動切換為導覽模式：

• 右鍵選單導覽：
  • 方向鍵 ↑／↓：上下移動選取項目。
  • 方向鍵 ←／→：進入（或按目前配置下的確認鍵）或退出（或按目前配置下的取消鍵）子選單。
  • 確認鍵／Start／Menu 鍵：執行選取的項目。
  • 取消鍵／Back／View 鍵：關閉選單。
  • 片語子選單開啟時：可使用 LB／RB 快速切換上一頁／下一頁，按住可連發；並以 LT／RT 直接跳至首頁／末頁。
• 數值輸入對話框操作 🔢：
  • 方向鍵 ↑／↓：增加或減少數值。
  • 方向鍵 ←／→：移動游標（或 LB／RB + 方向鍵進行單字跳轉）。
  • 右搖桿 左／右：虛擬選取模式（擴張或縮減選取範圍；按住 LB／RB 時可改為單字粒度的選取調整）。
  • 確認鍵／Start／Menu 鍵或鍵盤 Alt + A：確認並套用。
  • 取消鍵／Back／View 鍵或鍵盤 Alt + B：取消並關閉。
  • 刪除鍵或鍵盤 Backspace：退格（刪除字元／選取內容）。
  • 選單鍵或鍵盤 Alt + Y：重設為預設值。
• 片語管理對話框操作 📝：
  • 方向鍵 ↑／↓：切換選取片語，或在按鈕區導覽。
  • 方向鍵 ←／→：將選取的片語上移或下移；或在清單與按鈕區之間切換焦點。
  • 確認鍵或鍵盤 Enter：將片語插入至輸入框（若焦點在按鈕上則執行按鈕動作）。
  • 取消鍵／Back／View 鍵或鍵盤 Esc ／ Alt + B：關閉。
  • 刪除鍵或鍵盤 Delete ／ Alt + X：刪除選取的片語。
  • 選單鍵或鍵盤 Alt + Y：新增片語。
  • LB／RB：快速切換上一筆／下一筆片語。
  • LT／RT：直接跳到第一筆／最後一筆片語。
  • Start／Menu 鍵：功能等同確認鍵。
• 片語編輯對話框操作 ✍️：
  • 方向鍵 ↑／↓：在欄位與按鈕之間切換焦點。
  • 方向鍵 ←／→：移動游標（或 LB／RB + 方向鍵進行單字跳轉）。
  • 右搖桿 左／右：虛擬選取模式；快速連續選取時會有更細緻的觸覺／輕量音效同步回饋，按住 LB／RB 時可改為單字粒度。
  • 確認鍵或鍵盤 Enter ／ Alt + A：確定並儲存（若欄位為空則開啟鍵盤）。
  • 取消鍵：清空目前欄位；若欄位已空則執行取消。
  • Back／View 鍵或鍵盤 Esc ／ Alt + B：取消並關閉。
  • 刪除鍵或鍵盤 Backspace：退格（刪除字元／選取內容）。
  • 選單鍵：開啟右鍵選單。
  • Start／Menu 鍵：開啟 Windows 觸控式鍵盤。
• 說明對話框操作 ❓：
  • 方向鍵 ↑／↓：逐行捲動內容；長按可連發捲動。
  • LT 鍵／RT 鍵或鍵盤 PgUp ／ PgDn：向上／向下翻頁；長按可連發翻頁。
  • 確認鍵／取消鍵／Start／Menu 鍵／Back／View 鍵或鍵盤 F1 ／ Esc：關閉說明。

4. 右鍵選單操作（滑鼠／觸控／鍵盤／控制器）🛠️

在應用程式的文字輸入框上按下滑鼠右鍵，或透過目前配置下的選單鍵、鍵盤 F10 或 Alt + M，即可於目前位置喚出功能選單：

• 隱私模式 🔒：切換是否記錄輸入歷程。開啟時標題列會顯示 (🔒) 符號，且未來的輸入內容皆不會存入歷程記錄中。為確保最高安全性，開啟的瞬間將自動清空目前的輸入框與所有已儲存的歷程記錄，防止舊資料因誤觸而洩漏。
• 允許中斷廣播 🔇：切換螢幕報讀軟體的廣播中斷行為。勾選（預設）時允許新廣播中斷前一則；取消勾選後，每則訊息皆完整依序播報，適合需要聆聽完整訊息的使用者。
• 動畫式視覺警示 🚨：切換錯誤與驗證提示是否使用 1Hz 動畫式視覺警示。預設為關閉，改採單次靜態脈衝，對光敏感使用者較安全；僅在明確需要動畫提示時建議開啟。
• 返回時最小化 🔽：切換返回前一個視窗時是否自動最小化輸入框視窗。啟用後每次確認或使用 Back／View 鍵返回時，輸入框會縮至工作列，避免視窗遮擋遊戲畫面；初次啟用時會顯示確認提示。
• 片語 📝：展開子選單，顯示已儲存的片語清單（最近插入的片語以 ★ 標示置頂顯示）。點選任一片語即可將其內容插入至文字輸入框。
  • 管理片語…：開啟片語管理對話框，可進行新增、編輯、刪除及排序操作。使用目前配置下的選單鍵新增、確認鍵插入、刪除鍵刪除、左／右方向鍵排序、取消鍵關閉。
  • 匯出片語…：將所有片語匯出為 JSON 檔案，方便備份或轉移至其他裝置。片語清單為空時操作無效。
  • 匯入片語…：從 JSON 檔案匯入片語，將完整取代目前所有片語；匯入前會顯示確認對話框（片語清單已空時直接進行）。
  • 片語數量提示：片語管理對話框會顯示目前數量（例如 12/50）；接近上限時會提供額外視覺提醒，協助避免新增失敗。
  • 片語編輯對話框中的取消鍵行為：若焦點位於名稱或內容輸入框且有文字，先清空該輸入框；若輸入框已為空或焦點不在輸入框，則執行取消關閉。
  • 片語編輯對話框中的 Enter 行為：在名稱或內容輸入框中，按下 Enter 時，若目前欄位為空會開啟 Windows 觸控式鍵盤；若目前欄位已有內容則執行確認驗證。於內容欄位可使用 Shift + Enter 換行。
  • 分頁行為：若片語項目超過單頁容量，子選單會顯示 ◀／▶ 分頁控制；每次重新開啟片語子選單時，會回到第 1 頁。控制器可直接使用 LB／RB 快速切頁，按住可連續翻頁，並以 LT／RT 跳至首頁或末頁。
• 快速鍵設定 ⚙️：
  • 修飾鍵組合：可直接勾選 Alt、Ctrl、Shift 或 Win 鍵作為快速鍵的修飾部分。
  • 擷取主要按鍵：點選後，應用程式會進入擷取狀態，此時按下鍵盤上的任一按鍵即可將其設定為喚出快速鍵的主要按鍵（按下鍵盤 ESC 鍵 或控制器目前配置下的取消鍵可取消擷取）。
  • 快速鍵喚起回饋：透過全域快速鍵叫出主視窗時，若目前有已連線的控制器，會播放一組簡短的「準備完成」握手震動，並同步顯示一次平滑的視覺脈衝，方便在螢幕完全切回前就知道已可開始輸入。
• 設定 ⚙️：包含視窗不透明度、回饋強度、遊戲控制器死區、控制器主按鍵配置與歷程記錄容量等進階設定。
  • 遊戲控制器調校 🎮：可直接調整搖桿死區、重複輸入延遲與速度；若只是暫時出現飄移或殘留偏移，也可使用「重設目前校正狀態」清除執行期學習值，而不影響已儲存設定。若同時連接多支控制器，亦可使用「識別目前遊戲控制器」讓目前作用中的裝置播放特殊震動，方便快速確認是哪一支；另外也提供「校正狀態視覺化…」專屬診斷視窗，即時顯示左、右搖桿的原始輸入點、校正點與死區環，方便做更直觀的漂移檢查與校正確認。
    • 校正狀態視覺化 🧭：即時繪圖的診斷對話框，左圓圖顯示左搖桿（LS），右圓圖顯示右搖桿（RS）。每個圓圖包含四種視覺元素：

      元素	說明
      空心菱形	原始輸入（Raw）：硬體回報的物理位置，包含所有磨損漂移。搖桿完全靜置時應接近圓心。
      藍色實心點	校正後位置（Corrected）：原始值減去系統學習到的偏移量，代表實際輸出給應用程式的位置。正常情況下應比菱形更接近圓心。
      實線圓環	死區進入閾值（Enter）：藍點必須超出此環才會觸發方向輸入。對應設定中的 ThumbDeadzoneEnter（預設 7849）。
      虛線圓環	死區離開閾值（Exit）：方向已觸發後，藍點縮回至此環內側才會釋放。對應設定中的 ThumbDeadzoneExit（預設 2500）。兩環之間為遲滯區，防止邊界抖動。

    • 如何判讀：
      • 搖桿靜置時，菱形（原始）與藍點（校正）若分開，代表系統正在補償漂移，差距越小越好。若兩點都在圓心附近，表示搖桿狀態良好。
      • 輕推搖桿至藍點剛好碰到實線環（Enter）時，狀態列數字即為此時的死區觸發點；可用來確認死區大小是否符合需求。
      • 若藍點在靜置時已超出虛線環（Exit），代表校正後的偏移仍超出離開閾值，需提高 ThumbDeadzoneEnter 或重設校正狀態。
    • 操作：按「重設目前校正狀態」後，偏移量歸零，兩點立即重合；靜置幾秒後系統會重新學習漂移並自動補償。狀態列下方的數字格式為「死區進入／離開 Enter／Exit」，即目前設定的閾值。
  • 控制器主按鍵配置 🎯：可在 自動、Xbox、PlayStation（○ 確認）、PlayStation（× 確認） 與 Nintendo 之間切換。若選擇 自動 並使用 GameInput，系統會依裝置型別自動判斷最適合的配置；若手動指定，則以手動選擇為準。
  • 重新啟動提示 🔄：若您變更了需在下次啟動後才完整套用的項目（例如系統主題／高對比狀態、遊戲控制器輸入 API 或歷程容量），標題列與右鍵選單會同步顯示提示，並提供「立即重新啟動程式」快捷項目。
  • 開啟資料夾 📂：快速開啟位於 %AppData%\InputBox 的應用程式資料儲存路徑，方便手動備份或修改設定檔。
  • 開啟日誌資料夾 📋：快速開啟位於 %LocalAppData%\InputBox\Logs 的日誌檔案存放路徑，方便查閱或回報錯誤記錄。若日誌資料夾尚未建立（即程式從未發生例外），會以警告對話框與螢幕報讀雙重方式提示資料夾不存在。
• 清除歷程記錄 🗑️：手動清空目前儲存在記憶體中的所有輸入歷程記錄。
• 說明 ❓：開啟說明對話框，顯示鍵盤快速鍵與控制器按鍵對應的完整查閱表（功能等同按下 F1）。
• 離開 🚪：關閉並結束應用程式。

5. 設定 ⚙️

本應用程式的設定檔會在第一次執行時自動產生。若需要調整震動強度、視窗還原延遲等參數，請修改此檔案。

(1) 設定檔位置 📂

設定檔位於使用者的應用程式資料夾中：

• 路徑：%AppData%\InputBox\appsettings.json
• 快速存取方式：
  1. 按下 Win + R 開啟執行視窗，輸入 %AppData%\InputBox 並按下 Enter。
  2. 捷徑 🚀：您可以透過右鍵選單中的 「設定」→「開啟資料夾」 快速跳轉至此路徑。
  3. 將會看到 appsettings.json 檔案。

故障排除 🔧：若因手動修改格式錯誤導致程式崩潰或無法啟動，請直接刪除此 appsettings.json 檔案。程式將於下次啟動時自動還原為預設設定。

(2) 設定項目說明 📝

可使用任何文字編輯器（如 Windows Notepad、Visual Studio Code）開啟 appsettings.json 進行編輯。

下表列出所有可調整的設定項目及其行為說明。為了讓內容更容易直接完整顯示，以下改依分類拆成多個表格。

視窗操作

參數名稱	類型	預設值	有效範圍	說明
WindowOpacity	浮點數	1.0	0.1 ~ 1.0	視窗不透明度。低於 0.5（50%）時，UI 會顯示可讀性警告。當系統開啟「高對比」模式時，此值會被強制視為 1.0 以維護視覺安全。
WindowRestoreDelay	整數（毫秒）	50	0 ~ 5000	還原視窗的緩衝時間（毫秒），電腦較慢者可調大此值以避免視窗全黑。
ClipboardRetryDelay	整數（毫秒）	20	0 ~ 1000	剪貼簿鎖定時的重試基礎間隔（毫秒）。
TouchKeyboardDismissDelay	整數（毫秒）	300	0 ~ 5000	觸控鍵盤關閉後的緩衝時間（毫秒）。
WindowSwitchBufferBase	整數（毫秒）	150	0 ~ 5000	切換回遊戲視窗前的基礎等待時間（毫秒）。

操作體驗調整

參數名稱	類型	預設值	有效範圍	說明
IsPrivacyMode	布林值	false	-	是否開啟隱私模式（true／false）。開啟後標題列會顯示 (🔒) 且不記錄輸入歷程。
A11yInterruptEnabled	布林值	true	-	是否允許螢幕報讀廣播中斷前一則訊息。停用後每則訊息皆完整依序播報。
EnableAnimatedVisualAlerts	布林值	false	-	是否允許 1Hz 動畫式視覺警示。停用後將改用單次靜態脈衝，對光敏感使用者較安全；可於右鍵選單直接切換。
MinimizeOnReturn	布林值	false	-	返回前一個視窗時是否自動最小化輸入框。啟用後每次返回都會將視窗縮至工作列；可於右鍵選單直接切換，初次啟用時需確認。
HistoryCapacity	整數	100	1 ~ 1000	輸入歷程記錄的最大保存筆數。

遊戲控制器輸入 API

參數名稱	類型	預設值	有效範圍	說明
GamepadProviderType	字串	"XInput"	-	選擇遊戲控制器輸入 API："XInput" 或 "GameInput"。若 GameInput 初始化失敗將自動退避至 XInput。備註：使用 GameInput 時，遊戲控制器可能需在實際產生輸入（如按鍵或搖桿操作）後，才會開始回報狀態。初次連線時若尚未有反應，請稍候或操作遊戲控制器一次即可。
GamepadFaceButtonModeType	字串	"Auto"	"Auto" "Xbox" "PlayStationTraditional" "PlayStationCrossConfirm" "Nintendo"	選擇控制器主按鍵配置模式。"Auto" 會在可辨識裝置型別時自動套用對應的顯示與功能對照；偵測到 PlayStation 時預設優先使用 PlayStation（× 確認），Nintendo 則採 Nintendo 配置；若手動指定模式，會優先於自動判斷。
ThumbDeadzoneEnter	整數	7849	0 ~ 30000	XInput 標準值（0~32767），無單位。搖桿推動觸發閾值。若控制器搖桿因磨損而產生偏移，可提高此值。
ThumbDeadzoneExit	整數	2500	0 ~ 30000	XInput 標準值（0~32767），無單位。搖桿回彈重置閾值。此值必須顯著低於觸發閾值以防止抖動。
RepeatInitialDelayFrames	整數（幀）	30	1 ~ 300	長按方向鍵時，開始重複輸入前的延遲（幀）。1 幀約為 16.6ms（60 FPS）。
RepeatIntervalFrames	整數（幀）	5	1 ~ 100	長按方向鍵時的重複速度（幀），數值越小越快。1 幀約為 16.6ms（60 FPS）。

回饋

參數名稱	類型	預設值	有效範圍	說明
EnableVibration	布林值	true	-	是否啟用控制器震動回饋（true／false）。
VibrationIntensity	浮點數	0.7	0.0 ~ 1.0	全域震動強度（0.0 ~ 1.0）。若覺得震動太強可改為 0.5；在右鍵選單確認調整後，會立即播放一段短震動預覽。

快速鍵

參數名稱	類型	預設值	有效範圍	說明
HotKeyModifiers	字串	"Alt, Control, Shift"	-	喚醒輸入框的修飾鍵組合。可填寫：Alt、Control、Shift、Win，多個修飾鍵請以逗號隔開。例如 Win + Ctrl + I 請設為 "Win, Control"。
HotKeyKey	字串	"I"	-	喚醒輸入框的主要按鍵（支援按鍵名稱如 "I" 或虛擬鍵碼如 "73"）。

注意 1：大多數設定可立即生效；僅部分項目（例如遊戲控制器輸入 API、歷程容量，以及系統主題／高對比變更）需要重新啟動程式。若有待套用變更，標題列與右鍵選單會顯示提示。🔄

注意 2：本應用程式具備「自動數值保護機制」。若手動在 appsettings.json 中設定了超出「有效範圍」的數值，程式會在啟動或讀取時，自動將該數值修正回最接近的合理界限內，以確保系統穩定性。🛡️

注意 3：本應用程式具備「搖桿死區遲滯（Hysteresis）機制」，會自動確保重置閾值與觸發閾值間有足夠緩衝，避免搖桿老化導致的輸入抖動。🎮

(3) 片語管理（Phrases）設定 📝

片語資料儲存於專屬的 JSON 設定檔中，供應用程式的片語庫功能使用。

片語檔位置 📂

片語檔位於使用者的應用程式資料夾中：

• 路徑：%AppData%\InputBox\phrases.json
• 快速存取方式：
  1. 按下 Win + R 開啟執行視窗，輸入 %AppData%\InputBox 並按下 Enter。
  2. 捷徑 🚀：您可以透過右鍵選單中的 「設定」→「開啟資料夾」 快速跳轉至此路徑。
  3. 將會看到 phrases.json 檔案。

故障排除 🔧：若因手動修改 JSON 格式錯誤導致片語無法載入，請直接刪除此 phrases.json 檔案。程式將於下次啟動時自動重建預設的空片語清單。

片語檔設定項目說明 📋

項目	說明
片語檔案位置	%AppData%\InputBox\phrases.json
檔案類型	JSON 文字檔
檔案容量限制	512 KB（超出此限制時程式會拒絕讀取）
片語數量上限	最多 50 個條目（MaxPhraseCount）
片語名稱長度	最多 50 字符（超出自動截斷）
片語內容長度	最多 500 字符（對齊 FFXIV 聊天輸入框上限；超出自動截斷）
編碼格式	UTF-8（無 BOM）
寫入機制	先寫入暫存檔（.tmp），驗證後再覆蓋原檔，確保檔案損壞時不會遺失資料

超過 50 條限制時的行為 🔄

若使用文字編輯器直接修改 phrases.json，手動新增超過 50 個片語條目，程式會在啟動或讀取時作出以下處理：

情況	行為說明
檔案讀取	自動讀取前 50 個條目，超出部分被忽略。不會產生錯誤訊息。
應用程式新增	當片語數已達 50 個時，右鍵選單中「片語」→「管理片語…」新增按鈕會失效；Add() 方法返回 false，遠端呼叫也會被拒絕。
計數器提示	片語管理對話框會以 12/50 的形式顯示目前數量；接近上限時會提供額外視覺提醒（橙色或紅色背景）。

建議做法 💡：建議透過應用程式的片語管理對話框或**右鍵選單「片語」→「匯出片語…」／「匯入片語…」**進行管理與備份。若需直接手動編輯 JSON，請確保：

1. JSON 格式正確（可使用 JSONLint 驗證）
2. 條目數≤ 50 個
3. 每個片語名稱 ≤ 50 字符，內容 ≤ 500 字符
4. 檔案大小 ≤ 512 KB

四、震動回饋說明 📳

本應用程式提供細膩的震動回饋以增進操作直覺：

• 短促點擊感 🖱️：移動游標、導覽輸入歷程、或在選單中切換項目時觸發。
• 明確確認感 ✅：文字成功複製到剪貼簿、或視窗成功切換回目標視窗時觸發。
• 狀態重置感 🔄：清空文字輸入框、或將不透明度重設為 100% 時觸發。
• 強烈警告感 ⚠️：操作發生錯誤、輸入歷程到底／到頂、或寫入剪貼簿失敗時觸發。

五、疑難排解 🔍

1. Windows 觸控式鍵盤不會在輸入（鍵盤 Enter 鍵／控制器確認鍵）後自動關閉 ⌨️

這是觸控式鍵盤（TabTip.exe）的系統行為，本應用程式不會強制將其關閉。若要將其關閉，請按一下右上角的 X 按鈕，或使用目前配置下的控制器取消鍵。

若需使用控制器目前配置下的取消鍵關閉觸控式鍵盤，可將其「鍵盤配置」設定為「遊戲控制器」。

2. 從 Xbox 全螢幕體驗切換回 Windows 桌面後，應用程式視窗過大 📺

可手動縮放視窗大小（使用手指或滑鼠）。

3. Windows 觸控式鍵盤不會顯示 ⌨️

請檢查以下設定：

Windows 設定 → 時間與語言 → 輸入 → 觸控式鍵盤 → 「顯示觸控式鍵盤」的選項。

若需讓觸控式鍵盤一律顯示，可將此選項設定為「一律」。

4. 在桌面環境下使用「搖桿模擬滑鼠」拖曳視窗時，發生卡頓或功能失效 🖱️

此現象主要發生在 ROG Ally 系列掌機，由於本應用程式支援遊戲控制器 API（GameInput／XInput），若 Armory Crate SE（ACSE） 的控制模式設為「自動」，且已手動將本應用程式的操作配置設定為「遊戲控制器」，系統會在視窗開啟時自動將配置切換為「遊戲控制器」模式。

這會導致原本在桌面環境下用於模擬滑鼠游標的搖桿功能失效（轉為傳送原生控制器訊號），進而造成無法透過搖桿模擬滑鼠來拖曳視窗。

解決方法 ✅：

• 將 Armory Crate SE 的控制模式手動改為「桌面」。
• 直接使用觸控螢幕進行拖曳操作。

5. 在 Steam Deck 遊戲模式下切換應用程式後，返回本應用程式時輸入框未取得焦點，控制器按鈕無反應 🎮

這是遊戲模式（Gamescope）下的視窗焦點限制，屬於預期行為。

解決方法 ✅：

• 觸控：用手指直接點擊輸入框一下，即可讓輸入框取得焦點。
• 觸控板：以觸控板搭配 Steam 鍵 + 滑鼠右鍵（R1），將游標移至輸入框後按下確認，即可恢復控制器操作。

⚠️ 注意：使用觸控板搭配 Steam 鍵 + 滑鼠右鍵（R1）的操作方式，需先在 Steam 的控制器設定中，將觸控板的對應動作配置為「滑鼠」模式，並確認相關組合鍵已啟用，才能正常使用。

六、應用程式的設計原則 🛡️

本應用程式遵循以下設計原則：

1. 不與任何遊戲或應用程式進行互動。
2. 不讀取、不修改、不注入任何第三方程式。
3. 不模擬鍵盤或滑鼠輸入。
4. 不自動貼上內容至其他視窗。
   • 僅複製至 Windows 剪貼簿。
5. 不偵測或識別任何特定應用程式。
6. 僅在使用者主動操作時，開啟 Windows 觸控式鍵盤（TabTip.exe）。
7. 本應用程式視窗預設為最上層顯示（TopMost），以確保在全螢幕或控制器操作環境下不被其他視窗遮擋。

總結而言，本應用程式之運作邏輯與系統內建之「記事本」或「剪貼簿管理員」本質相同，僅作為文字中轉使用，不具備任何修改、攔截或代理目標程式功能之能力。本專案僅設計為解決特定硬體環境下操作不便之一般性輔助應用程式。✨

七、關於 Microsoft SmartScreen 與防毒軟體提示 ⚠️

本應用程式為第三方應用程式，未經 Microsoft Store 發佈，亦未以商業程式碼簽章憑證簽署。

因此，在首次下載或執行時，Microsoft SmartScreen 或部分防毒軟體可能會顯示「未受信任」或相關安全性警告。

本應用程式遵循前述設計原則，是否下載、執行或使用本應用程式，請依個人需求與環境自行評估。🛡️

八、編譯與發佈 🛠️

本專案基於 .NET（C#）開發，支援透過 Visual Studio 或 .NET CLI 進行編譯與發佈。為了提供最便利的使用者體驗，建議發佈為「獨立的單一執行檔」。📦

1. 使用 .NET CLI 發佈 💻

請開啟終端機或命令提示字元，並切換至原始碼目錄（即 src\InputBox 資料夾下），執行以下指令：

dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:PublishReadyToRun=true

參數說明：

• -c Release：以 Release 模式進行建置。編譯器會對程式碼進行最大程度的最佳化，並移除除錯資訊，使應用程式執行速度更快、資源佔用更低。
• -r win-x64：指定目標執行階段為 Windows 64 位元作業系統。
• --self-contained true：啟用獨立式部署。這會將底層的 .NET 執行階段與應用程式一併打包，使用者無需在電腦上預先安裝任何 .NET 環境即可直接執行。
• -p:PublishSingleFile=true：啟用單一檔案發佈。會將應用程式本身及其所有依賴的函式庫全部打包進單一個 .exe 執行檔中，讓資料夾保持乾淨，方便使用者複製或分享。
• -p:PublishReadyToRun=true：啟用 ReadyToRun 預先編譯。這會在建置時提前將部分程式碼編譯為原生機器碼，減少執行時即時編譯的負擔，能顯著縮短應用程式的冷啟動時間，讓喚出輸入框的反應更迅速。

發佈完成後，編譯好的單一執行檔會生成在以下路徑：

bin\Release\net10.0-windows\publish\win-x64\InputBox.exe

2. 使用 Visual Studio 發佈 🚀

1. 在 Visual Studio 的「方案總管」中，右鍵點擊 InputBox 專案，選擇 [發佈]。
2. 若您已經有匯入專案內的 *.pubxml，請直接點擊 [發佈] 按鈕。
3. 若需手動設定，請選擇目標為 資料夾，並在「顯示所有設定」中設定以下參數：
   • 部署模式：獨立式
   • 目標執行階段：win-x64
   • 展開「檔案發行選項」，勾選 [產生單一檔案] 跟 [啟用 ReadyToRun 編譯]。
4. 點擊 [儲存] 後再點擊 [發佈] 即可。

九、測試 🧪

為確保異動不造成行為回歸，建議在發佈前先執行測試（含單元測試與 UI 冒煙測試）。

1. 執行單元測試

dotnet test tests/InputBox.Tests/InputBox.Tests.csproj

2. 顯示詳細輸出（除錯用）

dotnet test tests/InputBox.Tests/InputBox.Tests.csproj --logger "console;verbosity=detailed"

3. 收集 Code Coverage（與 CI 一致）

dotnet test tests/InputBox.Tests/InputBox.Tests.csproj -c Release --no-build `
  --filter-not-trait "Category=UI" `
  --coverage `
  --coverage-output-format cobertura `
  --coverage-output coverage.cobertura.xml

4. 執行 UI 冒煙測試（需桌面環境）

$env:INPUTBOX_RUN_UI_TESTS = "1"
dotnet test tests/InputBox.Tests/InputBox.Tests.csproj -c Release --no-build --filter-trait "Category=UI"
Remove-Item Env:INPUTBOX_RUN_UI_TESTS -ErrorAction SilentlyContinue

注意：本專案使用 Microsoft Testing Platform（MTP）；UI 冒煙測試需要 Windows 桌面環境與 INPUTBOX_RUN_UI_TESTS=1 環境變數才會執行。相關測試規範與注意事項請參閱 docs/engineering/testing.md 與 tests/InputBox.Tests/README.md。

十、聲明 📢

1. 本專案使用 AI 服務輔助開發、翻譯、圖示生成、文件撰寫以及網頁製作。 🤖
2. 本應用程式依賴 TabTip.exe 以開啟 Windows 觸控式鍵盤，僅支援於 Windows 11 22H2（Build 22621）以上版本執行。
   • 實際系統功能（如觸控式鍵盤行為或鍵盤配置）可能因系統版本與功能下放狀況而有所差異。
3. 本應用程式為非官方第三方應用程式，與任何遊戲或服務之開發商、發行商、代理商或營運單位皆無關聯，且無法保證在任何特定遊戲或服務環境中皆能符合使用者的操作需求或使用情境。
4. 使用本應用程式所產生的任何後果，皆由使用者自行承擔。

十一、授權條款 📜

本專案的本體採用 CC0 1.0 Universal 宣告釋出至公眾領域，並於適用法律允許之最大範圍內不主張任何著作權或相關權利。

您可以自由地複製、修改、發佈或執行本應用程式（含原始碼、文件以及網頁等等資源），完全無需取得授權。🕊️

第三方函式庫授權聲明 ⚖️

本應用程式以 自包含部署（self‑contained） 形式發佈，內含執行時所需之第三方函式庫。

以下第三方元件之權利歸原作者所有，並遵循其各自之授權條款，不屬於 CC0 1.0 Universal 授權範圍。

• .NET Runtime：由 Microsoft 及其 貢獻者 開發並採用 MIT License 授權，作為本應用程式之底層執行環境，相關第三方聲明請參閱 THIRD-PARTY-NOTICES。
• Windows Forms（WinForms）：由 Microsoft 及其 貢獻者 開發並採用 MIT License 授權，提供桌面視窗圖形介面基礎架構，相關第三方聲明請參閱 THIRD-PARTY-NOTICES。
• GameInput.Net：由 Cephy314 及其貢獻者開發並採用 MIT License 授權，用於存取 GameInput API。
• UsbVendorsLibrary：由 Cephy314 及其貢獻者開發並採用 MIT License 授權，用於存取裝置資訊。
• USB ID Database（usb.ids）：由 Stephen J. Gowdy 等人維護的公開 USB 裝置識別碼資料庫。該資料庫採雙重授權（GNU General Public License（第 2 版或是更新的版本）／3-clause BSD License）。
  • 本應用程式透過第三方函式庫 UsbVendorsLibrary 使用該資料庫，並於 自包含部署（self‑contained） 發佈之執行檔中以嵌入資源形式包含其內容。
  • 本專案依照官方雙重授權所明示之選項，以 3-clause BSD License 條款隨附發佈；歸因聲明請參閱發佈檔 Licenses/usb_ids_LICENSE.txt。

本專案的詳細條款與免責聲明，請參閱隨附之 LICENSE 文件；發佈檔 Licenses/ 資料夾內含 ThirdPartyNotices.txt（NuGet 套件授權聲明清單）及各元件完整授權文字。