新增「儲存至雲端硬碟」按鈕(&A)

使用者可透過「儲存至雲端硬碟」按鈕，將網站上的檔案儲存到雲端硬碟。舉例來說，假設你的網站列出數項操作說明手冊 (PDF)，讓使用者下載。「儲存至雲端硬碟」按鈕可與其他手動操作並排放置，讓使用者將手冊儲存到「我的雲端硬碟」中。

當使用者按一下按鈕，檔案就會從資料來源下載，並在收到資料時上傳至 Google 雲端硬碟。由於下載作業是在使用者的瀏覽器中進行，因此這個程序可讓使用者透過已建立的瀏覽器工作階段來驗證要儲存檔案的動作。

支援的瀏覽器

「儲存至雲端硬碟」按鈕支援這些瀏覽器。

在頁面新增「儲存至雲端硬碟」按鈕

如要建立「儲存至雲端硬碟」按鈕的執行個體，請在您的網頁中加入下列指令碼：

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div class="g-savetodrive"
   data-src="//example.com/path/to/myfile.pdf"
   data-filename="My Statement.pdf"
   data-sitename="My Company Name">
</div>

在此情況下：

  • 如果您使用的是標準 HTML 標記，則必須將 class 設為 g-savetodrive。

  • data-src 是必要參數，包含要儲存的檔案網址。

    • 可以使用絕對網址或相對網址。
    • 系統可透過與代管按鈕所在網域相同的網域、子網域和通訊協定提供 data-src 網址。您必須在網頁與資料來源之間使用相符的通訊協定。
    • 不支援資料 URI 和 file:// 網址。
    • 由於瀏覽器採用的來源政策，這個網址的來源網域必須與其所在網頁相同，或使用跨源資源共享 (CORS) 存取。如果按鈕和資源位於不同網域，請參閱處理不同網域的按鈕和資源 (#domain)。
    • 如要在透過 http 和 https 提供相同頁面時提供檔案，請指定不包含通訊協定的資源，例如 data-src="//example.com/files/file.pdf"。這類通訊協定會根據代管頁面存取的方式，使用合適的通訊協定。

  • data-filename 是必要參數，其中包含儲存檔案所使用的名稱。

  • data-sitename 是必要參數，其中包含提供檔案的網站名稱。

您可以將這些屬性放在任何 HTML 元素上。不過，最常用的元素是 div、span 或 button。這些元素在網頁載入時的顯示方式會有些微不同，這是因為瀏覽器會在「儲存至雲端硬碟」JavaScript 重新轉譯元素前轉譯元素。

這個指令碼必須使用 HTTPS 通訊協定載入，且可從網頁上的任何時間點加入，不受限制。您也可以透過非同步方式載入指令碼，以改善效能。

在單一頁面上使用多個按鈕

您可以在同一個頁面上放置多個「儲存至雲端硬碟」按鈕。舉例來說，您可能會在長頁的頂端和底部各有一個按鈕。

如果多個按鈕的 data-src 和 data-filename 參數相同，儲存一個按鈕時，所有類似的按鈕都會顯示相同的進度資訊。如果按下多個不同的按鈕，這些按鈕將依序儲存。

處理不同網域中的按鈕和資源

如果「儲存至雲端硬碟」按鈕位於資料來源以外的其他頁面，儲存檔案的要求必須使用跨源資源共享 (CORS) 存取資源。CORS 是一種允許某個網域的網頁應用程式存取其他網域伺服器資源的機制。

舉例來說，如果「儲存至雲端硬碟」按鈕位於 http://example.com/page.html 的頁面上，且資料來源指定為 data-src="https://otherserver.com/files/file.pdf"，則除非瀏覽器可使用 CORS 存取資源，否則按鈕將無法存取 PDF。

data-src 網址可從其他網域提供，但 HTTP 伺服器的回應需要支援 HTTP OPTION 要求並包含下列特殊 HTTP 標頭：

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Range
Access-Control-Expose-Headers: Cache-Control, Content-Encoding, Content-Range

Access-Control-Allow-Origin 的值可設為 *，允許來自任何網域的 CORS，也可以使用 CORS 指定可存取資源的網域，例如 http://example.com/page.html。如果您沒有可代管內容的伺服器，請考慮使用 Google App Engine。

詳情請參閱伺服器說明文件，瞭解如何在「儲存至雲端硬碟」按鈕提供的來源中啟用 CORS。如要進一步瞭解如何為 CORS 啟用伺服器，請參閱「我要將 CORS 支援新增至我的伺服器」一文。

JavaScript API

「儲存至雲端硬碟」按鈕 JavaScript 會在 gapi.savetodrive 命名空間定義兩個按鈕算繪函式。如果您停用自動轉譯功能，則必須將 parsetags 設為 explicit，以呼叫其中一個函式。

方法 說明
gapi.savetodrive.render(
container,
parameters
)		 將指定的容器顯示為「儲存至雲端硬碟」按鈕小工具。
容器
轉譯為「儲存至雲端硬碟」按鈕的容器。指定容器 (字串) 或 DOM 元素本身的 ID。
參數
以「鍵=值組合」的形式包含「儲存至雲端硬碟」標記屬性的物件，不含 data- 前置字元。 例如：{"src": "//example.com/path/to/myfile.pdf", "filename": "My Statement.pdf", "sitename": "My Company Name"}。
gapi.savetodrive.go(
opt_container
)		 轉譯指定容器中的所有「儲存至雲端硬碟」標記和類別。 只有在 parsetags 設為 explicit 時，您才應使用這個函式。這會基於效能考量而這麼做。
opt_container
包含要轉譯的「儲存至雲端硬碟」按鈕標記的容器。指定容器 (字串) 或 DOM 元素本身的 ID。如果省略 opt_container 參數，網頁中所有「儲存至雲端硬碟」標記都會轉譯。

明確載入的「儲存至雲端硬碟」JavaScript 範例

<!DOCTYPE html>
    <html>
      <head>
        <title>Save to Drive Demo: Explicit Load</title>
        <link rel="canonical" href="http://www.example.com">
        <script src="https://apis.google.com/js/platform.js" async defer>
          {parsetags: 'explicit'}
        </script>
      </head>
      <body>
        <div id="container">
          <div class="g-savetodrive"
             data-src="//example.com/path/to/myfile.pdf"
             data-filename="My Statement.pdf"
             data-sitename="My Company Name">
          <div>
        </div>
        <script type="text/javascript">
          gapi.savetodrive.go('container');
        </script>
      </body>
    </html>

明確轉譯的「儲存至雲端硬碟」JavaScript 範例

    <!DOCTYPE html>
    <html>
      <head>
        <title>Save to Drive Demo: Explicit Render</title>
        <link rel="canonical" href="http://www.example.com">
        <script>
          window.___gcfg = {
            parsetags: 'explicit'
          };
        </script>
        <script src="https://apis.google.com/js/platform.js" async defer></script>
      </head>
      <body>
        <a href="javascript:void(0)" id="render-link">Render the Save to Drive button</a>
        <div id="savetodrive-div"></div>
        <script>
          function renderSaveToDrive() {
            gapi.savetodrive.render('savetodrive-div', {
              src: '//example.com/path/to/myfile.pdf',
              filename: 'My Statement.pdf',
              sitename: 'My Company Name'
            });
          }
          document.getElementById('render-link').addEventListener('click', renderSaveToDrive);
        </script>
      </body>
    </html>

將「儲存至雲端硬碟」按鈕本地化

如果您的網頁支援特定語言，請將 window.___gcfg.lang 變數設為該語言。如未設定，則會使用使用者的 Google 雲端硬碟語言。

如需可用的語言代碼值，請參閱支援的語言代碼清單。

    <!DOCTYPE html>
    <html>
      <head>
        <title>Save to Drive Demo: Async Load with Language</title>
        <link rel="canonical" href="http://www.example.com">
      </head>
      <body>
        <div class="g-savetodrive"
             data-src="//example.com/path/to/myfile.pdf"
             data-filename="My Statement.pdf"
             data-sitename="My Company Name">
        </div>

        <script type="text/javascript">
          window.___gcfg = {
            lang: 'en-US'
          };
        </script>
        <script src = 'https://apis.google.com/js/platform.js' async defer></script>

      </body>
    </html>

疑難排解

如果您在下載 data-src 網址時收到 XHR 錯誤，請確認該資源確實存在，而且您沒有 CORS 問題。

如果大型檔案遭截斷至 2 MB，可能是因為伺服器並未公開 Content-Range，進而發生 CORS 問題。