XD Plugin 入門 - 建立與 UI 介面篇

XD Plugin 入門 - 建立與 UI 介面篇

上禮拜公司的設計師和我說,他想要有一個可以拖曳 icon 的 XD 插件,然後說 XD 文件上說只要會 HTML, CSS 和 JS 就可以做了,最後烙下一句狠話:『這個你不會做的話,那還說你是前端工程師?』聽到這句話,燃起我的熊熊鬥志,趁著清明連假、防疫之餘,就找個時間研究一下~

(好啦 其實只是一直覺得很想玩玩看啦

看完此篇你會了解到:

  • XD 插件的開發檔案配置
  • 插件必須包含的檔案
  • 插件分為哪兩種 UI,分別該如何啟用與呈現
  • 如何 debug

有做過 chrome extension 的話,應該都知道插件會有一些基本需要的檔案,而 XD 插件也是,主要會有 main.js 和 manifest.json

官方也有提供基本的範例程式碼,可以先下載此範例了解整個開發的流程與方式。
https://github.com/AdobeXD/Plugin-Samples/tree/master/quick-start-panel

開發的檔案位置

在 XD 中有提供一個 develop 資料夾,可以用來放置與讀取開發中的插件
develop 資料夾可以從 XD 的 Plugins > Developments > Show Develop Folder 直接打開

打開後就可以將剛剛的檔案,或是自己建立包括 main.js 和 manifest.json 的資料夾放進去,接著只要 Reload Plugins 就可以在 XD 中開啟這個插件了

插件必須包含的兩個檔案與 UI 配置

插件中必須包括 manifest.json 和 main.js,透過這兩個的相互配置,就可以成功在 XD 開啟對應的 UI 了,以上面提供的範例為例,這個插件主要的功能是在 XD 中開啟 panel,並可以透過 panel 中的輸入欄位去增大 XD 的圖層。接下來就一一說明主要檔案的配置,以及 UI 分為哪兩種吧!

manifest.json

第一層的數據會包含:

  • id:這個 id 會在 Adobe I/O Console 上獲得唯一值。
  • name:要顯示的插件名稱
  • version:版本號
  • icons:icon 需要提供兩種尺寸,分別是 24 和 48
  • host:host 須包括兩個內容,分別為 app 和 minVersion
    • app 必為 “XD”
    • minVersion 為最小版本,目前支援 panel 的最小版本是 21.0
  • uiEntryPoints:用來定義 UI 入口點。分為 panel 與 menu 兩種

Panel

Panel 是側邊開啟的 UI。如下圖

若是要使用 panel,在 manifest.json 的 uiEntryPoints 就會這樣寫

1
2
3
4
5
6
7
"uiEntryPoints": [
{
"type": "panel",
"label": "Enlarge a Rectangle",
"panelId": "enlargeRectangle"
}
]

這邊的 label 就是識別用的,如果 uiEntryPoints 有兩個以上,就會出現選單,此時就可以透過 label 來識別選擇要用的功能。
而 panelId 是比較重要的,他會對應到 main.js 中 module.exports 的程式碼 (如下)。

1
2
3
4
5
6
7
8
module.exports = {
panels: {
enlargeRectangle: { // 對應 panelId
show, // main.js 中的函式
update // main.js 中的函式
}
}
};

menu 可以用來開啟 dialog。如下圖:

若是要使用 menu (dialog UI),在 manifest.json 的 uiEntryPoints 就會這樣寫

1
2
3
4
5
6
7
"uiEntryPoints": [
{
"type": "menu",
"label": "Hello World Command",
"commandId": "menuCommand"
},
]

label 同上說明是識別作用,而這邊的 commandId 也同樣是會對應到 main.js 中的 module.exports,如下:

1
2
3
4
5
module.exports = {
commands: {
menuCommand: function () {...起始要執行的內容}
}
};

上面的 commandId 會對應 commands 的內容,就像是呼叫這個函式的概念。

了解 manifest.json 的基本配置,以及可以選擇的兩種 UI 後,就可以正式進入到開發的部分。
manifest.json 完整說明

main.js

main.js 除了是寫功能的程式碼外,UI 的呈現也是都要在這邊加上,因此這裡主要是說明如何加上開啟 UI 的程式碼。

panel

前面提到 manifest.json 的 panelId 會對應到 main.js 的 exports,而對應呼叫的方法有三種,分別是 show()、hide()、update()。
show() 是必須要有的,也就是用來將 HTML 樣板加上去側邊欄。

在 main.js 中,我們可以運用 HTML 和 CSS 去定義要呈現的樣板,可參考這邊的第 5 - 39 行
最後會將定義好的樣板 return 出來,並透過 show 函式 append。

例如:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
let panel;
function create() {
const HTML = '這邊寫 HTML 標籤和 CSS 樣式'
panel = document.createElement("div");
panel.innerHTML = HTML;
return panel;
}

function show(event) {
if (!panel) event.node.appendChild(create());
}

module.exports = {
panels: {
enlargeRectangle: {
show,
}
}
};

而 dialog 的原理也和 panel 很相似,定義 HTML 樣板後可以透過 commands 來加入,若需要主動的開啟,可以加上 showModal() 的方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
let dialog;
function getDialog() {
if (dialog == null) {
dialog = document.createElement("dialog");
let form = document.createElement("form");
dialog.appendChild(form);
form.style.width = 200;
}
return dialog;
}

module.exports = {
commands: {
menuCommand: function () {
document.body.appendChild(getDialog()).showModal();
}
}
};

到這邊就可以成功使用插件來新增 UI 介面。

插件如何 debug

在 XD 的 Plugins > Developments > Developer Console 可以開啟一個用來 debug 的頁面

只要在 main.js 寫 console.log 就可以印出來囉(如下圖)

但要注意是純文字且和 chrome 檢查元素好像不太一樣,有時候印出來的都落落長,完全不知道自己要看的是在哪邊…
因此在做插件時,也需要對 XD 內本身提供的方法有一些了解,在開發時會更好上手。下一篇再繼續介紹吧!

最後也推薦一下 XD 自身有提供一大堆插件範例,在摸索的時候也可以試著下載後將檔案放到 develop 資料料中載入玩玩看。

評論

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×