開始使用WordPress塊開發-css教學-PHP中文網

Getting Started With WordPress Block Development

WordPress開發目前正經歷轉型期，無論您是WordPress新手還是資深開發者，“全站編輯”（FSE）功能的引入，包括區塊編輯器（WordPress 5.0）和站點編輯器（WordPress 5.9），都顛覆了我們構建WordPress主題和插件的傳統方式。

儘管我們第一次接觸區塊編輯器已經五年了，但它的開發仍然充滿挑戰，因為文檔要么缺失，要么過時。這更多地反映了FSE功能快速迭代的現狀。

例如，2018年，CSS-tricks上曾發表過一個關於Gutenberg開發入門的系列文章。但時過境遷，雖然那種開發方式仍然有效，但已不再推薦（此外，它所基於的create-guten-block項目也不再維護）。

本文旨在幫助您開始WordPress區塊開發，並遵循當前的方法。當然，本文發布後，情況可能會發生變化。但我將嘗試關注其核心思想，因為即使工具會隨著時間推移而發展，核心概念很可能保持不變。

WordPress區塊究竟是什麼？

首先，讓我們澄清一些術語，例如“區塊”。在WordPress 5.0之前的這些功能的所有開發都使用代號“Gutenberg”（印刷術的發明者）。

從那時起，“Gutenberg”已被用來描述與區塊相關的一切，包括區塊編輯器和站點編輯器，因此它變得複雜到一些人討厭這個名字的程度。最重要的是，還有一個Gutenberg插件用於測試實驗性功能，以供將來可能包含。如果您認為將所有這些稱為“全站編輯”可以解決問題，那麼也存在一些擔憂。

因此，在本文中，當我們提到“區塊”時，指的是在WordPress區塊編輯器中創建內容的組件。區塊被插入頁面或文章中，並為特定類型的內容提供結構。 WordPress自帶了一些用於常見內容類型的“核心”區塊，例如段落、列表、圖像、視頻和音頻等等。

除了這些核心區塊外，我們還可以創建自定義區塊。這就是WordPress區塊開發的重點（還可以過濾核心區塊以修改其功能，但您可能暫時不需要）。

區塊的作用

在我們深入創建區塊之前，我們必須首先了解區塊的內部工作原理。這絕對可以節省我們以後很多麻煩。

我喜歡將區塊抽像地理解為：一個具有某些屬性（稱為屬性）的實體，代表某些內容。我知道這聽起來很模糊，但請耐心聽我解釋。區塊基本上以兩種方式表現出來：作為區塊編輯器中的圖形界面，或作為數據庫中的數據塊。

當您打開WordPress區塊編輯器並插入一個區塊（例如，Pullquote區塊）時，您會得到一個不錯的界面。您可以點擊該界面並編輯引用的文本。區塊編輯器UI右側的“設置”面板提供用於調整文本和設置區塊外觀的選項。

當您完成創建精美的引用並點擊“發布”時，整篇文章都會存儲在數據庫的wp_posts表中。由於Gutenberg，這沒有什麼新意。這就是事情一直以來的工作方式——WordPress將文章內容存儲在數據庫中的指定表中。但新的是Pullquote區塊的表示是存儲在wp_posts表的post_content字段中的內容的一部分。

這種表示是什麼樣的？讓我們來看看：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

登入後複製

看起來像普通的HTML，對吧？！用技術術語來說，這就是“序列化”的區塊。請注意HTML註釋中的JSON數據，“textAlign”：“right”。這是一個屬性——與區塊相關的屬性。

假設您關閉了區塊編輯器，然後一段時間後再次打開它。區塊編輯器將檢索相關post_content字段中的內容。然後，編輯器解析檢索到的內容，並在遇到以下內容時：

<code>...</code>

登入後複製

它會自言自語：

好吧，這看起來像一個Pullquote區塊。嗯……它也有一個屬性……我確實有一個JavaScript文件，它告訴我如何根據其屬性在編輯器中構造Pullquote區塊的圖形界面。我現在應該這樣做，以便以其全部榮耀呈現此區塊。

作為區塊開發者，您的工作是：

告訴WordPress您要註冊特定類型的區塊，以及相關細節。
向區塊編輯器提供JavaScript文件，這將幫助它在編輯器中呈現區塊，同時將其“序列化”以將其保存到數據庫中。
提供區塊正常運行所需的任何其他資源，例如樣式和字體。

