Scheme (zh_TW)

資料規格

以下為 WebScrapBook 遵循的資料規格。可參考 ScrapBook X 資料規格作為對照。

剪貼簿資料夾

WebScrapBook 在剪貼簿目錄（root）下有三種最頂層的子目錄：

• .wsb: 儲存 WebScrapBook 及後端伺服器（PyWebScrapBook）的設定和暫存檔。
• tree: 儲存元資料、目錄樹、及靜態站台資料等。
• data: 儲存擷取的頁面。

可調整後端伺服器的配置改變 tree 及 data 目錄的儲存路徑：

• data 可放在 root 或任意層數的子目錄下，但不能放在 .wsb 下。
• tree 可放在 root 任意層數的子目錄下，也可以放在 .wsb 下。若要放在 .wsb 下，建議設為保留的 .wsb/tree 以免因不當使用干擾後端伺服器的運作。

為求簡潔，雖可自訂，以下仍以 data 及 tree 稱之。

data 資料夾

WebScrapBook 資料項目的索引檔可為 */index.html、*.htz、*.maff、*.html、或 *.htm，放在 data 資料夾或任意層數的子目錄下。

資料項目的索引檔可藉由 index 屬性修改，但一般建議與項目名稱保持對應。試想名為 維基百科 的資料項目指向名為 搞基百科/index.html 的索引檔，這……怪怪的，對吧？

資料檔有一些限制，如下：

• 索引檔為 */index.html、*.htz、或 *.maff 的資料項目才允許含有資源檔案。

  • 對於 */index.html，所有 */ 資料夾下的檔案皆視為此資料項目的一部分。
  • *.htz 必須為 ZIP 檔案且內部含有 index.html 索引檔。
  • *.maff 必須為 ZIP 檔案且內部含有 */index.rdf 或 */index.* 索引檔，並符合 MAFF 規格書的要求。
  • *.html 為單一 HTML 檔案（所有資源皆內嵌其中），其連結的檔案皆視為外部檔案，而非此資料項目的一部分。
  • *.htm 作為索引檔是保留給書籤項目使用，此檔案必須使用 meta 重導向至原始網頁，且與資料項目的 source 屬性一致。

• 為避免混淆，不同資料項目不可使用同一個索引檔。

• 為避免混淆，資料項目的檔案（索引檔或資源檔）不可放在另一個（索引檔為 */index.html 的）資料項目的資料夾下。

  • 更嚴格地說，data 資料夾下任何含有資料項目的子資料夾皆不可含有名為 index.html 的檔案，即使此檔案尚未被指定為任一資料項目的索引檔亦然，以免 WebScrapBook 索引器誤判。
  • 同理，單一 HTML 檔案（*.html）的項目不可命名為 index.html，以免被誤判為 */index.html 項目。

  例如以下結構：

  data
      subdir
          item1
              index.html
              ...
          item2.htz
          item3.maff
          item4.html
          item5.htm
          index.html
  

  • subdir 下若有 index.html，就會使程式把 subdir 視為資料項目，其下所有檔案和資料夾，如 item1...5，都視為此項目的一部分。在這種情況下，item1...5 只能是 subdir 資料項的內容，而不可以是其他資料項目。
  • 反過來說，若 subdir 下已有作為資料項目的 item1、item2、item3、item4、或 item5，就不可以有 index.html 檔案。

• 資料項目的索引檔可用 meta 重導向至其資源檔案（頁面或一般檔案）。

  許多網頁擷取工具會把網頁儲存為名為 <name>.htm(l) 的檔案及名為 <name>.files 或 <name>_files 的支援資料夾。若把此類資料直接放在一個資料夾下，像這樣：

  dir
      page1.htm
      page1_files
      page2.htm
      page2_files
      ...
  

  直接交給 WebScrapBook 建立索引時，這些頁面皆會被視作單一 HTML 檔案，未來可能會發生處理異常。

  要讓 WebScrapBook 正確理解它們，可把它們各別放在獨立的子資料夾，並且建立 index.html 以 meta 重導向至主頁面，像這樣：

  dir
      page1
          index.html  (meta 重導向至 page1.htm)
          page1.htm
          page1_files
      page2
          index.html  (meta 重導向至 page2.htm)
          page2.htm
          page2_files
      ...
  

• 為了避免跨平台相容性問題，也要注意：

  • 檔名中不應含有可能不被某些平台支援的字元，例如 :、"、?、*、\、|、<、> 及控制字元（0x00–0x1F、0x7F、0x80–0x9F）。
  • 不應同時存在檔名只有大小寫不同的檔案，例如 myimage.jpg 和 MyImage.JPG。

tree 資料夾

索引檔

WebScrapBook 使用三種索引檔，分別記錄剪貼簿項目的元資料、目錄表、以及全文快取，大致相當於傳統 ScrapBook 的 scrapbook.rdf 和 cache.rdf 檔案。

