Excalidraw 和 Fugu:改善核心使用者歷程

任何堪稱先進的科技,皆與魔法無異。除非你瞭解。我叫 Thomas Steiner,在 Google 負責開發人員關係。在 Google I/O 演講的這篇報導中,我將介紹一些新的 Fugu API,以及這些 API 如何改善 Excalidraw PWA 的核心使用者歷程,讓您從這些想法中汲取靈感,並應用到自己的應用程式中。

我如何接觸 Excalidraw

我想先說個故事。2020 年 1 月 1 日,Facebook 軟體工程師 Christopher Chedeau 在 Twitter 上發文,介紹他開始開發的小型繪圖應用程式。這項工具可繪製卡通風格的手繪方塊和箭頭。隔天,您也可以繪製橢圓形和文字,以及選取物件並移動。1 月 3 日,應用程式有了名稱 Excalidraw,就像每個好的副專案一樣,購買網域名稱是 Christopher 的第一步。現在,您可以使用顏色,並將整個繪圖匯出為 PNG。

Excalidraw 原型應用程式的螢幕截圖,顯示支援矩形、箭頭、橢圓形和文字。

1 月 15 日,Christopher 發布了一篇網誌文章,在 Twitter 上引起廣泛關注,包括我的關注。文章開頭列出了一些令人印象深刻的數據:

  • 1.2 萬名不重複活躍使用者
  • 在 GitHub 獲得 1,500 顆星
  • 26 位貢獻者

對於僅僅兩週前才開始的專案來說,這已經相當不錯了。但真正引起我興趣的是文章後面的內容。Christopher 寫道,他這次嘗試了新做法:讓所有提出提取要求的人無條件獲得修訂版本存取權。閱讀網誌文章當天,我提出提取要求,為 Excalidraw 新增檔案系統 Access API 支援,修正使用者提交的功能要求。

我宣布個人最佳成績的推文螢幕截圖。

我的提取要求在一天後合併,從那時起,我就擁有完整的修訂權限。不用說,我沒有濫用權力。截至目前為止,149 位貢獻者中也沒有人這麼做。

目前,Excalidraw 是一款功能完整的可安裝漸進式網頁應用程式,支援離線功能、令人驚豔的深色模式,而且還能透過 File System Access API 開啟及儲存檔案。

Excalidraw PWA 目前狀態的螢幕截圖。

Lipis 說明他為何投入大量時間開發 Excalidraw

以上就是我與 Excalidraw 結緣的故事。在深入介紹 Excalidraw 的一些精彩功能之前,我很榮幸能向大家介紹 Panayiotis。Panayiotis Lipiridis 在網路上簡稱為 lipis,是 Excalidraw 最多產的貢獻者。我問 lipis 為什麼願意花這麼多時間投入 Excalidraw:

和大家一樣,我是從 Christopher 的推文得知這項計畫。我的第一項貢獻是新增 Open Color 程式庫,這些顏色至今仍是 Excalidraw 的一部分。隨著專案規模擴大,我們收到許多要求,我的下一個重大貢獻是建構後端來儲存繪圖,讓使用者可以分享。不過,真正驅使我貢獻心力的原因,是只要有人試用過 Excalidraw,就會想找藉口再次使用。

我完全同意 lipis 的看法。用過 Excalidraw 的人都會想找機會再用。

Excalidraw 實際應用

現在,我要示範如何實際使用 Excalidraw。我不是什麼偉大的藝術家,但 Google I/O 標誌很簡單,所以讓我試試看。方塊是「i」,線條可以是斜線,「o」是圓圈。按住 Shift 鍵,就能畫出完美的圓形。我稍微移動斜線,讓畫面看起來更美觀。現在為「i」和「o」上色。藍色代表良好。也許可以試試不同的填滿樣式?全實心或交叉線?不,暈滃法看起來很棒。雖然不完美,但這就是 Excalidraw 的概念,所以我先儲存。

我點選儲存圖示,並在檔案儲存對話方塊中輸入檔案名稱。在支援 File System Access API 的 Chrome 瀏覽器中,這不是下載,而是真正的儲存作業,我可以選擇檔案的位置和名稱,如果進行編輯,也可以直接儲存到同一個檔案。

