建立 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 套裝中:

  1. 在 Finder 中建立一個檔案。
  2. 將檔案新增至新的檔案。
  3. 重新命名檔案,然後在檔案名稱中新增 .wdgt 副檔名,以建立 Widget 套裝。檔案圖示會變更為 Widget 圖示。
  4. 將你的 Widget 新增到 iBooks Author。

建立 Widget 的秘訣

在建立 Widget 套裝之前,請確認套裝中的檔案名稱沒有使用控制字元。如果檔案名稱中有控制字元,你將不能將該書籍發佈至 Apple Books 的 Book Store。

如果你將 Widget 設為會自動播放,Widget 就不能存取互聯網。 

請勿使用自訂檔案圖示,並避免在 Widget 中使用下列檔案名稱:

  • 資源/
  • 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 建立的書籍不提供互聯網外掛模組,例如 Flash。 你可以使用 HTML5 <video> 和 <audio> 等元素來納入視訊和音訊。
HTML Widget 內部的影片和音訊不能受 DRM 保護。
AllowJava 以 iBooks Author 建立的書籍,其中的 Widget 不能包含 Java 內容。
AllowSystem 以 iBooks Author 建立的書籍,其中的 Widget 不能存取系統指令。
外掛模組 以 iBooks Author 建立的書籍,其中的 Widget 不能包含 Cocoa 外掛模組組件。

iBooks Author 會忽略以下鍵值:

鍵值 說明
CloseBoxInsetX iBooks Author 及 Apple Books 中的 Widget 不會顯示 close 裝飾。
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 服務。

發佈日期: