在 kintone 系統中，我們可以依照使用者需求，透過 JavaScript 客製化擴充應用程式的功能。不過，當某些功能需要套用在多個應用程式中時，若每次都逐一開發並嵌入程式碼，不僅繁瑣，也不利於後續維護。為了解決這個問題，kintone 提供了一種模組化的方式──將客製化程式碼打包成「外掛」，讓使用者能夠輕鬆地在不同應用程式間套用同一組功能。

本系列文章將帶你一步步認識 kintone 外掛的開發流程，從基本架構到實作，以及官方提供之開發套件介紹等。本篇作為系列的開端，將介紹 kintone 外掛的基本結構與組成檔案，為日後的開發打下基礎。

什麼是 kintone 外掛？

kintone 外掛是一種可以打包並上傳至 kintone 的擴充模組，讓你能夠：

• 在應用程式中插入 JavaScript / CSS 程式碼
• 提供使用者介面來設定外掛行為（如選擇欄位、設定參數）
• 將相同功能輕鬆套用到多個應用程式中

換句話說，外掛是一種可調設定，且可在多個應用程式中重複使用的客製功能。

外掛的基本檔案構成

一個 kintone 外掛實際上是一個 zip 壓縮檔，裡面包含了以下幾個必要檔案與資料夾：

plugin/
├── js/                       
│   ├── config.js             // 外掛設定畫面的程式碼
│   ├── desktop.js            // 反映於桌面版的客製化程式碼
│   └── mobile.js             // 反映於手機版的客製化程式碼
├── html/                     
│   └── config.html           // 外掛設定畫面的 HTML 結構
├── css/                      // CSS 樣式檔
│   └── config.css            
│   └── desktop.css           
│   └── mobile.css            
├── image/                   
│   └── icon.png              // 外掛的圖示
└── manifest.json             // 外掛設定的中樞，定義所有檔案與基本資訊

桌面版/手機版的 JavaScript

反映在應用程式中的程式碼（主要功能）。

• 桌面版/手機版可擇一使用，也可以同時支援。
• 在設定畫面所使用的 JavaScript 檔案中，若使用「儲存外掛設定資訊的 API」來儲存設定內容，則可透過「取得外掛設定資訊的 API」來讀取這些設定值。此時所需的外掛ID，會透過變數 kintone.$PLUGIN_ID 提供。（外掛ID是在建立外掛時，系統為每一個外掛唯一分配的 32 位元字串。例如：faabchdodajloackbgnipilddblmkejp）
• 檔案大小上限為 20MB。

外掛ID的參照範例

當一個應用程式中使用了多個外掛時，kintone.$PLUGIN_ID 可能會被多次賦值。
因此，建議使用以下的立即執行函式（IIFE）來補捉並使用當下的外掛 ID：

((PLUGIN_ID) => {
  kintone.plugin.app.getConfig(PLUGIN_ID);
})(kintone.$PLUGIN_ID);

設定畫面用的 JavaScript

在使用者開啟外掛設定畫面時執行的 JavaScript。

• 此檔案為可選項目。
• 可透過「儲存外掛設定資訊的 API」來儲存外掛的設定值。取得外掛ID的方式同「桌面版/手機版的 JavaScript」中的說明。
• 檔案大小上限為 20MB。

設定畫面用的 HTML

構成設定畫面用的 HTML。(反映於下圖紅框處)

• 此檔案為可選項目。
• 檔案大小上限為 64KB。

桌面版/手機版/設定畫面用的 CSS

• 皆為可選項目。
• 檔案大小上限為 20MB。

外掛圖示檔

• 必須項目。
• 支援圖檔格式：png／jpg／gif／bmp。
• 檔案大小上限為 20MB。

manifest.json

這是構成 kintone 外掛最重要的一個檔案，可以說是外掛的「組裝說明書」。我們必須透過這個檔案來定義外掛名稱、版本、描述、圖示、使用的檔案清單、必須設定的參數等。例如：