需要注意的是，所有這些從序列化數據到圖形界面的轉換——反之亦然——只發生在區塊編輯器中。在前端，內容的顯示方式與存儲方式完全相同。因此，從某種意義上說，區塊是一種將數據放入數據庫的巧妙方法。

希望這能使您更清楚地了解區塊的工作原理。

區塊只是插件

區塊只是插件。好吧，從技術上講，您可以將區塊放在主題中，也可以將多個區塊放在一個插件中。但是，通常情況下，如果您想製作一個區塊，您將要製作一個插件。因此，如果您曾經創建過WordPress插件，那麼您已經部分掌握了製作WordPress區塊的方法。

但是，讓我們假設您從未設置過WordPress插件，更不用說區塊了。你甚至從哪裡開始？

設置區塊

我們已經介紹了什麼是區塊。讓我們開始設置來製作一個。

確保已安裝Node

這將使您可以訪問npm和npx命令，其中npm安裝區塊的依賴項並幫助編譯內容，而npx在不安裝軟件包的情況下運行軟件包上的命令。如果您使用的是macOS，您可能已經安裝了Node，並且可以使用nvm更新版本。如果您使用的是Windows，則需要下載並安裝Node。

創建項目文件夾

現在，您可能會遇到其他教程，它們直接跳轉到命令行並指示您安裝名為@wordpress/create-block的軟件包。此軟件包非常棒，因為它會生成一個完整的項目文件夾，其中包含開始開發所需的所有依賴項和工具。

我個人在設置自己的區塊時會採用這種方法，但請暫時容忍我一下，因為我想消除它引入的主觀內容，並僅關注基本開發環境的必需部分，以便理解。

這些是我想特別指出的文件：

readme.txt：這有點像插件目錄的正面，通常用於描述插件並提供有關用法和安裝的更多詳細信息。如果您將區塊提交到WordPress插件目錄，則此文件有助於填充插件頁面。如果您計劃為區塊插件創建GitHub存儲庫，那麼您也可以考慮使用包含相同信息的README.md文件，以便它在那裡很好地顯示。
package.json：這定義了開發所需的Node軟件包。我們將在安裝時打開它。在經典的WordPress插件開發中，您可能習慣於使用Composer和composer.json文件。這是它的等效項。
plugin.php：這是主要的插件文件，是的，它是經典的PHP！我們將在這裡放置插件標題和元數據，並使用它來註冊插件。

除了這些文件外，還有一個src目錄，它應該包含區塊的源代碼。

擁有這些文件和src目錄就足以開始了。在那組中，請注意我們實際上只需要一個文件（plugin.php）來製作插件。其餘的要么提供信息，要么用於管理開發環境。

前面提到的@wordpress/create-block軟件包為我們搭建了這些文件（以及更多）。您可以將其視為自動化工具，而不是必需品。無論如何，它確實使工作更容易，因此您可以通過運行以下命令來自由地使用它來搭建區塊：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

登入後複製

安裝區塊依賴項

假設您已準備好上一節中提到的三個文件，現在該安裝依賴項了。首先，我們需要指定我們將需要的依賴項。我們通過編輯package.json來做到這一點。使用@wordpress/create-block實用程序時，會為我們生成以下內容（添加了註釋；JSON不支持註釋，因此如果您複製代碼，請刪除註釋）：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

登入後複製

查看無註釋版本