• meta#.js: 記錄剪貼簿項目的元資料。
• toc#.js: 記錄目錄表。
• fulltext#.js: 記錄全文快取。

三種檔案皆可分割為多個連續檔名，其中 # 為空值或正整數。索引檔的內容必須含有一個 JavaScript 的函數調用 scrapbook.<fn>(<data>)，其中 <data> 須為 JSON 規格的文字資料。這樣做是為了確保靜態站台檔案的跨瀏覽器相容性。

靜態站台檔案

• map.html: 索引頁，會動態載入索引檔並列出剪貼簿中所有項目。
• index.html: 靜態索引頁，含有靜態的目錄表，供搜尋引擎優化及不支援 JavaScript 的瀏覽器讀取。對於支援 JavaScript 的瀏覽器，此頁面一樣會動態載入索引檔，因此一般而言速度比 map.html 更慢。
• frame.html: 框架頁，側欄以 map.html 頁面作為目錄，側欄開啟的項目會在主框架頁載入。
• search.html: 搜尋頁，可用元資料或全文搜尋。

上述頁面皆是由 WebScrapBook 索引器自動產生，不應手工編輯，但可建立對應名稱的 <name>.css 或 <name>.js 檔案客製其功能和樣式。

靜態站台使用的檔案還有：

• feed.atom: RSS 摘要，列出最近更新的項目。
• icon: 靜態站台頁面使用的圖示。
• favicon: 內嵌最愛圖示的快取檔案。

其他項目

• templates: 剪貼簿的模版檔案。目前支援用 note_template.html 及 note_template.md 設定 HTML 及 Markdown 筆記的預設內容。

.wsb 資料夾

• config.ini: 後端伺服器的配置檔。
• locks: 存放檔案寫入的保護鎖。
• themes: 存放後端伺服器的自訂主題。
• server: 存放後端伺服器運作時的資料檔及暫存檔。
• backup: 存放備份檔。

剪貼簿項目的元資料

傳統 ScrapBook 的資料項目使用 <ID>/index.dat 記錄元資料。而對於 WebScrapBook，項目的元資料直接記錄於項目的索引檔的根元素（*/index.html，或 *.htz 或 *.maff 中的 index.html，或單一 HTML 檔案本身）：

• data-scrapbook-id: 項目的 ID。通常可省略，由套件自動管理。
• data-scrapbook-type: 項目類型。一般頁面可省略此項，其他類型的項目則不可省，常見如 file 或 note。
• data-scrapbook-source: 項目的原始網址。
• data-scrapbook-create: 項目的建立時間。
• data-scrapbook-modify: 項目的修改時間。通常可省略，會直接取用檔案的最後修改時間。
• data-scrapbook-title: 項目的標題。通常可省略，會直接取用網頁標題。
• data-scrapbook-icon: 項目的最愛圖示網址。通常可省略，會直接取用網頁的最愛圖示。
• data-scrapbook-charset: 項目的文字編碼。通常用於純文字檔案。
• data-scrapbook-comment: 項目的評註。

WebScrapBook 主要把元資料記錄在 tree 資料夾下的索引檔，異動時也只更新這些檔案。因此前述項目檔案中的元資料只是記錄擷取時的狀態，或供索引器匯入新項目時用。這和傳統 ScrapBook 不同，後者在異動時會更新 scrapbook.rdf 及資料檔案中的 index.dat。

對於有資源檔的項目，索引頁可用 meta 重導向至真正的主要頁面。此時元資料應記錄在索引頁，而非導向的主要頁面中。

剪貼簿頁面使用的特殊屬性

以下屬性記錄 WebScrapBook 於時間點 <time> 擷取的頁面改寫前的狀態（有設定相關選項時）：

• data-scrapbook-orig-null-node-<time>: 原始頁面中此元素不存在。
• data-scrapbook-orig-null-attr-<attr>-<time>: 原始頁面中此元素無 <attr> 屬性。
• data-scrapbook-orig-attr-<attr>-<time>: 原始頁面中此元素的 <attr> 屬性值。
• data-scrapbook-orig-textContent-<time>: 原始頁面中此元素的文字內容。

以下屬性記錄一些原始頁面無法以標準 HTML 表達的資訊：