讓我變更標誌,將「i」改成紅色。如果再次點選「儲存」,修改內容會儲存到與先前相同的檔案。為了證明這一點,我先清除畫布並重新開啟檔案。如您所見,修改後的紅藍標誌再次出現。

使用檔案

在目前不支援 File System Access API 的瀏覽器上,每次儲存作業都是下載,因此當我進行變更時,最終會有多個檔案,且檔案名稱中的數字會遞增,填滿「下載」資料夾。不過,儘管有這個缺點,我還是可以儲存檔案。

開啟檔案

那麼,祕訣是什麼?如何在可能支援或不支援 File System Access API 的不同瀏覽器上開啟及儲存檔案?在 Excalidraw 中開啟檔案時,系統會呼叫名為 loadFromJSON)( 的函式,接著再呼叫名為 fileOpen() 的函式。

export const loadFromJSON = async (localAppState: AppState) => {
  const blob = await fileOpen({
    description: 'Excalidraw files',
    extensions: ['.json', '.excalidraw', '.png', '.svg'],
    mimeTypes: ['application/json', 'image/png', 'image/svg+xml'],
  });
  return loadFromBlob(blob, localAppState);
};

fileOpen() 函式來自我們在 Excalidraw 中使用的 browser-fs-access 小型程式庫。這個程式庫透過檔案系統存取 API 提供檔案系統存取權,並提供舊版備用方案,因此可在任何瀏覽器中使用。

首先,我會示範如何在支援 API 時導入。協商可接受的 MIME 類型和副檔名後,核心部分是呼叫 File System Access API 的函式 showOpenFilePicker()。這個函式會傳回檔案陣列或單一檔案,具體取決於是否選取多個檔案。接著,只要將檔案控制代碼放在檔案物件上,即可再次擷取。

export default async (options = {}) => {
  const accept = {};
  // Not shown: deal with extensions and MIME types.
  const handleOrHandles = await window.showOpenFilePicker({
    types: [
      {
        description: options.description || '',
        accept: accept,
      },
    ],
    multiple: options.multiple || false,
  });
  const files = await Promise.all(handleOrHandles.map(getFileWithHandle));
  if (options.multiple) return files;
  return files[0];
  const getFileWithHandle = async (handle) => {
    const file = await handle.getFile();
    file.handle = handle;
    return file;
  };
};

備用實作會依賴 "file" 類型的 input 元素。協商要接受的 MIME 類型和副檔名後,下一步是以程式輔助方式點選輸入元素,顯示檔案開啟對話方塊。當使用者選取一或多個檔案時,Promise 就會解析。

export default async (options = {}) => {
  return new Promise((resolve) => {
    const input = document.createElement('input');
    input.type = 'file';
    const accept = [
      ...(options.mimeTypes ? options.mimeTypes : []),
      options.extensions ? options.extensions : [],
    ].join();
    input.multiple = options.multiple || false;
    input.accept = accept || '*/*';
    input.addEventListener('change', () => {
      resolve(input.multiple ? Array.from(input.files) : input.files[0]);
    });
    input.click();
  });
};

儲存檔案

現在來談談如何節省費用。在 Excalidraw 中,儲存作業會在名為 saveAsJSON() 的函式中進行。首先,它會將 Excalidraw 元素陣列序列化為 JSON,將 JSON 轉換為 blob,然後呼叫名為 fileSave() 的函式。這項函式同樣由 browser-fs-access 程式庫提供。

export const saveAsJSON = async (
  elements: readonly ExcalidrawElement[],
  appState: AppState,
) => {
  const serialized = serializeAsJSON(elements, appState);
  const blob = new Blob([serialized], {
    type: 'application/vnd.excalidraw+json',
  });
  const fileHandle = await fileSave(
    blob,
    {
      fileName: appState.name,
      description: 'Excalidraw file',
      extensions: ['.excalidraw'],
    },
    appState.fileHandle,
  );
  return { fileHandle };
};

首先,我們來看看支援 File System Access API 的瀏覽器實作方式。前幾行看起來有點複雜,但其實只是在協商 MIME 類型和副檔名。如果我先前已儲存檔案,且已有檔案控制代碼,就不需要顯示儲存對話方塊。但如果是第一次儲存,系統會顯示檔案對話方塊,應用程式也會取回檔案控制代碼,供日後使用。其餘部分則只是寫入檔案,這會透過可寫入串流進行。

export default async (blob, options = {}, handle = null) => {
  options.fileName = options.fileName || 'Untitled';
  const accept = {};
  // Not shown: deal with extensions and MIME types.
  handle =
    handle ||
    (await window.showSaveFilePicker({
      suggestedName: options.fileName,
      types: [
        {
          description: options.description || '',
          accept: accept,
        },
      ],
    }));
  const writable = await handle.createWritable();
  await writable.write(blob);
  await writable.close();
  return handle;
};

「另存新檔」功能

如果我決定忽略現有的檔案控制代碼,可以實作「另存新檔」功能,根據現有檔案建立新檔案。為了示範,我會開啟現有檔案,進行一些修改,然後不覆寫現有檔案,而是使用另存新檔功能建立新檔案。原始檔案則會保持不變。

對於不支援檔案系統存取 API 的瀏覽器,實作方式很簡短,因為它只會建立一個錨點元素,其 download 屬性的值是所需的檔案名稱,而 blob 網址則是其 href 屬性值。

export default async (blob, options = {}) => {
  const a = document.createElement('a');
  a.download = options.fileName || 'Untitled';
  a.href = URL.createObjectURL(blob);
  a.addEventListener('click', () => {
    setTimeout(() => URL.revokeObjectURL(a.href), 30 * 1000);
  });
  a.click();
};

接著,系統會透過程式輔助方式點按錨定廣告元素。為避免記憶體流失,請務必在使用後撤銷 Blob 網址。由於這只是下載,因此不會顯示檔案儲存對話方塊,所有檔案都會存放在預設的 Downloads 資料夾中。

拖放

我最喜歡的電腦系統整合功能之一是拖放。在 Excalidraw 中,當我將 .excalidraw 檔案拖曳到應用程式時,檔案會立即開啟,我可以開始編輯。在支援 File System Access API 的瀏覽器上,我甚至可以立即儲存變更。由於已從拖曳作業取得必要的檔案控制代碼,因此不需要透過檔案儲存對話方塊。

如要實現這項功能,只要在支援 File System Access API 時,對資料移轉項目呼叫 getAsFileSystemHandle() 即可。接著,我將這個檔案控制代碼傳遞至 loadFromBlob(),您可能還記得前面幾個段落。你可以對檔案執行許多操作:開啟、儲存、覆寫、拖曳、拖放。我和同事 Pete 在這篇文章中記錄了所有技巧和更多內容,如果覺得上述內容太快,可以參考這篇文章。

const file = event.dataTransfer?.files[0];
if (file?.type === 'application/json' || file?.name.endsWith('.excalidraw')) {
  this.setState({ isLoading: true });
  // Provided by browser-fs-access.
  if (supported) {
    try {
      const item = event.dataTransfer.items[0];
      file as any.handle = await item as any
        .getAsFileSystemHandle();
    } catch (error) {
      console.warn(error.name, error.message);
    }
  }
  loadFromBlob(file, this.state).then(({ elements, appState }) =>
    // Load from blob
  ).catch((error) => {
    this.setState({ isLoading: false, errorMessage: error.message });
  });
}

分享檔案

目前在 Android、ChromeOS 和 Windows 上,另一種系統整合方式是透過 Web Share Target API。我現在位於「檔案」應用程式的 Downloads 資料夾中。我可以看到兩個檔案,其中一個檔案的名稱是 untitled,並附有時間戳記。如要查看內容,請依序點選三點圖示和「分享」,畫面上會顯示「Excalidraw」選項。輕觸圖示後,可以看到檔案只包含 I/O 標誌。

Lipis 談論已淘汰的 Electron 版本

我還沒提到的一點是,你可以對檔案按兩下。一般來說,當您按兩下檔案時,系統會開啟與檔案 MIME 類型相關聯的應用程式。舉例來說,.docx 的應用程式是 Microsoft Word。

Excalidraw 曾有 Electron 版本的應用程式,支援這類檔案類型關聯,因此當您按兩下 .excalidraw 檔案時,Excalidraw Electron 應用程式就會開啟。Lipis 是 Excalidraw Electron 的創作者和淘汰者,您先前已見過他。我問他為什麼認為可以淘汰 Electron 版本:

從一開始,使用者就一直要求推出 Electron 應用程式,主要是因為他們想透過按兩下開啟檔案。我們也打算將應用程式上架到應用程式商店。同時,有人建議改為建立 PWA,因此我們兩者都做了。幸好,我們接觸到 Project Fugu API,例如檔案系統存取、剪貼簿存取、檔案處理等。只要按一下,就能在電腦或行動裝置上安裝應用程式,不必額外安裝 Electron。因此,我們很快就決定淘汰 Electron 版本,專注於網頁應用程式,並將其打造成最優質的 PWA。最棒的是,我們現在可以將 PWA 發布到 Play 商店和 Microsoft Store!這太驚人了!

有人可能會說,Electron 版 Excalidraw 之所以未淘汰,並非因為 Electron 不好,而是因為網頁已足夠好。我喜歡!

檔案處理

我之所以說「網路已經夠好」,是因為即將推出的檔案處理等功能。

這是 macOS Big Sur 的一般安裝作業。現在,我們來看看在 Excalidraw 檔案上按一下滑鼠右鍵會發生什麼事。我可以選擇使用已安裝的 PWA Excalidraw 開啟。當然,按兩下也可以,只是在螢幕側錄中示範的效果較不明顯。

這項功能如何運作?第一步是讓作業系統知道我的應用程式可以處理哪些檔案類型。我會在網頁應用程式資訊清單中,名為 file_handlers 的新欄位執行這項操作。其值為物件陣列,包含動作和 accept 屬性。動作會決定作業系統啟動應用程式的網址路徑,而接受物件則是 MIME 類型和相關聯副檔名的鍵/值組合。

{
  "name": "Excalidraw",
  "description": "Excalidraw is a whiteboard tool...",
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#000000",
  "background_color": "#ffffff",
  "file_handlers": [
    {
      "action": "/",
      "accept": {
        "application/vnd.excalidraw+json": [".excalidraw"]
      }
    }
  ]
}

下一步是在應用程式啟動時處理檔案。這會在 launchQueue 介面中發生,我需要呼叫 setConsumer() 來設定消費者。這個函式的參數是非同步函式,會接收 launchParams。這個 launchParams 物件有一個名為 files 的欄位,可取得要處理的檔案控制代碼陣列。我只關心第一個,並從這個檔案控制代碼取得 blob,然後傳遞給我們的老朋友 loadFromBlob()。

if ('launchQueue' in window && 'LaunchParams' in window) {
  window as any.launchQueue
    .setConsumer(async (launchParams: { files: any[] }) => {
      if (!launchParams.files.length) return;
      const fileHandle = launchParams.files[0];
      const blob: Blob = await fileHandle.getFile();
      blob.handle = fileHandle;
      loadFromBlob(blob, this.state).then(({ elements, appState }) =>
        // Initialize app state.
      ).catch((error) => {
        this.setState({ isLoading: false, errorMessage: error.message });
      });
    });
}

如果上述內容太快,請參閱我的文章,進一步瞭解 File Handling API。如要啟用檔案處理功能,請設定實驗性網頁平台功能旗標。預計今年稍晚會在 Chrome 中推出。

剪貼簿整合

Excalidraw 還有另一項實用功能,就是整合剪貼簿。我可以將整張繪圖或部分繪圖複製到剪貼簿,也可以視需要加上浮水印,然後貼到其他應用程式。順帶一提,這是 Windows 95 小畫家應用程式的網頁版。

這項功能的運作方式非常簡單。我只需要將畫布做為 blob,然後將含有 blob 的 ClipboardItem 傳遞至 navigator.clipboard.write() 函式,將單一元素陣列寫入剪貼簿。如要進一步瞭解 Clipboard API 的用途,請參閱 Jason 和我的文章。

export const copyCanvasToClipboardAsPng = async (canvas: HTMLCanvasElement) => {
  const blob = await canvasToBlob(canvas);
  await navigator.clipboard.write([
    new window.ClipboardItem({
      'image/png': blob,
    }),
  ]);
};

export const canvasToBlob = async (canvas: HTMLCanvasElement): Promise<Blob> => {
  return new Promise((resolve, reject) => {
    try {
      canvas.toBlob((blob) => {
        if (!blob) {
          return reject(new CanvasError(t('canvasError.canvasTooBig'), 'CANVAS_POSSIBLY_TOO_BIG'));
        }
        resolve(blob);
      });
    } catch (error) {
      reject(error);
    }
  });
};

與他人協作

分享工作階段網址

你知道 Excalidraw 也有協作模式嗎?不同使用者可以共同編輯同一份文件。如要開始新的工作階段,請按一下「即時協作」按鈕,然後啟動工作階段。Excalidraw 整合了 Web Share API,因此我可以輕鬆與協作者分享工作階段網址。

即時協作

我使用 Pixelbook、Pixel 3a 手機和 iPad Pro 編輯 Google I/O 標誌,模擬本機協作工作階段。您可以看到,我在一部裝置上所做的變更會反映在所有其他裝置上。

甚至能看到所有游標移動。Pixelbook 的游標移動穩定,因為它是透過觸控板控制,但 Pixel 3a 手機的游標和 iPad Pro 平板電腦的游標會跳來跳去,因為我是透過手指輕觸來控制這些裝置。

查看協作者狀態

為了提升即時協作體驗,系統甚至會偵測閒置狀態。使用 iPad Pro 時,游標會顯示綠點。當我切換到其他瀏覽器分頁或應用程式時,圓點會變成黑色。當我在 Excalidraw 應用程式中,但沒有執行任何操作時,游標會顯示我處於閒置狀態,並以三個 zZZ 表示。

經常閱讀我們出版品的讀者可能會認為,閒置偵測是透過閒置偵測 API 實現,這是 Project Fugu 早期階段的提案。答案是:不會。雖然我們在 Excalidraw 中採用了以這個 API 為基礎的實作方式,但最後我們決定採用更傳統的方法,根據指標移動和頁面瀏覽權限進行評估。

螢幕截圖:在 WICG Idle Detection 存放區中提交的 Idle Detection 意見回饋。

我們提交了意見回饋,說明 Idle Detection API 為何無法解決我們的用途。所有 Project Fugu API 都是公開開發,因此所有人都能參與並發表意見!

Lipis 談 Excalidraw 的阻礙

說到這裡,我問了 lipis 最後一個問題,詢問他認為網頁平台缺少什麼,導致 Excalidraw 受到限制:

File System Access API 雖然很棒,但你知道嗎?我現在最在意的檔案,大多存放在 Dropbox 或 Google 雲端硬碟,而不是硬碟。我希望 File System Access API 能包含遠端檔案系統供應商 (例如 Dropbox 或 Google) 的抽象層,以便整合,並讓開發人員編寫程式碼。使用者可以放心,知道檔案在信任的雲端服務供應商中安全無虞。

我完全同意 lipis 的看法,我的生活也與雲端服務密不可分。希望這項功能很快就會推出。

分頁應用程式模式

太棒了!我們在 Excalidraw 中看到許多非常棒的 API 整合。檔案系統、檔案處理、剪貼簿、網頁分享和網頁分享目標。但還有一件事。到目前為止,我一次只能編輯一份文件。答案是不需要。歡迎搶先體驗 Excalidraw 的分頁應用程式模式早期版本。看起來會像這樣。

我已在安裝的 Excalidraw PWA 中開啟現有檔案,該 PWA 以獨立模式執行。現在,我在獨立視窗中開啟新分頁。這不是一般的瀏覽器分頁,而是 PWA 分頁。在這個新分頁中,我可以開啟第二個檔案,並在同一個應用程式視窗中獨立處理。

分頁應用程式模式目前仍處於早期階段,尚未完全定案。如有興趣,請務必參閱我的文章,瞭解這項功能的現況。

Closing

如要掌握這項功能和其他功能的最新消息,請務必查看 Fugu API 追蹤工具。我們很高興能推動網路發展,讓您在平台上完成更多工作。希望 Excalidraw 能持續進步,也期待您打造出各種精彩應用程式。前往 excalidraw.com 開始創作。

我迫不及待想看到今天介紹的 API 出現在您的應用程式中。我是 Tom,你可以在 Twitter 和網際網路上找到我,帳號是 @tomayac。感謝收看,希望你喜歡 Google I/O 的其他內容。