建立 iBooks Author 適用的 HTML5 Widget

瞭解如何製作能用於以 iBooks Author 所建立書籍中的 HTML5 Widget。

iBooks Author 支援 HTML5 Widget（副檔名為 .wdgt）。若要製作 HTML5 Widget，請使用文字編輯器或內容製作 app 建立以下三個檔案：

主要 HTML 檔案：這個檔案是 Widget 的主要部分。可以將它命名為任何您想要的名稱，但是副檔名必須是 .html。您可以將 CSS 和 JavaScript 置於主要的 HTML 檔案內。或者，您也可以將 .css 和 .js 檔案新增至 Widget 套件，然後從主要的 HTML 檔案進行載入。舉凡可用來設計網頁的各項技術，皆可應用。使用 HTML 定義 Widget 的結構，並以 CSS 提供視覺化樣式，然後運用 JavaScript 實現互動。
Default.png 檔案：若要建立 Default.png，最簡單的方式是在網頁內容製作 app 或網頁瀏覽器中，擷取主要 HTML 檔案的螢幕快照。這是使用者在頁面上看到的影像，點一下即可開啟您的 Widget。在網頁瀏覽器或網頁內容製作 app 中，擷取主要 HTML 檔案的螢幕快照。將其命名為「Default.png」，而且首字務必要使用大寫字母「D」。當您的 Widget 執行時，將等於 Default.png 檔案的大小。您可以在 Info.plist 檔案中變更其大小。
Info.plist 檔案：這個檔案會為 iBooks Author 和 Apple Books 提供執行 Widget 所需的資訊。檔案名稱必須為「Info.plist」。

建立完這些必要的檔案之後，請建立所需的選用檔案，例如 CSS 或 JavaScript 檔案。接著，將這些檔案全都新增至 Widget 套件中：

在 Finder 中建立一個檔案夾。
將檔案新增至新的檔案夾。
重新命名檔案夾，然後在檔案夾名稱中新增 .wdgt 副檔名，以建立 Widget 套件。檔案夾圖像會變更為 Widget 圖像。
將您的 Widget 新增到 iBooks Author。

建立 Widget 的秘訣

在建立 Widget 套件之前，請確認套件中的檔案名稱沒有使用控制字元。若有，您就無法發佈該書籍至 Apple Books 中的「書店」。

如果您將 Widget 設為會自動播放，Widget 就不能存取 Internet。

請勿使用自訂檔案夾圖像，並避免在 Widget 中使用下列檔案夾名稱：

Resources/
Support Files/Resources/
Contents/Resources/

若要針對 Retina 顯示器來最佳化您的 Widget：

在 HTML、CSS 及 JavaScript 檔案中，使用適用於具有 Retina（2x）圖形之網站的標準通訊協定。
在您的 Widget 中納入 Default@2x.png 檔案。讓檔案的解析度為 Default.png 檔案的兩倍。您無法在 iBooks Author 中檢視這個檔案，但可以在 Retina 顯示器上的 Apple Books 中加以檢視。

進一步瞭解如何最佳化以 iBooks Author 製作的書籍。

Info.plist

基本 Widget 的 Info.plist 包含一些必要的鍵值及一些選用的鍵值。下表列出了這些鍵值、其定義，以及「Hello World」Widget 的一些範例值。

鍵值	範例值	必要	定義
CFBundleDevelopmentRegion	英文	選用	指定套件原生區域的字串。這通常對應於建立套件的人所用的母語。
CFBundleDisplayName	Hello World	必要	包含 Widget 實際名稱的字串。這將會顯示在 iBooks Author 和 Apple Books 中。
CFBundleIdentifier	com.apple.widget.HelloWorld	必要	唯一識別 Widget 的字串，這是以反向網域格式所呈現。
CFBundleName	Hello World	選用	包含 Widget 名稱的字串。它必須符合 Finder 中的 Widget 套件名稱，但不顯示 .wdgt 副檔名。
CFBundleShortVersionString	1.0	選用	提供 Widget 簡短版本編號的字串。通常與 CFBundleVersion 相同。
CFBundleVersion	1.0	選用	提供 Widget 版本編號的字串。
高度	768	選用	提供 Widget 高度（單位為像素）的數字。如果未指定，將使用 Default.png 的高度。
MainHTML	HelloWorld.html	必要	提供實作 Widget 的 HTML 檔案名稱的字串。
寬度	1024	選用	提供 Widget 寬度（單位為像素）的數字。如果未指定，將使用 Default.png 的寬度。
IBNotifiesOnReady	<true/>	選用	如果設定為 true，Widget 將通知 Apple Books 何時從顯示 Default.png 切換為顯示執行中的 HTML Widget。

