當我們花費上百小時以上，精心設計一個全新的佈景主題，並興致勃勃地想要上架到 WordPress 的官方佈景主題目錄，然而在線上排隊等待審核小組進行檢查的主題很多，可能要等待一個星期以上才有回音，結果收到的結果是駁回申請，或者請我們修正審核結果信件中提到需要被修正的事項，又要等上一段時間。
與其讓官方審核小組駁回、再修正，如此一來一往的無謂等待，不如我們一次把該注意的事項做到好，一次就上架成功吧！
WordPress 辨識佈景主題的版本資訊是掃描 style.css 檔案並分析內容的檔頭註解，而官方的佈景主題目錄判斷版本資訊是根據 readme.txt 這個檔案。
內容的編排格式很像 Markdown，它是 WordPress 的獨特格式，用來解析佈景主題的資訊。支援的段落標題和欄位的標記名稱如下：
| 標記名稱 | 標題層級 | 說明 |
|---|---|---|
| Theme Name | 1 | 佈景主題名稱。 |
| Contributors | 開發者的 WordPress.org 使用者名稱。 | |
| Requires at least | 所需的最低 WordPress 版本。 | |
| Requires PHP | 所需的最低 PHP 版本。 | |
| Tested up to | 已測試的 WordPress 版本。 | |
| Stable tag | 穩定版本標籤。 | |
| License | 版權許可證。 | |
| License URI | 版權許可證連結。 | |
| Tags | 和佈景主題相關的標籤。 | |
| Description | 2 | 佈景主主題的描述。 |
| Installation | 2 | 安裝說明。 |
| Changelog | 2 | 修改日誌。 |
| Copyright | 2 | 版權說明。 |
| Upgrade Notice | 2 | 升級的注意事項。 |
| Frequently Asked Questions | 2 | 常見問題解答。 |
| Screenshots | 2 | 截圖說明。 |
標題的層級和 Markdown 相反，最大的為 === ，相當於 h1， == 次之，相當於 h2，再來是 =，相當於 h3。
其中最重要的資訊在第一個段落，除了最後三個是外掛專用，不用填寫，其它必填。
Stable tag 為目前的最新的版本。WordPress 用這個欄位來判斷是否觸發更新提示。如果想要測試更新，把這個值調低，經過和官方目錄的版號比對不同，就會出現更新提示。
以上兩個欄位務必準確，以免使用這下載並啟用之後，發生 PHP Fatal 級別的錯誤。
在整個佈景主題中有使用到的圖片、字型、JavaScript 等程式片段，有用到第三方提供，非本人自創的部分則必須條列在 readme.txt 並詳列授權條款。如果使用上述檔案但盤點時確遺漏掉，則會被審核小組退件哦。
版權聲明陳列在 readme.txt 中的 Copyright 段落中。
準備 1200 x 900 長寬尺寸的圖片，格式為 png。這個比例換算為 4:3，它會出現在後台的外觀設定，佈景主題的列表中。
在 HTML 中，只要是輸出字串的地方都要使用過濾字串的 WordPress 函式，常見的函式如下。
| 函式名稱 | 說明 |
|---|---|
| esc_html | 轉換特定字元為 HTML 實體，主要用於在 HTML 元素內部過濾文本內容。 |
| esc_html__ | 與 esc_html 類似，但支援國際化。 |
| esc_html_e | 直接輸出 esc_html 的結果。 |
| esc_html_x | 與 esc_html 類似，不過參數提供情境，方便翻譯者辨識為動詞或名詞等等，以提高翻譯的準確度。 |
| esc_attr | 轉換特定字元為 HTML 實體，主要用於 HTML 元素的屬性值。 |
| esc_attr__ | 與 esc_attr 類似，但支援國際化。 |
| esc_attr_e | 直接輸出 esc_attr 的結果。 |
| esc_attr_x | 和 esc_attr 類似，不過參數提供情境，方便翻譯者辨識為動詞或名詞等等，以提高翻譯的準確度。 |
| esc_url | 用於過濾 URL。 |
| esc_js | 用於 JavaScript 中的字串。 |
| esc_textarea | 用於 HTML 的 <textarea> 元素中的內容。 |
例：
<span class="page-description search-term">' . esc_html( get_search_query() ) . '</span>
在搜尋頁面，使用者的輸入結果會印在網頁上，由於使用者會輸入什麼無法預料，基於安全性的理由，使用 esc_html 函式要將非法字元都過濾掉。
例：
<input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button', 'ironman' ); ?>" />
在 HTML 的屬性中，使用 esc_attr_x 函式來過濾非法字元。
在佈景主題中的每一個函式，都要加上前綴字，例如 ironman。此規範可以避免和內建的 WordPress 函式及其它外掛程式中的函式發生「撞名」而發生錯誤。
不能使用和佈景主題無關的功能，例如註冊 post_type ，這應該是在外掛裡做的事，而不是在佈景主題去註冊一個新的文章分類。
頁尾的版權連結的目標網頁必須是該佈景主題的介紹頁面或 DEMO 站，否則不會通過審核。
和佈景主題無關的檔案都必須移除，例如 .git、.vscode、node_modules 等目錄。提交審核之前務必確定類似的檔案及目錄都有排除。
在前一段落提到的是常常會被審核小組退回的原因，可以參考佈景主題檢視 一文，有更詳細的說明。
當檢查無誤後，把整個目錄打包為 zip 檔，依版號命名。例如：
ironman-1.0.0.zip
接著前往佈景主題上傳網頁：
圖：WordPress 佈景主題提交頁面
點擊下方的「Upload Your Theme」。一開始會經過自動程式檢查，這個步驟通過後，才會進到審核的程序。
當您想要將精心設計的佈景主題上架到 WordPress 官方目錄之前，務必檢查本篇文章提到的要點，確保一次成功，以減少等待審核的時間。
首先，編寫完整的 readme.txt，確保裡面的版本資訊、版權聲明等都正確。圖片、字型和程式碼的版權也必須明確，並提供正確的首頁縮圖。程式碼必須要確保所有變數的輸出都使用相對應的過濾函式進行過濾字串。佈景主題的函式要有前綴字。不能提供非佈景主題相關的額外功能。頁尾的版權連結要和佈景主題有直接的相關性，並刪除不相關的檔案。
佈景主題設計實戰系列到這邊告一段落，設計一個佈景主題需要花費上百小時來調整、測試，達到自己滿意才上架，因此在鐵人賽期間要同時完成是不可能達成的。筆者預估完成時間為 2023 年 11 月 15 日，為鐵人賽結束後一個月，想知道進度如何，歡迎加入筆者的臉書專頁喔。
圖：Terry 的臉書專頁（URL）
課後思考：
為什麼所有在 HTML 中輸出的字串都需要進行過濾？此舉對於網站的安全性有什麼影響？
前篇解答參考：
自訂器允許使用者在前台進行即時預覽佈景主題的更改，這為佈景主題設計提供了高度的彈性。我們可以提供不同頁面的佈局，例如 2 欄式、 3 欄式。側邊欄的位置在左邊，或者在右邊。字型的選擇，也可以讓使用者選用 Google 字型，還是正黑體、標楷體等等。不過提供的項目設定越多，面板的分類就要規劃好，讓使用者可以直覺地找到相關的設定項目，以提高使用者的體驗哦。
iThome鐵人賽
看影片追技術