想要加速生產力嗎？一起來製作自己的 Wox Plugin 吧！

㊣港都🦭豹哥㊣

Published in

新加坡商鈦坦科技

13 min readDec 21, 2023

近幾年來資訊產業蓬勃發展，各行各業也順著浪潮開始運用各種好用的工具來增加生產力，豹哥身為一個需要長期使用電腦的工程師，手上有些小工具也是合情合理的吧！😎

俗話說：「工欲善其事，必先利其器」，今天，就讓豹哥來為大家介紹一款名叫 “Wox” 的 Windows 免費桌面搜索工具，且會實際跟大家分享如何製作自己的 plugin！

目錄
1. Wox 是什麼呢？
2. 開始使用 Wox 吧！
3. 從 0 開始自己的 plugin，以查詢 ip country 為例
   ・第 1 版－快速迭代
   ・第 2 版－實際接上 API 吧
   ・第 3 版－是時候來做些 enhancement 了

Wox 是什麼呢？

“Wox” 是一款強大且免費又開源的桌面搜索工具，專為提高 Windows 操作系統用戶的效率和便利性而設計。

這款應用程式的主要特點是它的輕量級和高度可定制性，使用者可以快速開啟檔案、網頁搜索以及許多其他功能。🔍

快速搜尋本機檔案工具：僅需使用一個簡單的介面（以下簡稱 bar），就可以快速搜尋本機的檔案、文件夾、應用程式等。
支援插件：支援各種公開插件，例如翻譯、天氣預報、計算機、色票等，使用者也可以根據自己的需求新增屬於自己的功能。
快捷鍵啟動：可以設定自己喜歡的快捷鍵來啟動 Wox 的功能
搜尋網路資源：除了搜尋本地的檔案外，還可以進行網路搜索，讓使用者更快速的查詢資料。

開始使用 Wox 吧！

從 Wox 的官網上找到下載的按鈕，點擊後會到其 GitHub，可以看到目前最新版本是 v2.0.0-alpha.1，這個版本開始支援 macOS。

但官方也宣稱如果是使用 Windows 作業系統，安裝更加穩定的 v1 版本會比較好，所以我們本次將以 v1.4.1196 版本作為示範！

如附圖，除了安裝 Wox 外，也要一併安裝 Everything 唷！

安裝完畢後，即可開啟使用。在 Windows 的作業系統下，預設啟動 Wox 的 Hotkey 是 Alt + Space，這些設定都可以在 Wox 的設定視窗中查看或調整！

切換到 Plugin（插件）的分頁後，就可以看到預設已經安裝過的插件，也可以透過連結到官網上查找其他的開源插件，點選進各個插件後，就會看到該如何使用的教學！

讓我們來試試看簡單的網頁搜尋，裡用 Alt + Space 叫出 Wox 的 bar 後輸入 g news，並直接 enter，是不是就開啟瀏覽器並查詢 news 了呢！

從 0 開始自己的 plugin，以查詢 ip country 為例

第 1 版－快速迭代

🌟在開始開發時，可以先想想以下幾個問題，這會幫助釐清自己的思緒🌟

要做什麼樣的功能？
可以更快速地利用 ip address 知道對應的 country code, ISP 等資訊
為什麼會想要做呢？
因為每次需要資訊時都要透過網路資源或使用內部系統來查詢，想要更快速地獲得資訊，以增加 DevX
需要哪些資源來達成？
要有一個 GET 的 API 可以 call，並取得該 ip 詳細的資訊
這個功能要怎麼使用呢？
當開啟 Wox 後，能夠在 bar 裡輸入以下舉例，就會顯示資訊
ip → 觸發的關鍵字
210.121.164.67 → 查詢的 ip

ip 210.121.164.67

Wox support C# 以及 Python 來撰寫 plugin，今天我們會以 C# 作為範例！

首先，開啟一個 .net framework 的專案（class library），要特別注意的是目前 Wox 並不 support .net core 的框架，如果選錯了會導致後面步驟無法順利進行🙅

專案建立後，開啟 Nuget management (Alt + 7) 並安裝 wox.plugin

再來就是為你的 class 取一個好懂的名字－IpInformation

在 IpInformation 實作 IPlugin 這個套件的介面，可以看到有 Init 以及 Query 兩個方法

Init
可以想像成套件的初始化，例如：要載入或讀取檔案、建立 DB 連線…等
Query
輸入值時要呈現回傳結果的方法，回傳的型別為 Result 的 List，所以結果可以出現多個， Result 物件裡常用的 property 有 Title, SubTitle, IcoPath, Action 等

以我們這次的 case 並不需要做前置作業，所以 Init 方法可以留空（不可以留 NotImplementedException 唷🤣）

Query 的部分可以先直接 hard code 以下程式碼，先 end to end 的讓 plugin 可以運作

return new List<Result>()
{
    new Result
    {
        Title = "Country Code is KR",
        SubTitle = "haha result 1",
        Action = context => true,
    },
    new Result
    {
        Title = "City is Gwangmyeong",
        SubTitle = "haha result 2",
        Action = context => true,
    },
};

程式碼完成後，就可以建置（Build）一下這個專案，並在專案的 \bin\Debug 路徑下找到此專案的 dll 檔

開啟一個新資料夾，將此 dll 檔複製一份過去，並新增一個 package.json 的檔案（命名一定要是這個唷！）

檔案的內容如下，ID 的部分可以用 GUID 生成器產生一組不重複的 value，ExcuteFileName 也要取代成自己專案的 dll 檔名唷

{
  "ID": "_{unique value}_",
  "ActionKeyword": "ip", 
  "Name": "Ip Information",
  "Description": "A simple plugin to search ip information",
  "Author": "Angela",
  "Version": "1.0.0",
  "Language": "csharp",
  "Website": "your website~~",
  "IcoPath": "app.png",
  "ExecuteFileName": "_{your project}_.dll"
}

