透過 LibreOffice 的巨集系統在 Calc 中運行 Python

如果 Python 腳本在終端機運行，但無法讀取或修改 Calc 中開啟的電子表格，則很可能是在 LibreOffice 之外運行的。 Calc Python 巨集需要在 LibreOffice 進程內執行，LibreOffice 會提供活動文件上下文。將腳本儲存為使用者 Python 腳本資料夾中的一個模組，使用 `export` 命令匯出其函數g_exportedScripts，然後從 Calc 的巨集對話方塊啟動它。

這是與開啟的工作簿關聯的小型自動化操作的最簡單方法。 LibreOffice 目前的Python 腳本幫助文件同時介紹了進程內巨集和單獨連接的 Python 腳本；以下步驟使用的是進程內巨集方法。

為什麼普通的 Python 腳本看不到開啟的電子表格？

LibreOffice 透過全域變數將目前文件暴露給正在執行的 Python 巨集XSCRIPTCONTEXT。使用常規命令啟動的腳本python是一個獨立的進程，因此全域變數不會自動可用。它仍然可以與 LibreOffice 通信，但這需要與已執行的 Office 進程建立 UNO 連線。對於第一個宏，請在 LibreOffice 內部運行函數。

Python 巨集是.py模組中的一個函數。模組的g_exportedScripts元組告訴 LibreOffice 要在巨集列表中顯示哪些函數。這些細節在 LibreOffice 的Python 程式設計參考文件中有詳細說明。

如何在Calc中加入Python宏？

1. 找到使用者 Python 腳本資料夾

如果您希望腳本能在您使用者帳戶下的任何已開啟的 LibreOffice 文件中執行，請使用個人「我的巨集」%APPDATA%\LibreOffice\4\user\Scripts\python資料夾。 LibreOffice在 Windows、$HOME/.config/libreoffice/4/user/Scripts/pythonLinux 和 macOS 系統上都提供了該資料夾的文件。如果該Scripts/python資料夾尚不存在，請建立它們。腳本位置參考文件還解釋了其他巨集容器：應用程式巨集和嵌入在文件中的巨集。

文檔巨集儲存在特定文件中，並且僅在該文件開啟時才能存取。對於可重複使用的個人實用程序，「我的巨集」通常更易於維護。請避免修改 LibreOffice 的應用程式級巨集資料夾，因為這可能需要管理員權限。

2. 建立並匯出一個小的測試函數

打開純文字編輯器，hello_calc.py在上面的資料夾中建立文件，並新增：

def hello_calc(*args):
    doc = XSCRIPTCONTEXT.getDocument()
    sheet = doc.Sheets[0]
    sheet.getCellRangeByName("A1").setString("Hello from Python")

g_exportedScripts = (hello_calc,)

此函數取得目前與巨集呼叫關聯的文檔，選擇其第一個工作表，並在 A1 儲存格中寫入一個無害的測試字串。最後一行很重要：如果沒有導出的元組，函數可能無法作為可運行的巨集運行。請將檔案儲存為純文字格式，並使用 .txt.py副檔名，而不是富文本格式或以 .txt 結尾的檔案.py.txt。

LibreOffice 會將XSCRIPTCONTEXT變數提供給宏模組。它不會自動將該變數傳遞給程式碼導入的模組，因此請確保第一個測試程式碼是獨立的。如果您之後將可重複使用的函數拆分到其他模組中，請遵循 LibreOffice 的Python 模組導入指南。

3. 開啟一個 Calc 檔案並執行匯出的函數

1. 在 Calc 中開啟一個測試電子表格。開發過程中可以使用副本或空白工作簿。
2. 選擇“工具”>“巨集”>“運行巨集”。
3. 在庫清單中，展開「我的巨集」，選擇 Python 模組，然後hello_calc從巨集名稱中進行選擇。
4. 點擊運行。

同樣的功能也可以透過 APSO 擴充功能啟動，LibreOffice 推薦使用該擴充功能進行進程內 Python 腳本編寫，而且它還提供了一個 Python shell。對於此處所述的基本運行巨集流程，您無需使用 APSO。

如果巨集缺失或似乎沒有任何作用怎麼辦？

請依序完成以下檢查，而不是變更大範圍的安全設定：

• 模組未列出：請確認檔案位於正確的使用者Scripts/python路徑中，具有.py後綴，並且包含拼字正確的g_exportedScripts元組。重新開啟巨集對話方塊；如果 LibreOffice 仍然沒有列出新新增的文件，請關閉並重新啟動 LibreOffice，然後再次檢查。
• 缺少巨集名稱：請確保導出的元組包含函數對象，例如 `$(function_object)` (hello_calc,)。逗號使其成為一個單元素 Python 元組。
• 終端機中沒有任何顯示：當從標準巨集對話方塊執行 Python 巨集時，輸出print()不可用。上面的測試會將結果寫入 A1 儲存格，因此結果會在工作表中顯示。對於互動式調試，APSO 的 shell 會顯示輸出。
• 導入失敗：為系統 Python 安裝軟體包並不能保證 LibreOffice 的 Python 運行時能夠導入它。軟體包必須位於運行時的 Python 路徑中；官方導入指南介紹了使用者路徑和共享模組路徑。請先測試不帶可選導入的巨集。
• 出現安全性警告：請僅執行您編寫或已審核並信任的腳本。巨集安全機制旨在限制不安全程式碼的運作；請勿為了執行不熟悉的文件中的巨集而降低全域安全等級。如果您需要了解警告的具體含義，請參閱 LibreOffice 的巨集安全選項。

只有當自動化流程必須從終端、排程器或其他應用程式啟動時，才應選擇外部進程方式。 LibreOffice 要求您使用管道或套接字啟動 Office 進程，並透過其 UNO 橋接器進行連接；普通的獨立腳本與進程內 Calc 巨集並不等同。

如何驗證巨集是否運行成功？

點選「執行」後，查看第一個工作表中的 A1 儲存格。它應該包含“Hello from Python”，並且在選取 A1 時，公式欄也應該顯示相同的文字。如果儲存格內容保持不變，請確認目標工作簿已激活，並且巨集已從「我的巨集」中選取。此簡單測試成功後，請將測試程式碼替換為您的實際計算，並在工作簿副本上進行測試，然後再用於重要資料。