如何使用 @wordpress/scripts 向 Gutenberg 編輯器添加按鈕

大約一年半前，Antonio 寫了這篇博文，解釋了我們在將插件適應新的 WordPress 塊編輯器時遇到的困難之一。 他的教程的結果是這樣的：

幸運或不幸的是，古騰堡在這一年半中發生了很大的變化。 開發堆棧一直在擴展和改進，插件和主題開發人員必須接受和適應新技術。 我們中那些也寫下我們的經驗並分享我們所學知識的人現在“被迫”更新我們的教程，以便您可以跟上最新情況。 但我們對此感到高興！

幾週前，我們的一位讀者 Ivan 在 Antonio 的教程中給我們留言尋求幫助。 顯然他無法實現安東尼奧的插件。 而且，老實說，這並不讓我感到驚訝，因為最近情況發生了很大變化。 因此，為了幫助 Ivan 和所有閱讀我們並希望繼續了解 WordPress 的人，讓我們重新創建有關如何利用 WordPress 為我們提供的所有新工具向 Gutenberg 塊編輯器添加按鈕的教程！

創建插件

我們必須做的第一件事是創建一個 WordPress 插件。 這很簡單。 基本上，我們所要做的就是在wp-content/plugins中創建一個文件夾，其名稱是我們想要為我們的插件提供的名稱（例如， gutenberg-button ），並在其中創建一個具有相同名稱和一個.php擴展。 然後在您的插件文件中鍵入以下代碼：

現在，讓我們仔細看看前面的代碼片段做了什麼：

• 首先我們打開一個<?php標籤。 這裡沒有驚喜。
• 接下來，在這個主文件中，我們添加一個多行註釋。 註釋包括幾行“鍵/值”對。 例如，我們看到我們如何指定插件的名稱 ( Plugin Name )、它的版本 ( Version ) 或作者的姓名 ( Author )。 所有這些信息都將在 WordPress 的插件部分中可見。
• 最後，我們添加一些樣板代碼：
  • 我們指定一個namespace （我們在這裡討論了命名空間），
  • 我們確保，如果文件運行，它作為 WordPress 的一部分運行，並且
  • 我們定義了一些關於插件的常量（稍後會有所幫助）。

完成所有這些後，如果我們轉到 WordPress 的插件屏幕，我們將看到Gutenberg 按鈕在那裡：

我們激活它，然後……瞧！ 當然，它不會做任何事情，但它已經存在了。

JavaScript 插件開發

如今，WordPress 開發人員必須精通 JavaScript。 我猜，這就是古騰堡處於核心地位的後果之一。 本教程也不例外。

準備環境

如果我們想向 Gutenberg 界面添加一個新按鈕，我們必須在 JavaScript 中編寫此功能。 因此，讓我們在插件中準備 JavaScript 開發環境。 為此，只需從命令行運行以下命令（這樣做時請確保您位於wp-content/plugins/gutenberg-button ）：

 npm init

並按照說明進行操作：

 This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (gutenberg-button) version: (1.0.0) description: Adding a formatting button in Gutenberg. entry point: (index.js) ...

此過程的結果是一個package.json文件。 正如您稍後將看到的，此文件在未來將非常有用。

正如我已經在這篇文章的標題中透露的那樣，我們將使用@wordpress/scripts來創建我們的插件。 因此，讓我們通過運行以下命令將其添加為依賴項：

 npm install --save-dev @wordpress/scripts

該命令將在我們的插件中（在node_modules下）下載一堆依賴項，並將修改我們的package.json以便很明顯@wordpress/scripts現在是一個開發依賴項。

如果你看一下這個包的文檔，你會發現它包含很多用於構建、驗證語法、格式化代碼等的腳本：

 { "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format:js": "wp-scripts format-js", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" } }

所以讓我們編輯我們的package.json文件，以便"scripts"部分包含所有推薦的命令。

如何驗證一切正常……

讓我們在項目的根目錄下創建一個src文件夾，並在其中添加一個index.js文件。 這將是我們插件的主要 JavaScript 文件，並將包含您的所有代碼（然後您可以隨意組織代碼，只要主文件是src/index.js ）。

讓我們通過添加以下語句index.js來測試事情是否按預期工作：

 console.log( 'Hi!' );

並使用npm run build項目。 這會將您的代碼轉換為瀏覽器可以運行的內容（現在實際上不需要，但只需幾分鐘）並在build文件夾中生成一個新腳本。

我們現在要做的就是告訴 WordPress 這個腳本存在，以便它可以加載它。 為此，只需打開插件的主文件 ( gutenberg-button.php ) 並在末尾添加以下行：

 function enqueue_script() { wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', [], GUTENBERG_BUTTON_VERSION ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

如果您注意，您會看到我們只是告訴 WordPress 將我們的新腳本/build/index.js作為塊編輯器資源排入隊列。 這樣，當用戶訪問塊編輯器時，我們的腳本將成為編輯器將包含的資產的一部分。

所以讓我們看看這個。 轉到您的 WordPress 儀表板，編輯帖子並查看瀏覽器的 JavaScript 控制台。 如果事情按預期進行，您應該會看到“嗨！” 寫在控制台上：

複製我們的教程以向 Gutenberg 添加按鈕

好的，既然我們已經看到我們可以編寫 JavaScript 代碼並npm run build成我們的瀏覽器可以理解的內容，那麼是時候複製 Antonio 的教程了。 親愛的讀者，這非常簡單。

打開src/index.js文件並將之前的console.log語句替換為以下內容：

如您所見，這與 Antonio 幾個月前編寫的代碼幾乎相同。 主要區別在於我們不再使用全局變量wp來訪問 Gutenberg 的函數和組件。 相反，我們現在依賴於import語句。 但除此之外，它幾乎是一樣的。

編寫好代碼後，只需npm run build即可！ 您現在在 Gutenberg 中擁有按鈕：

讓我們通過選擇一些文本並單擊按鈕來確保它有效：

你去吧，我們看到文本再次出現在控制台中！

關於依賴關係的最後說明......

如果您查看build文件夾，您會看到@wordpress/scripts不僅創建了一個index.js文件，而且還有一個index.asset.php文件。 該文件定義了一個具有兩個屬性的小對象：

• 我們的插件所需的依賴項列表（即 WordPress 腳本）
• 構建版本

如果我們想確保腳本能夠正常運行，我們可以（並且應該）在 WordPress 中對我們的腳本進行排隊時使用這兩個屬性。 為此，只需返回gutenberg-button.php並更改它，如下所示：

 function enqueue_script() { $asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php'; wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', $asset['dependencies'], $asset['version'] ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

只需使用include語句加載index.asset.php中的對象，並將我們擁有的依賴項列表 ( [] ) 替換為實際依賴項，並使用內部版本號作為插件版本。

結論

創建真正有用的 WordPress 插件很棘手。 您必須充分了解 JavaScript 的工作原理並熟悉 WordPress 擁有的所有資源。 但是多虧了@wordpress/scripts包，準備 JavaScript 開發環境和構建可以在 WordPress 中運行的 JavaScript 插件比以往任何時候都容易。

我希望你喜歡今天的帖子。 而且，與往常一樣，如果您在任何時候遇到困難或有任何疑問，請發表評論，我們會為您提供幫助。

哦，順便說一下，這裡是項目的鏈接，如果您願意，可以下載和測試。 只需克隆項目， npm install所有依賴項， npm run build它並試一試！

Ashim D'Silva 在 Unsplash 上的特色圖片。