此時的資料夾會有 dll & plugin.json 兩個檔案，將其一同打包壓縮，並修改副檔名為 .wox

將 wox 檔丟到 wox 的 bar 中，即可以看到彈窗的提示詢問是否要 “安裝” 這個 plugin，也會附上剛剛在 package.json 檔案中的資訊

安裝後會需要重新啟動，啟動後就可以測試囉🤩

第 2 版－實際接上 API 吧

第 1 版因為是 hard code 的關係，所以無論輸入什麼關鍵字，都會出現那兩個 result

以豹哥的 case，公司內部是有自己的 geo ip service 可以用來完成這個需求，但這個 API 並沒有對外公開😅

所以豹哥就從網路上找到一個公開、免費的 API 資源給大家參考！只要將 ip 寫入 url 的 path 即可回傳 json 格式的 response，包含 country code, city, isp…等

http://ip-api.com/json/210.121.164.67

也因為我們需要 call API 以及接收 json 格式的回傳值，所以我們要在專案中裝入以下兩個 Nuget Package：

HttpClient → System.Net.Http
JsonConvert → Newtonsoft.Json => 也可以用原生 System.text的

裝完套件後，就可以將剛剛 hard code 的內容改成使用 http client 來呼叫 API

public List<Result> Query(Query query)
{
    var httpClient = new HttpClient();
    var httpResponseMessage = httpClient.GetAsync($"http://ip-api.com/json/{query.Search}").GetAwaiter()
        .GetResult();
    var readAsStringAsync = httpResponseMessage.Content.ReadAsStringAsync().GetAwaiter().GetResult();
    var ip = JsonConvert.DeserializeObject<Ip>(readAsStringAsync);

    return new List<Result>()
    {
        new Result
        {
            Title = $"Country Code is {ip.CountryCode}",
            SubTitle = "click to copy",
            Action = context => true,
        },
        new Result
        {
            Title = $"City is {ip.City}",
            SubTitle = "click to copy",
            Action = context => true,
        },
    };
}

public class Ip
{
    public string Status { get; set; }
    public string Country { get; set; }
    public string CountryCode { get; set; }
    public string City { get; set; }
    public string Isp { get; set; }
}

這邊可以看到 Query 這個物件裡有幾個可以用的 property，以下為他們的區別，就可以看自己需要什麼來取用對應的參數💪

以此段指令作為舉例：ip qq 123.123.123.123

Search：整段搜尋條件，範例為 → qq 123.123.123.123
First Search：第一段搜尋條件，範例為 → qq
Second Search：第二段搜尋條件，範例為 → 123.123.123.123
Action Key：觸發的指令，範例為 → ip

程式碼更新完後，一樣需要重新建置（Build）專案，並把所有相關的 dll 檔放入待打包清單，再來就是要有好習慣的去更新 package.json 裡的版本號！

一切就緒後就可以打包壓縮放入 Wox 的 bar 中，可以看到彈窗提示詢問是否要 “更新” 這個 plugin，並附上更改後的版本號

重啟後就可以進行測試囉！這次可以用不同的 ip 來進行查詢了！

但是 result 按下去並沒有像提示字所說的 copy 阿😭，那就前往第三版囉！

第 3 版－是時候來做些 enhancement 了

在第 2 版完成後，其實一開始設定的目標－「獲取 ip 的資訊」已經達標
但我們可以透過以下幾個 enhancement 讓這個 plugin 更好用、更好看！

Copy result 的結果
換掉 plugin 的 icon
換掉 result 的 icon

Copy result 的結果

為了達到這個效果，我們需要在專案中裝入此 Nuget Package－TextCopy，並在 result 的 Action property 中調整成以下

Action = (context =>
{
 ClipboardService.SetText($"{ip.CountryCode}");
 return true;
})

再來就是 icon 的調整，如果沒有特別設定的話，預設就會是紅色的 Wox icon

換掉 plugin & result 的 icon

在 Wox setting plugin 區塊中的左欄列表即是 plugin icon

若要更改此 icon 則必須在 plugin.json 檔裡的 IcoPath 進行設定，放上你的圖片路徑。

而 result 的 icon 也可以調整，方式是設定在程式碼裡 result 物件的 IcoPath

🌟不管是調整哪一種 icon，都要記得把圖片檔一起打包壓縮🌟，才不會找不到路徑，出現預設的紅色 Wox icon

接著就按照前面所教的步驟，重新建置專案後打包壓縮並更新回 wox，即可擁有 copy 的功能，且 icon 也都變漂亮啦！

經過以上步驟，相信大家都已經完成自己的第一個 Wox plugin 了！

也期待大家可以透過這個小工具來 enhance DevX，歡迎在底下留言跟我們分享好用的 Wox plugin 🤩

豹哥手把手教學我們下次見！💖

延伸閱讀｜鈦坦科技高雄團隊 ㊣港都🦭豹哥㊣ 的其他文章

解放你的雙手：SCSS 編譯成 CSS 自動化
 Practice makes perfect：CKAD 考取之路經驗分享
 工程師這樣開讀書會：The Clean Coder 共讀筆記

📢【鈦坦熱烈徵才中】
在鈦坦沒有Boss，但要有自組織的Guts ❗❗
想要投入 #彈性工時 #自主升遷 #薪資透明的工作文化 ❓ 還有～～豐富的內外訓教育課程隨你申請、專為敏捷團隊設計的開放式辦公空間、上班隨時前往酒吧暢飲放鬆一下…
🙋‍♂️ 職缺看這邊～
👉 https://gotica.io/鈦坦職缺/Blog