WordPress Gutenberg Block API：塊外觀

新的WordPress編輯器（代號(hào)為Gutenberg）將于5.0版本發(fā)布。現(xiàn)在是在它進(jìn)入WordPress核心之前掌握它的最佳時(shí)機(jī)。 在本系列中，我將向您展示如何使用Block API并創(chuàng)建您自己的內(nèi)容塊，您可以使用它們來構(gòu)建您的帖子和頁面。

在本系列的第一篇文章中，我們概述了Block API并創(chuàng)建了一個(gè)簡(jiǎn)單的測(cè)試塊。我們稍后會(huì)仔細(xì)研究Block API，但首先讓我們編輯我們?cè)谏弦黄恼轮袆?chuàng)建的默認(rèn)塊，以了解對(duì)現(xiàn)有塊進(jìn)行更改是多么容易。

如果您還記得，我們的自定義塊在前端和后端的呈現(xiàn)方式不同，以證明您可以完全控制塊在編輯器中的呈現(xiàn)方式以及站點(diǎn)訪問者看到塊的樣子。

如果你一直在關(guān)注，那么打開塊源代碼所在的/wp-content/plugins/my-custom-block/src/block文件夾。該文件夾包含一個(gè)JavaScript文件和兩個(gè)Sass文件，它們控制塊的行為以及它在編輯器和前端的呈現(xiàn)方式。

在block.js?JavaScript文件中包含了JSX，這是在編譯過程中為有效的JavaScript transpiled。同樣，兩個(gè)Sass文件也轉(zhuǎn)換為標(biāo)準(zhǔn)CSS。

在構(gòu)建過程中，這些文件需要處理才能在插件的?dist/?文件夾中創(chuàng)建分發(fā)文件。這些是WordPress排隊(duì)引入的實(shí)際文件，因?yàn)樗鼈儼袨g覽器都能理解的有效JavaScript和CSS。

幸運(yùn)的是，該create-guten-block?工具包通過監(jiān)視塊文件的更改來處理構(gòu)建和轉(zhuǎn)換。 這是一個(gè)非常好的功能，因?yàn)樗屛覀儾挥脫?dān)心。我們可以專注于編寫塊代碼（和樣式），插件文件將自動(dòng)更新。真實(shí)太棒了！

只需確保從插件根文件夾中運(yùn)行命令?npm start?以觸發(fā)文件監(jiān)視。

是時(shí)候編輯一些代碼！

不要擔(dān)心在?block.js?中的JSX代碼的細(xì)節(jié)，因?yàn)槲覀兩院髸?huì)詳細(xì)介紹它。現(xiàn)在，讓我們專注于對(duì)前端視圖和后端視圖的塊輸出進(jìn)行一些簡(jiǎn)單的更改。

打開block.js，找到?edit?傳遞給第二個(gè)參數(shù)的對(duì)象的方法registerBlockType()，并用以下內(nèi)容替換它：

edit: function( props ) {
  return (
    <div className={ props.className }>
      <h3>Editor View</h3>
      <p>This is our custom block inside the editor.</p>
      <p>Let's add an unordered list!</p>
      <ul>
        <li>Apple</li>
        <li>Orange</li>
        <li>Pear</li>
        <li>Plum</li>
      </ul>
    </div>
  );
},

此方法控制塊在編輯器窗口中的呈現(xiàn)方式。現(xiàn)在找到?save?方法并將其替換為：

save: function( props ) {
  return (
    <div>
      <h3>Frontend View</h3>
      <p>This is our custom block as seen by site visitors.</p>
      <p>Let's add an ordered list!</p>
      <ol>
        <li>Red</li>
        <li>Blue</li>
        <li>Pink</li>
        <li>Brown</li>
      </ol>
    </div>
  );
},

此方法用于在前端渲染塊輸出。

在style.scss中，將所有樣式替換為：

.wp-block-cgb-block-my-custom-block  {
  background: #a7d9f1;
  color: #ffffff;
  border: 1px solid #62afd4;
  border-radius: 15px;
  margin: 0 auto;
  max-width: 740px;
  padding: 1.5rem;
 
  ol, ul {
    margin-left: 20px !important;
  }
 
  li {
    margin-bottom: 0;
  }
 
  h3 {
    color: #ffffff;
    margin-top: 0;
  }
}

然后，在editor.scss中，將所有樣式替換為：

.wp-block-cgb-block-my-custom-block {
  background: #cba7f1;
  border: 1px solid #a170d6;
}

您可以在下面的屏幕截圖中看到這些更改如何影響塊的渲染，具體取決于我們是在編輯器窗口還是在前端查看它。

