啟用 ONLYOFFICE 桌面插件開發和調試

在 ONLYOFFICE 桌面編輯器中，您無需單獨啟用外掛程式開發開關。創建插件後，.plugin透過插件管理器安裝其軟體包，然後在需要調試工具時啟動桌面應用程式即可--ascdesktop-support-debug-info。桌面編輯器和 Web 編輯器使用不同的載入流程，因此請先依照下列桌面版的工作流程進行操作。

準備一個小型插件項目

這些說明適用於 Windows、macOS 和 Linux 上的 ONLYOFFICE 桌面編輯器。請使用最新版本的桌面版安裝程式和用於純文字檔案的程式碼編輯器。官方文件將手動插件安裝和開發者調試視為兩個獨立的功能；開發和測試本地插件無需使用插件市場。「Hello World」範例是一個很好的初步檢查，因為它能將插件載入與更複雜的服務隔離。

1. 建立來源資料夾

建立一個名為 `<folder_name>` 的資料夾hello-world-plugin。新增config.json清單檔案和index.html入口點。icon.png如果清單檔案中引用了圖像，則可以選擇性地新增圖像。將該資料夾放在已安裝應用程式目錄之外，以防止軟體更新覆蓋您的工作文件。

Windows 檔案總管顯示 hello-world-plugin 開發資料夾中的 config.json、index.html 和 icon.png 文件 — 將外掛程式清單檔案及其入口 HTML 檔案放在同一個開發資料夾中；本機圖示是可選的。

2. 定義清單並產生您自己的 GUID

清單檔案告訴 ONLYOFFICE 要載入哪個 HTML 檔案以及哪些編輯器可以執行該外掛程式。以下範例支援文件編輯器。安裝前，請將範例 GUID 替換為新產生的 UUID：New-Guid在 Windows PowerShell 或uuidgenmacOS/Linux 上執行，然後將值格式化為asc.{YOUR-UUID}。每個不同的插件都需要自己的識別碼。

{
  "name": "Hello World",
  "guid": "asc.{12345678-1234-1234-1234-1234567890AB}",
  "version": "1.0.0",
  "variations": [{
    "url": "index.html",
    "icons": ["icon.png"],
    "isViewer": false,
    "EditorsSupport": ["word"]
  }]
}

請使用有效的 JSON：不要有尾隨逗號，花括號要匹配，並且每個引用的入口點或圖示都必須指向一個實際的檔案。對於電子表格或簡報插件，請使用相應的值，EditorsSupport不要想當然地認為文件插件會出現在所有地方。請將結構與官方的Hello World 快速入門範例進行比較。

程式碼編輯器顯示插件的 config.json 文件，其中包含名稱、GUID、版本、入口點 URL 和文字編輯器支援資訊。 — config.json 清單檔案用於標識外掛程式並將其限制為它支援的編輯器。

3. 實現入口點

在頁面中index.html，載入 ONLYOFFICE 外掛程式 API 庫，新增一個按鈕，並讓該按鈕呼叫對應的 API window.Asc.plugin.executeMethod("PasteText", ["Hello World!"])。廠商提供的快速入門範例提供了完整的 HTML 程式碼和函式庫 URL；複製此範例比猜測初始化或 API 語法更安全。將檔案儲存為 UTF-8 編碼。如果您打算離線工作，請記住，從線上 URL 匯入外掛程式庫或其他資源的頁面仍然需要載入這些資源。

一個程式碼編輯器，顯示一個 index.html 入口點，其中包含一個「Hello World」按鈕和一個 PasteText 插件 API 呼叫 — 入口檔案包含插件運行時編輯器使用的介面和 JavaScript 呼叫。

安裝並運行您的開發插件

4. 建構 .plugin 歸檔文件

選擇來源資料夾中的文件，將它們壓縮成 ZIP 壓縮包，並將 ZIP 檔案的副檔名從.zip.zip更改為 .zip .plugin。壓縮包根目錄應包含 .zipconfig.json和index.html.zip，不應包含第二個hello-world-plugin子目錄。在 Windows 系統中，請在檔案總管中啟用檔案副檔名，以免意外建立.zip 檔案hello-world.plugin.zip。官方桌面編輯器安裝說明明確支援在不連接 Marketplace 的情況下進行手動安裝。

在 Windows 檔案總管中，插件來源檔案已被選取進行 ZIP 打包，旁邊是 hello-world.plugin 壓縮套件。 — 請先歸檔插件資料夾的內容，而不是其所在的資料夾，然後再將 ZIP 檔案重新命名為 .plugin 副檔名。

5. 從插件管理器導入軟體包

在 ONLYOFFICE 桌面編輯器中開啟一個可編輯文件。選擇“插件”>“插件管理器”>“我的插件”>“手動安裝插件”。管理器介面可能因版本而異，但此操作是官方記錄的手動安裝路徑，並非 Marketplace 中的單獨開發者 URL 設定。