Widget 完整的 Info.plist 如下所示：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleDevelopmentRegion</key>
	<string>English</string>
	<key>CFBundleDisplayName</key>
	<string>Hello World</string>
	<key>CFBundleIdentifier</key>
	<string>com.apple.widget.HelloWorld</string>
	<key>CFBundleName</key>
	<string>Hello World</string>
	<key>CFBundleShortVersionString</key>
	<string>1.0</string>
	<key>CFBundleVersion</key>
	<string>1.0</string>
	<key>Height</key>
	<integer>768</integer>
	<key>MainHTML</key>
	<string>HelloWorld.html</string>
	<key>Width</key>
	<integer>1024</integer>
	<key>IBNotifiesOnReady</key>
	<true/>
</dict>
</plist>

主要限制

請勿使用下列鍵值；這些功能無法相容：

鍵值	說明
AllowFileAccessOutsideOfWidget	以 iBooks Author 建立的書籍，其中的 Widget 無法存取一般檔案系統中的檔案。
AllowFullAccess	其他存取鍵值列表的縮寫，有些並不相容。
AllowInternetPlugins	以 iBooks Author 建立的書籍無法使用 Internet 外掛模組，例如 Flash。您無法使用 HTML5 <video> 和 <audio> 等元素來納入影片和音訊。 HTML Widget 內部的影片和音訊不能受 DRM 保護。
AllowJava	以 iBooks Author 建立的書籍，其中的 Widget 不能包含 Java 內容。
AllowSystem	以 iBooks Author 建立的書籍，其中的 Widget 不能存取系統指令。
Plugin	以 iBooks Author 建立的書籍，其中的 Widget 不能包含 Cocoa 外掛模組組件。

iBooks Author 會忽略以下鍵值：

鍵值	說明
CloseBoxInsetX	iBooks Author 及 Apple Books 中的 Widget 不會顯示關閉裝飾。
CloseBoxInsetY
字體	iBooks Author Widget 不能使用隨附字體。

視訊和音訊要求

您不能使用副檔名為 .m4v 或 .m4p 的媒體。使用副檔名為 .mp4 的下列其中一種格式：

H.264 影片：最高可達 720p、每秒 60 影格。High Profile 4.2 級，採用 AAC-LC 音訊，最高可達 160 kbps、48 kHz、立體音訊。在 iMovie 10 中使用 HD 720p 選項開啟的視訊會使用這些設定。
MPEG-4 影片：最高可達 2.5 Mbps、640 x 480 像素、每秒 30 影格。Simple Profile，採用 AAC-LC 音訊，最高可達每頻道 160 kbps、48 kHz、立體音訊。

針對音訊，請使用副檔名為 .m4a 的 AAC（8 至 320 Kbps、48 kHz 立體聲）。

HTML Widget 套件中的視訊和音訊媒體不能受 DRM 保護。

如果影片或音訊檔案無法在您 iBooks Author 的 Widget 中播放，請在 iPhone、iPad 或 Mac 上加以預覽。這應該會顯示檔案將如何在您完成的書籍中播放。

本地化

iBooks Author 不支援本地化字串和資產。請在內文中以目標語言加入使用者能看到的文字字串。

遭裁剪的元素

元素（例如 <video>）可能會發生單邊遭到裁剪的情況。如果元素尺寸大於可用空間，就有可能發生這個情況。請在 #video 選擇器中尋找「width:auto」的 CSS，並加以變更，以反映實際尺寸。舉例來說，如果您的 Widget 包含尺寸為 960 x 540 的視訊，請檢查相關選擇器的 CSS，並將寬度和高度設為正確的值：

#video   {
	width: 960;
	height: 540;
}

適用於 iOS 和 macOS 的開發

iOS 和 macOS 使用不同的輸入類型。建立 iBooks Author 適用的 HTML Widget 時，您可以配合觸控和滑鼠輸入。

避免在讀者開啟 HTML Widget 時發生閃光

如果您的 HTML Widget 非常複雜，當讀者在 Apple Books 中加以開啟時，就有可能會看到閃光。若要避免此種情況，請更新您的 Widget，以告知 Apple Books 何時應該從 Default.png 檔案切換至 HTML Widget：

1. 在 Widget 的 Info.plist 中新增設為 true 的「IBNotifiesOnReady」項目。這會讓 Apple Books 知道 Widget 將會告知何時應該切換至 HTML Widget.

<key>IBNotifiesOnReady</key>
 <true/>

2. 在 HTML 檔案的 <head> 部分，將 Widget 設為載入 Apple JavaScript 程式庫：

<script type="text/javascript" src="AppleClasses/AppleWidget.js"> </script>

iOS 和 macOS 已具備 AppleWidget.js，因此，您不需要將其納入自身的 Widget 套件中。

3. 設定您的 Widget，以便在 HTML 初始化時告知 Apple Books。在 HTML 檔案 <head> 部分的 JavaScript 中，呼叫：

widget.notifyContentIsReady()

發佈至外部 Web 服務

唯有在 HTML Widget 使用了正確的跨來源資源共享 (CORS) 標頭時，您才可以將其發佈至外部 Web 服務。

發佈日期：十月 12, 2018