• data-scrapbook-css-disabled: 原始頁面中此樣式表元素為停用狀態。
• data-scrapbook-input-checked: 原始頁面中此 INPUT 元素的勾選狀態。
• data-scrapbook-input-indeterminate: 原始頁面中此 INPUT 元素為不確定狀態。
• data-scrapbook-input-value: 原始頁面中此 INPUT 元素的值。
• data-scrapbook-option-selected: 原始頁面中此 OPTION 元素的選取狀態。
• data-scrapbook-textarea-value: 原始頁面中此 TEXTAREA 元素的值。
• data-scrapbook-canvas: 原始頁面中此畫布元素的像素內容。
• data-scrapbook-shadowdom: 原始頁面中此元素的影子物件（shadow DOM）內容。
• data-scrapbook-shadowdom-mode: 原始頁面中此元素的影子物件 mode 屬性。
• data-scrapbook-shadowdom-clonable: 原始頁面中此元素的影子物件 clonable 屬性。
• data-scrapbook-shadowdom-delegates-focus: 原始頁面中此元素的影子物件 delegatesFocus 屬性。
• data-scrapbook-shadowdom-serializable: 原始頁面中此元素的影子物件 serializable 屬性。
• data-scrapbook-shadowdom-slot-assignment: 原始頁面中此元素的影子物件 slotAssignment 屬性。
• data-scrapbook-adoptedstylesheet-<index>: 原始頁面中第 <index> 個建構式樣式表內容。
• data-scrapbook-adoptedstylesheets: 原始頁面中此元素相關 DOM 使用的建構式樣式表。
• data-scrapbook-slot-assigned: 原始頁面中此 SLOT 元素人工指派目標節點的索引值。
• data-scrapbook-slot-index: 原始頁面中此元素作為 SLOT 元素人工指派目標的索引值。

此外，也使用以下特殊 HTML 註解：

• <!--scrapbook-capture-selected-->...<!--/scrapbook-capture-selected-->: WebScrapBook 擷取選取範圍時的選取範圍。
• <!--scrapbook-capture-selected-splitter-->...<!--/scrapbook-capture-selected-splitter-->: WebScrapBook 擷取選取範圍時若在同一個類文字節點中選取了多個範圍，此註解標示不同選取範圍之間的分隔。
• <!--scrapbook-slot-index=<index>-->...<!--scrapbook-slot-index-->: 原始頁面中此文字節點作為 SLOT 元素人工指派目標的索引值。

頁面編輯及儲存使用的特殊屬性

以下為 WebScrapBook 編輯及儲存頁面時會使用的特殊屬性：

• data-scrapbook-elem: 將此元素標示為對 WebScrapBook 有特殊意義的元素，例如輔助載入資料的腳本、標示、註解等元素。以下是可供使用者自由寫入的屬性：
  • data-scrapbook-elem="todo": 將此元素（通常為 checkbox）標示為待辦事項。
  • data-scrapbook-elem="title": 儲存頁面時，主頁面（資料項目的索引頁或索引頁 meta 重導向的頁面）中具有此屬性的元素的文字內容會更新為資料項目的標題。
  • data-scrapbook-elem="title-src": 儲存頁面時，主頁面中具有此屬性的元素的文字內容會覆寫至此資料項目的標題及其他 data-scrapbook-elem="title-src" 元素的文字內容。
  • data-scrapbook-elem="custom": WebScrapBook 編輯器會把具有此屬性的元素視為剪貼簿註記，可用移除註記功能移除。
  • data-scrapbook-elem="custom-wrapper": WebScrapBook 編輯器會把具有此屬性的元素視為包覆式剪貼簿註記，可用移除註記功能拆包（移除元素但保留所有子元素）。
  • data-scrapbook-elem="custom-css": 標示此元素為自訂樣式表，編輯時不會改動（例如不會被透過 CSS 選擇器擦除）。
  • data-scrapbook-elem="custom-script": 標示此元素為自訂腳本，編輯時不會改動（例如不會被透過 CSS 選擇器擦除）。
  • data-scrapbook-elem="custom-script-safe": 同 custom-script，並標示為不會影響頁面儲存的安全腳本，編輯器不會在存檔時警告文件中有腳本。
• data-scrapbook-id: 用於將多個特殊元素視為同一群組的辨識碼，例如用移除剪貼簿註記元素時，會一併移除其他具有相同辨識碼的元素。

此外，也使用以下特殊 HTML 註解：

• <!--scrapbook-erased-<time>=<content>-->: 記錄 WebScrapBook 擦除的網頁內容，可用 WebScrapBook 編輯器還原。

筆記模版

筆記模版中可使用以下語法，建立筆記時會動態改寫為適當的內容：

• %%: 寫入 % 符號。
• %NOTE_TITLE%: 寫入資料項目的標題，若無標題則寫入檔名（不含 ".html"）。
• %SCRAPBOOK_DIR%: 寫入連往剪貼簿根目錄的相對路徑。例如用 <link rel="stylesheet" href="%SCRAPBOOK_DIR%/common/common.css"> 引用全剪貼簿共用的樣式表。
• %TREE_DIR%: 寫入連往 tree 目錄的相對路徑。
• %DATA_DIR%: 寫入連往 data 目錄的相對路徑。
• %ITEM_DIR%: 寫入連往資料項目根目錄的相對路徑。