我們還沒有排隊(duì)引入塊的腳本，但它足以讓我們知道，?editor.scss?樣式只適用于編輯窗口，而?style.scss?都會(huì)被添加到編輯窗口和前端。因此，可以從style.scss中省略在編輯器和前端中同時(shí)使用的樣式 。

注意我們?cè)赟ass文件中引用了一個(gè)冗長(zhǎng)的CSS選擇器來定位我們的塊元素。

.wp-block-cgb-block-my-custom-block

這個(gè)類由Gutenberg自動(dòng)添加到前端的塊容器元素中，但我們必須在編輯器窗口中手動(dòng)應(yīng)用它以獲得相同的類，如?edit?下面的方法所示。

<div className={ props.className }>
  <!-- Block code goes here -->
</div>

Gutenberg生成的類名確定如下：wp-block-[block namespace]-[block name。

在我們的例子中，我們使用?create-guten-block?工具包創(chuàng)建我們的塊，默認(rèn)情況下使用?cgb?命名空間，而?block-my-custom-block?是基于我們指定的塊名稱。 這會(huì)導(dǎo)致將CSS類名?wp-block-cgb-block-my-custom-block?添加到塊容器中。Gutenberg在內(nèi)部使用命名空間和塊名稱來唯一標(biāo)識(shí)塊。

在那里對(duì)塊文件進(jìn)行更改時(shí)，我發(fā)現(xiàn)了一些值得一提的痛點(diǎn)。

首先，在對(duì)?edit?方法進(jìn)行更改時(shí)，我發(fā)現(xiàn)自己必須先清除瀏覽器緩存，然后才能刷新編輯器窗口以查看最新的更改。 這種情況并非一直發(fā)生，但情況往往如此。如果您發(fā)現(xiàn)同樣的事情發(fā)生在您身上，請(qǐng)清除瀏覽器緩存并重試。

其次，在編輯?save?方法的內(nèi)容時(shí)，編輯器窗口在下次刷新時(shí)似乎發(fā)生了一些奇怪的事情。

為了證明這一點(diǎn)，我在?save?方法中添加了一個(gè)新的列表項(xiàng)（<li>Indigo</li>），然后刷新了帖子編輯器（當(dāng)然，必須再次清除緩存之后！）。這是結(jié)果：

如果選擇“?轉(zhuǎn)換為塊”??或“?編輯為HTML”，??則會(huì)顯示該?save?方法的內(nèi)容，該內(nèi)容應(yīng)在前端而非編輯器中查看。

這非常令人困惑，使事情恢復(fù)正常的唯一明顯方法是從編輯器窗口中刪除塊并再次重新插入。正如我在上一篇文章中所提到的，Gutenberg仍然是一項(xiàng)正在進(jìn)行中的工作，這就是一個(gè)很好的例子！

希望在未來的版本中這將更加直觀，但是現(xiàn)在它只是需要注意的事項(xiàng)。更改?save?函數(shù)時(shí)，請(qǐng)準(zhǔn)備刪除編輯器窗口中的相關(guān)塊并再次添加。

如前所述，save和edit方法的輸出可能完全不同。但是，在大多數(shù)情況下，您可能希望前端輸出與編輯器輸出匹配，以便編輯體驗(yàn)與前端渲染盡可能一致。

在我們上面的設(shè)計(jì)示例中，我僅在編輯器和前端視圖中添加了不同的內(nèi)容和樣式以用于演示目的。

Block API概述

Block API由添加到全局?wp?管理對(duì)象的一組JavaScript?對(duì)象組成。因?yàn)?wp?是全局性的，我們不需要在我們的源代碼中專門導(dǎo)入它 – 它可以按需提供。

在?wp?可用的對(duì)象取決于您當(dāng)前正在查看的管理頁面。例如，如果您要自定義站點(diǎn)，則?wp?包含主要的定制功能API對(duì)象。

但是，目前Gutenberg 塊 API僅適用于帖子編輯器。我預(yù)計(jì)，當(dāng)帖子編輯器和網(wǎng)站定制器之間的集成越來越近時(shí)，這將會(huì)發(fā)生變化。

您可以通過打開Gutenberg編輯器并在瀏覽器控制臺(tái)中輸入wp來查看wp的結(jié)構(gòu)。

如您所見，wp包含許多對(duì)象，但我們最感興趣的對(duì)象是：

• wp.elements
• wp.blocks
• wp.components
• wp.data
• wp.i18n

