添加“保存到云端硬盘”按钮

通过“保存到云端硬盘”按钮,用户可以将文件从您的网站保存到云端硬盘。例如,假设您的网站列出了几份说明手册 (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 元素上。但最常用的元素是 divspanbutton。在网页加载时,其中每个元素的显示效果略有不同,因为浏览器会先渲染这些元素,然后“保存到云端硬盘”JavaScript 才会重新渲染这些元素。

此脚本必须使用 HTTPS 协议加载,并且可以从网页上的任何位置不受限制。您也可异步加载脚本以提高性能。

在一个页面上使用多个按钮

您可以在同一页面上放置多个“保存到云端硬盘”按钮。例如,您可以在长页面的顶部和底部放置一个按钮。

如果多个按钮的 data-srcdata-filename 参数相同,则从一个按钮保存会导致所有类似的按钮显示相同的进度信息。如果点击多个不同的按钮,系统会按顺序保存这些按钮。

处理不同网域中的按钮和资源

如果“保存到云端硬盘”按钮与数据源位于不同页面上,则保存文件的请求必须使用跨域资源共享 (CORS) 来访问资源。CORS 是一种机制,可让一个网域中的 Web 应用访问位于另一个网域中的服务器的资源。

例如,如果在位于 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
)
将指定容器渲染为“保存到云端硬盘”按钮 widget。
容器
要呈现为“保存到云端硬盘”按钮的容器。 指定容器(字符串)的 ID 或 DOM 元素本身。
形参
一个对象,包含“保存到云端硬盘”标记属性(作为键值对,不带 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
包含要呈现的“保存到云端硬盘”按钮标记的容器。 指定容器(字符串)的 ID 或 DOM 元素本身。如果省略 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 问题。

如果大型文件被截断为 2MB,则可能是因为您的服务器未公开 Content-Range,而这有可能是 CORS 问题。