{
  "manifest_version": 1,
  "version": 1,
  "type": "APP",
  "name": {
    "ja": "サンプルプラグイン",
    "en": "sample plugin",
    "zh-TW": "範例外掛"
  },
  "description": {
    "ja": "これはサンプルプラグインです。",
    "en": "This is sample plugin.",
    "zh-TW": "這是一個範例外掛"
  },
  "icon": "image/icon.png",
  "desktop": {
    "js": ["js/desktop.js"],
    "css": ["css/desktop.css"]
  },
  "mobile": {
    "js": ["js/mobile.js"],
    "css": ["css/mobile.css"]
  },
  "config": {
    "html": "html/config.html",
    "js": ["js/config.js"],
    "css": ["css/config.css"]
  }
}

各參數的詳細說明如下：

可指定的語系（Locale）

在設定語系時，可以使用以下語言代碼：

• ja：日文
• en：英文
• zh：中文（簡體）
• zh-TW：中文（繁體）
• es：西班牙文
• pt-BR：葡萄牙文（巴西）
• th：泰文

🔗 官方文件連結：kintoneプラグイン開発手順 - マニフェストファイルのフォーマット

使用 plugin-packer 打包外掛

有了構成 kintone 外掛所需的檔案後，還需要透過 plugin-packer 這個工具，將其打包成正式的外掛檔案。你可以使用 npm 在本地安裝這個套件，也可以使用 網頁版 plugin-packer。

在本地安裝 plugin-packer 套件

執行以下指令可將此套件安裝至全域環境：

npm install -g @kintone/plugin-packer

也可以安裝在你的專案中作為開發依賴：

cd [你的專案資料夾]
npm install -D @kintone/plugin-packer

打包步驟

1. 將外掛構成檔案集中到 src 資料夾中。範例如下：

project-root/                 // 專案根目錄
├── src/                      // 將需打包的檔案集中在此資料夾下
│   ├── js/                   
│   │   ├── config.js         // 外掛設定畫面的程式碼
│   │   ├── desktop.js        // 反映於桌面版的客製化程式碼
│   │   └── mobile.js         // 反映於手機版的客製化程式碼
│   ├── html/                 
│   │   └── config.html       // 外掛設定畫面的 HTML 結構
│   ├── css/                  // CSS 樣式檔
│   │   ├── config.css        
│   │   ├── desktop.css       
│   │   └── mobile.css        
│   ├── image/                
│   │   └── icon.png          // 外掛的圖示
│   └── manifest.json         // 外掛設定的中樞，定義所有檔案與基本資訊
└── package.json

2. 回到根目錄，執行打包指令：

若套件安裝於全域環境：

cd project-root
kintone-plugin-packer src

若套件安裝於專案中：

npx kintone-plugin-packer src

執行後，會在根目錄產生打包完成的外掛 zip 檔 plugin.zip，以及密鑰檔 [外掛ID].ppk。

若希望指定輸出位置與 zip 檔名稱，可以加入 --out 選項，例如：

kintone-plugin-packer --out dist/new-plugin.zip src

這樣會將打包檔輸出至 dist 資料夾，並命名為 new-plugin.zip。

🌟 重要！密鑰 ppk 檔說明 🌟

密鑰 ppk 檔是外掛的「身分證」。未來若要更新此外掛，必須使用當初產生的 ppk 檔重新打包，才能維持相同的外掛 ID。請務必妥善保存此檔案。

3. 若要重新打包外掛（更新外掛版本）：

當你修改程式碼後，若想保留原本的外掛 ID，可使用第一次打包時產生的 ppk 檔，搭配 --ppk 選項：

kintone-plugin-packer --ppk PLUGIN_ID.ppk src

若未指定密鑰，則會產生一個新的外掛（新的 ID），kintone 將視為不同外掛，而非原本的更新版。

使用網頁版 plugin-packer 打包

🔗 網頁版 plugin-packer

將欲打包的 src 資料夾拖曳至左側區域，點擊下方藍色按鈕「作成する」即可進行打包。
若要重新打包，請在右側區域上傳先前產出的密鑰 ppk 檔。

※ 若使用非 Chrome 或 Firefox 瀏覽器，請先將 src 資料夾壓縮成 zip 再進行上傳。

以上就是 kintone 外掛基本架構的介紹。
在下一篇文章中，我們將透過一個簡單的實作範例，從零開始開發並打包出一個可以實際運作的 kintone 外掛，一步步帶你進入實戰開發流程！🚀