```json { "name": "block-example", "version": "0.1.0", "description": "Example block scaffolded with Create Block tool.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "packages-update": "wp-scripts packages-update", "plugin-zip": "wp-scripts plugin-zip", "start": "wp-scripts start" }, "devDependencies": { "@wordpress/scripts": "^24.1.0" } }

<code>...</code>

登入後複製

現在package.json已設置完畢，我們應該能夠通過在命令行中導航到項目文件夾並運行npm install來安裝所有這些依賴項。

添加插件標題

如果您來自經典的WordPress插件開發，那麼您可能知道所有插件在主插件文件中都有一塊信息，這有助於WordPress識別插件並在WordPress管理面板的“插件”屏幕上顯示有關它的信息。

以下是@wordpress/create-block為我生成的，用於一個創造性地稱為“Hello World”的插件：

npx @wordpress/create-block

登入後複製

這在主插件文件中，您可以根據需要隨意命名。您可以將其命名為index.php或plugin.php之類的通用名稱。 create-block包會自動將其命名為您在安裝時提供的項目名稱。由於我將此示例稱為“Block Example”，因此該包為我們提供了一個block-example.php文件，其中包含所有這些內容。

您需要更改一些詳細信息，例如將自己設為作者等等。並非所有這些都是必要的。如果我從“頭”開始，那麼它可能更接近於此：

{
  // 定义项目名称
  "name": "block-example",
  // 使用语义版本控制设置项目版本号
  "version": "0.1.0",
  // 项目的简短描述
  "description": "Example block scaffolded with Create Block tool.",
  // 您可以将其替换为您自己
  "author": "The WordPress Contributors",
  // 标准许可信息
  "license": "GPL-2.0-or-later",
  // 定义主JavaScript文件
  "main": "build/index.js",
  // 我们在开发过程中构建和编译插件所需的一切
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  // 定义使用脚本包的哪个版本（撰写本文时为24.1.0）
  // https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

登入後複製

我不會詳細介紹每一行的確切用途，因為這在WordPress插件手冊中已經是一個完善的模式了。

文件結構

我們已經查看了區塊所需的文件。但是，如果您使用的是@wordpress/create-block，您將在項目文件夾中看到許多其他文件。

以下是目前包含的內容：

<code>
这里的@wordpress/scripts包是主要的依赖项。如您所见，它是一个devDependency，这意味着它有助于开发。如何？它公开了wp-scripts二进制文件，我们可以使用它来编译我们的代码，从src目录到build目录，等等。

WordPress维护了许多其他软件包，用于各种目的。例如，@wordpress/components软件包为WordPress区块编辑器提供了一些预制UI组件，可用于为区块创建一致的用户体验，并符合WordPress设计标准。

您实际上*不需要*安装这些软件包，即使您想使用它们也是如此。这是因为这些@wordpress依赖项不会与您的区块代码捆绑在一起。相反，任何引用实用程序软件包代码的导入语句——例如@wordpress/components——都用于在编译期间构造“资产”文件。此外，这些导入语句被转换为将导入映射到全局对象的属性的语句。例如，import { \_\_ } from "@wordpress/i18n"被转换为const \_\_ = window.wp.i18n.\_\_的缩小版本。（window.wp.i18n是一个保证在全局范围内可用的对象，一旦相应的i18n软件包文件被排队）。

在插件文件中注册区块期间，隐式使用“资产”文件来告诉WordPress区块的软件包依赖项。这些依赖项会自动排队。所有这些都在幕后完成，前提是您使用的是scripts软件包。也就是说，您仍然可以选择在package.json文件中本地安装依赖项以进行代码完成和参数信息：

```json
// etc.
"devDependencies": {
  "@wordpress/scripts": "^24.1.0"
},
"dependencies": {
  "@wordpress/components": "^19.17.0"
}</code>

登入後複製

哇，好多！讓我們指出新的內容：

build/：此文件夾在處理生產用途的文件時接收已編譯的資產。
node_modules：此文件夾保存我們運行npm install時安裝的所有開發依賴項。
src/：此文件夾保存插件的源代碼，這些源代碼將被編譯並發送到build目錄。我們稍後將查看其中的每個文件。
.editorconfig：這包含用於調整代碼編輯器以實現代碼一致性的配置。
.gitignore：這是一個標準的存儲庫文件，用於識別應從版本控制跟踪中排除的本地文件。您的node_modules絕對應該包含在此處。
package-lock.json：這是一個自動生成的文件，用於跟踪使用npm install安裝的所需軟件包的更新。

區塊元數據

我想與您一起深入研究src目錄，但首先將重點放在其中的一個文件上：block.json。如果您使用的是create-block，它已經為您準備好了；如果沒有，請繼續創建它。 WordPress正在大力推動將其作為標準的規範方法來註冊區塊，方法是提供元數據，這些元數據為WordPress提供上下文，以便同時識別區塊並在區塊編輯器中呈現它。

以下是@wordpress/create-block為我生成的內容：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

登入後複製

實際上，我們可以在此處包含許多不同的信息，但實際上只需要name和title。一個超級精簡的版本可能如下所示：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

登入後複製