通過這些對(duì)象，您可以訪問創(chuàng)建一些非常復(fù)雜的塊所需的所有工具。嘗試在瀏覽器控制臺(tái)中鍵入其完整對(duì)象名稱以進(jìn)一步探索這些對(duì)象。

例如，如果您鍵入wp.blocks?并展開對(duì)象，您將看到其中一個(gè)可用的函數(shù)registerBlockType()。這是一個(gè)非常重要的功能，我們將在下一篇文章中深入介紹

wp.elements對(duì)象

該對(duì)象是React（和ReactDom）之上的抽象層，它以可預(yù)測(cè)和一致的方式公開React功能。即使底層實(shí)現(xiàn)被完全修改或改變，這仍然是正確的。

只要界面保持不變，與Block API交互的插件將不會(huì)受到影響。

wp.blocks對(duì)象

創(chuàng)建塊（registerBlockType()）的核心功能都包含在wp.blocks?一般塊管理所需的其他功能中，例如：

• getBlockType()
• getBlockContent()
• getBlockAttributes()
• hasBlockSupport()
• isValidBlock()

此對(duì)象還包含一組可重用的塊，您可以將這些塊包含在您自己的塊中，以提供無需額外開銷的功能。這些開箱即用的現(xiàn)成塊可以大大加快塊開發(fā)速度，我們將在下一篇文章中使用其中的一些，因?yàn)槲覀儗⑦M(jìn)一步深入研究塊的創(chuàng)建。

一些可用的是：

• 對(duì)齊工具欄
• 自動(dòng)完成
• 媒體上傳器
• 調(diào)色板
• 富文本編輯器

wp.components對(duì)象

wp.components?對(duì)象還包含可重用的組件，但這些組件更通用，通常用于在編輯器窗口中創(chuàng)建其他UI元素，例如塊設(shè)置的控制面板。

這些包括：

• 按鈕
• 復(fù)選框
• 代碼編輯器
• 破折號(hào)圖標(biāo)
• 日期/時(shí)間
• 下拉列表
• 菜單項(xiàng)
• 單選按鈕
• 范圍控制

wp.data對(duì)象

數(shù)據(jù)模塊在Gutenberg編輯器中管理應(yīng)用程序狀態(tài)，其中包括存儲(chǔ)每個(gè)塊的設(shè)置。我們將在本系列的最后一篇文章中介紹可以在塊中添加設(shè)置的不同方法。

wp.data?在Redux之上實(shí)現(xiàn)，所以當(dāng)Gutenberg與核心合并時(shí)，我們不僅可以訪問React，還可以訪問由Redux提供支持的完整集中式數(shù)據(jù)存儲(chǔ)！

wp.??i18n對(duì)象

插件和主題已經(jīng)能夠輕松地翻譯PHP字符串多年了，并且通過wp.i18n?對(duì)象，也可以使用類似的方法在JavaScript中翻譯字符串。這意味著您的塊中包含的所有字符串（包括塊名稱，關(guān)鍵字和標(biāo)簽）都可以翻譯成任何語言。

如果您之前使用過標(biāo)準(zhǔn)的PHP翻譯功能，那么您將感覺賓至如歸，因?yàn)檫@個(gè)過程幾乎是一樣的。我認(rèn)為這是一個(gè)聰明的舉動(dòng)，因?yàn)樗鼘⒐膭?lì)開發(fā)人員從一開始就在他們的塊中啟用字符串翻譯。

在塊代碼中，翻譯字符串非常簡(jiǎn)單：

wp.i18n.__( 'This string is translatable', 'text-domain' );

小結(jié)

在本教程中，我們實(shí)現(xiàn)了一個(gè)基本塊并編輯了代碼。我們還看到，我們可以完全控制塊的渲染，并且與前端相比，編輯器中可以有不同的塊視圖。

編輯器仍有一些問題可能會(huì)讓你不時(shí)感到驚訝 – 這提醒人們，Gutenberg仍在開發(fā)中，可能還沒有準(zhǔn)備好在生產(chǎn)網(wǎng)站上使用。

最后，我們總結(jié)了塊API，它在全局wp?JavaScript對(duì)象上引入了幾個(gè)新對(duì)象來創(chuàng)建和管理塊。

在下一篇文章中，我們將加快步伐并創(chuàng)建一個(gè)更全面的塊。為此，我們將深入探索?registerBlockType()這個(gè)函數(shù)。我們還將仔細(xì)研究正確排隊(duì)塊腳本。

原文：WordPress Gutenberg Block API: Block Look and Feel?，發(fā)布于 2018年5月9日，由?倡萌@WordPress大學(xué)?翻譯，未經(jīng)許可，禁止轉(zhuǎn)載和挪用譯文！