ONLYOFFICE桌面編輯器外掛程式管理器在「我的插件」中顯示「手動安裝插件」操作 — 在文件中，開啟“插件”，然後開啟“插件管理器”，切換到“我的插件”即可進行手動安裝。

6. 選擇檔案並檢查其選單項

在檔案對話方塊中選擇您的hello-world.plugin壓縮包並打開它。安裝的插件應該會出現在「插件」標籤下。如果外掛程式不見了，請在變更應用程式設定之前檢查清單檔案、GUID、支援的編輯器類型和壓縮包根目錄。如果選單沒有立即刷新，請嘗試在安裝後重新開啟文件。

在 Windows 系統中，開啟對話框，選擇「插件檔案」篩選器，找到 hello-world.plugin 套件。 — 在檔案選擇對話方塊中選擇 .plugin 存檔；不要選擇原始來源資料夾。

7. 在一次性文件中測試插件

開啟一個空白測試文檔，從「插件」標籤啟動Hello World插件，然後點擊其按鈕。確認文件中出現「Hello World!」字樣。這不僅檢查了插件的安裝情況，還確認了插件介面已加載，並且其編輯器 API 呼叫已成功應用於文件。請勿在不可替換的文件上測試會修改內容的插件。

ONLYOFFICE 文字處理器，帶有 Hello World 外掛程式面板，文件中可以看到 Hello World 文字。 — 在一次性文件中執行已安裝的插件，並檢查產生的文件內容。

啟用插件開發調試功能

8. 使用調試標誌重新啟動桌面編輯器

完全關閉 ONLYOFFICE 桌面編輯器，然後使用官方調試標誌從終端啟動應用程式。請使用適用於您的作業系統和安裝位置的命令：

Windows 命令提示字元： "%ProgramFiles%\ONLYOFFICE\DesktopEditors\DesktopEditors" --ascdesktop-support-debug-info
Linux（標準軟體包位置）： "/opt/onlyoffice/desktopeditors/DesktopEditors" --ascdesktop-support-debug-info
macOS： "/Applications/ONLYOFFICE.app/Contents/MacOS/ONLYOFFICE" --ascdesktop-support-debug-info

上述 Windows 命令使用的是命令提示字元變數擴展，而非 PowerShell 語法；在 PowerShell 中，請使用執行檔的完整路徑呼叫它。如果您的應用程式安裝在非標準位置，請替換為實際的可執行檔路徑。您也可以將該標誌新增至 Windows 桌面捷徑的「目標」欄位。有關平台詳細信息，請參閱 ONLYOFFICE 的桌面調試模式命令。

文件開啟後，點擊編輯區域並按F1 鍵，或右鍵點擊可編輯的工具列欄位並選擇「檢查元素」。在開發者工具中，選擇插件 iframe 以檢查插件介面程式碼和日誌。傳遞給 iframe 的程式碼會callCommand在frameEditor上下文中運行，因此必要時需要切換框架。插件調試參考文件解釋了這種差異以及如何使用斷點。偵錯可能會暴露文件內容和執行時間細節；未經檢查，請勿共用原始日誌。

開發者工具控制台，選取一個插件 iframe，並顯示一個範例初始化日誌條目 — 啟用偵錯後，在開發者工具中檢查相關的插件 iframe；此處的控制台訊息具有指示意義。

縮短編輯測試週期，無需修改內建插件

手動安裝後，ONLYOFFICE 會將外掛程式複製到使用者設定檔下的以 GUID 命名的目錄中。文件中所列的位置分別對應%LOCALAPPDATA%\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\Windows、~/Library/Application Support/asc.onlyoffice.ONLYOFFICE/data/sdkjs-plugins/macOS 和~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/Linux 系統。此 GUID 命名的資料夾省略了清單檔案中使用的前導字元asc.。

為避免每次變更都建立新的歸檔文件，開發者可以關閉應用，將已安裝的插件資料夾替換為指向工作來源資料夾的符號鏈接，然後在編輯後重新開啟文件。此操作為可選步驟，具體連結命令因作業系統而異。請在執行此操作之前遵循官方桌面開發指南。切勿替換捆綁/預設插件資料夾或修改 macOS 應用包：供應商警告稱，移除預設插件可能會破壞包的完整性並導致崩潰。

驗證開發環境

三個檢查項目表明工作流程已準備就緒：自訂插件出現在「插件」下，「Hello World」測試會在新文件中插入文本，並且使用調試標誌啟動後開發者工具會開啟。如果介面空白或安裝失敗，請確認清單檔案解析為 JSON 格式，GUID 以 `<your_plugin_name>` 開頭asc.，index.html位於宣告的相對路徑，並且所有必要資源都已存在。官方插件錯誤指南涵蓋了這些常見故障。已安裝的插件並不能保證其實現的每個功能都能正常運作；每次程式碼更改後都應重複上述檢查。