$schema定義用於驗證文件內容的模式格式。聽起來像是一個必需的東西，但它完全是可選的，因為它允許支持的代碼編輯器驗證語法並提供其他額外功能，例如工具提示提示和自動完成。
apiVersion指的是插件使用的Block API的哪個版本。今天，版本2是最新版本。
name是一個必需的唯一字符串，有助於識別插件。請注意，我已經在前面添加了css-tricks/，我將其用作命名空間，以幫助避免與可能具有相同名稱的其他插件發生衝突。您可以選擇使用您的姓名首字母縮寫之類的東西（例如as/block-example）。
version是WordPress建議用作發布新版本時的緩存清除機制。
title是另一個必需的字段，它設置在顯示插件的任何位置使用的名稱。
category將區塊與其他區塊分組，並將其一起顯示在區塊編輯器中。當前存在的類別包括文本、媒體、設計、小部件、主題和嵌入，您甚至可以創建自定義類別。
icon允許您從Dashicons庫中選擇一些內容，以便在區塊編輯器中以可視方式表示您的區塊。我使用format-quote圖標，因為我們在這個示例中正在製作我們自己的pullquote之類的東西。我們可以利用現有的圖標而不是必須創建我們自己的圖標，這很好，儘管這當然也是可能的。
editorScript是主JavaScript文件index.js所在的位置。

註冊區塊

在我們進入實際代碼之前，還有一件事，那就是註冊插件。我們剛剛設置了所有這些元數據，我們需要一種方法讓WordPress使用它。這樣，WordPress就知道在哪裡可以找到所有插件資產，以便可以將它們排隊用於區塊編輯器。

註冊區塊是一個兩步過程。我們需要在PHP和JavaScript中註冊它。對於PHP方面，打開主插件文件（在本例中為block-example.php），並在插件標題之後添加以下內容：

<code>...</code>

登入後複製

這就是create-block實用程序為我生成的內容，這就是為什麼函數的命名方式如此的原因。我們可以使用不同的名稱。關鍵是避免與其他插件衝突，因此最好在此處使用您的命名空間以使其盡可能唯一：

npx @wordpress/create-block

登入後複製

如果包含所有區塊元數據的block.json位於src中，為什麼我們要指向build目錄？這是因為我們的代碼仍然需要編譯。 scripts軟件包處理src目錄中文件的代碼並將生產中使用的已編譯文件放置在build目錄中，同時複製block.json文件。

好了，讓我們轉到註冊區塊的JavaScript方面。打開src/index.js並確保它如下所示：

{
  // 定义项目名称
  "name": "block-example",
  // 使用语义版本控制设置项目版本号
  "version": "0.1.0",
  // 项目的简短描述
  "description": "Example block scaffolded with Create Block tool.",
  // 您可以将其替换为您自己
  "author": "The WordPress Contributors",
  // 标准许可信息
  "license": "GPL-2.0-or-later",
  // 定义主JavaScript文件
  "main": "build/index.js",
  // 我们在开发过程中构建和编译插件所需的一切
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  // 定义使用脚本包的哪个版本（撰写本文时为24.1.0）
  // https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

登入後複製

我們正在進入React和JSX領域！這告訴WordPress：

從@wordpress/blocks軟件包導入registerBlockType模塊。
從block.json導入元數據。
從其相應的文件導入Edit和Save組件。我們稍後將向這些文件中添加代碼。
註冊區塊，並使用Edit和Save組件來呈現區塊並將內容保存到數據庫中。

Edit和save函數是怎麼回事？ WordPress區塊開發的細微之處之一是區分“後端”和“前端”，這些函數用於在這些上下文中呈現區塊的內容，其中edit處理後端呈現，save將內容從區塊編輯器寫入數據庫以在網站的前端呈現內容。

快速測試

我們可以快速操作一下，看看我們的區塊是否在區塊編輯器中工作並在前端呈現。讓我們再次打開index.js，並使用edit和save函數返回一些基本內容，以說明它們的工作方式：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

登入後複製

這基本上是我們之前代碼的精簡版本，只是我們直接指向block.json中的元數據來獲取區塊名稱，並且省略了Edit和Save組件，因為我們直接從此處運行函數。

我們可以通過在命令行中運行npm run build來編譯它。之後，我們可以在區塊編輯器中訪問名為“Block Example”的區塊：

如果我們將區塊放入內容區域，我們將獲得從edit函數返回的消息：

如果我們保存並發布文章，則在前端查看時，我們應該獲得從save函數返回的消息：

創建區塊

看起來一切正常！現在我們已經確認一切正常，我們可以恢復到測試之前的index.js中的內容：

<code>...</code>

登入後複製

請注意，edit和save函數與src目錄中@wordpress/create-block為我們生成的兩個現有文件相關聯，並且包含我們在每個文件中需要的其他導入。更重要的是，這些文件建立了包含區塊標記的Edit和Save組件。

後端標記（src/edit.js）

npx @wordpress/create-block

登入後複製

看看我們做了什麼？我們正在從@wordpress/block-editor軟件包導入props，這允許我們生成稍後可以用於樣式的類。我們還導入了__國際化函數，用於處理翻譯。

前端標記（src/save.js）

這將創建一個Save組件，我們將使用與src/edit.js幾乎相同的內容，但文本略有不同：

{
  // 定义项目名称
  "name": "block-example",
  // 使用语义版本控制设置项目版本号
  "version": "0.1.0",
  // 项目的简短描述
  "description": "Example block scaffolded with Create Block tool.",
  // 您可以将其替换为您自己
  "author": "The WordPress Contributors",
  // 标准许可信息
  "license": "GPL-2.0-or-later",
  // 定义主JavaScript文件
  "main": "build/index.js",
  // 我们在开发过程中构建和编译插件所需的一切
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  // 定义使用脚本包的哪个版本（撰写本文时为24.1.0）
  // https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

登入後複製

同樣，我們得到了一個可以在CSS中使用的不錯的類：

樣式區塊

我們剛剛介紹瞭如何使用區塊屬性來創建類。您正在CSS相關的網站上閱讀這篇文章，因此我覺得如果我們沒有特別介紹如何編寫區塊樣式，我會錯過一些東西。

區分前端和後端樣式

如果您查看src目錄中的block.json，您會發現兩個與樣式相關的字段：

editorStyle提供應用於後端的樣式的路徑。
style是應用於前端和後端的共享樣式的路徑。

Kev Quirk有一篇詳細的文章展示了他使後端編輯器看起來像前端UI的方法。

回想一下，@wordpress/scripts軟件包在處理/src目錄中的代碼並將已編譯的資產放置在/build目錄中時，會復制block.json文件。用於註冊區塊的是build/block.json文件。 這意味著我們在src/block.json中提供的任何路徑都應相對於build/block.json編寫。

使用Sass

我們可以將幾個CSS文件放入build目錄中，在src/block.json中引用路徑，運行build，然後就完成了。但這並沒有充分利用@wordpress/scripts編譯過程的功能，該過程能夠將Sass編譯成CSS。相反，我們將樣式文件放在src目錄中，並在JavaScript中導入它們。

這樣做時，我們需要注意@wordpress/scripts如何處理樣式：

導入到JavaScript代碼中的名為style.css或style.scss或style.sass的文件將編譯為style-index.css。
所有其他樣式文件都將被編譯並捆綁到index.css中。

@wordpress/scripts軟件包使用webpack進行捆綁，並使用PostCSS插件進行樣式處理。 PostCSS可以使用其他插件進行擴展。 scripts軟件包使用Sass、SCSS和Autoprefixer的插件，所有這些插件都無需安裝其他軟件包即可使用。

事實上，當您使用@wordpress/create-block啟動初始區塊時，您可以很好地開始使用SCSS文件，您可以使用這些文件快速上手：

editor.scss包含應用於後端編輯器的所有樣式。
style.scss包含前端和後端共享的所有樣式。

現在讓我們通過編寫一些我們將編譯成區塊CSS的Sass來實際操作一下。儘管這些示例不會非常Sass化，但我仍然將它們寫入SCSS文件以演示編譯過程。

前端和後端樣式

好的，讓我們從應用於前端和後端的樣式開始。首先，我們需要創建src/style.scss（如果您使用的是@wordpress/create-block，它已經存在），並確保我們導入它，我們可以在index.js中執行此操作：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

登入後複製

打開src/style.scss並在其中使用從區塊屬性為我們生成的類放入一些基本樣式：

<code>...</code>

登入後複製

現在就這些！當我們運行build時，這將編譯成build/style.css，並由區塊編輯器和前端引用。

後端樣式

您可能需要編寫特定於區塊編輯器的樣式。為此，請創建src/editor.scss（同樣，@wordpress/create-block為您執行此操作），並在其中放入一些樣式：

npx @wordpress/create-block

登入後複製

然後在edit.js中導入它，該文件包含我們的Edit組件（我們可以在任何地方導入它，但由於這些樣式是用於編輯器的，因此在此處導入組件更合乎邏輯）：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

登入後複製

現在，當我們運行npm run build時，樣式將應用於這兩種上下文中的區塊：