Dodaj przycisk „Zapisz na Dysku”

Przycisk „Zapisz na Dysku” umożliwia użytkownikom zapisywanie plików na Dysku z Twojej witryny. Załóżmy na przykład, że w Twojej witrynie znajduje się kilka instrukcji obsługi (w formacie PDF), które użytkownicy mogą pobrać. Przycisk „Zapisz na Dysku” można umieścić obok każdej instrukcji, aby użytkownicy mogli zapisywać je na swoim Dysku.

Gdy użytkownik kliknie przycisk, plik zostanie pobrany ze źródła danych i przesłany na Dysk Google w miarę odbierania danych. Ponieważ pobieranie odbywa się w kontekście przeglądarki użytkownika, ten proces umożliwia użytkownikowi uwierzytelnienie działania polegającego na zapisywaniu plików za pomocą utworzonej sesji przeglądarki.

Obsługiwane przeglądarki

Przycisk „Zapisz na Dysku” jest obsługiwany w tych przeglądarkach.

Dodawanie przycisku „Zapisz na Dysku” do strony

Aby utworzyć instancję przycisku „Zapisz na Dysku”, dodaj do strony ten skrypt:

<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>

Gdzie:

• class to wymagany parametr, który musi mieć wartość g-savetodrive, jeśli używasz standardowego tagu HTML.

• data-src to wymagany parametr zawierający adres URL pliku do zapisania.

  • Adresy URL mogą być bezwzględne lub względne.
  • Adres URL data-src może być obsługiwany z tej samej domeny, subdomeny i protokołu co domena, w której jest hostowany przycisk. Musisz używać zgodnych protokołów na stronie i w źródle danych.
  • Adresy URI danych i adresy URL file:// nie są obsługiwane.
  • Ze względu na zasadę tego samego pochodzenia przeglądarki ten adres URL musi być obsługiwany z tej samej domeny co strona, na której się znajduje, lub musi być dostępny za pomocą współdzielenia zasobów między domenami (CORS). Jeśli przycisk i zasób znajdują się w różnych domenach, zapoznaj się z sekcją Obsługa przycisków i zasobów w różnych domenach.
  • Aby udostępnić plik, gdy ta sama strona jest obsługiwana zarówno przez protokół HTTP, jak i HTTPS, określ zasób bez protokołu, np. data-src="//example.com/files/file.pdf", który używa odpowiedniego protokołu w zależności od sposobu uzyskania dostępu do strony hostującej.

• data-filename to wymagany parametr zawierający nazwę używaną do zapisywania pliku.

• data-sitename to wymagany parametr zawierający nazwę witryny udostępniającej plik.

Te atrybuty możesz umieścić w dowolnym elemencie HTML. Najczęściej używane elementy to jednak div, span lub button. Każdy z tych elementów wyświetla się nieco inaczej podczas wczytywania strony, ponieważ przeglądarka renderuje element, zanim JavaScript „Zapisz na Dysku” ponownie go wyrenderuje.

Ten skrypt musi być wczytywany za pomocą protokołu HTTPS i można go umieścić w dowolnym miejscu na stronie bez ograniczeń. Aby zwiększyć wydajność, możesz też wczytywać skrypt asynchronicznie.

Uwaga: przycisk jest renderowany w tekście. Przycisk "Zapisz na Dysku" można umieścić w innym elemencie, aby początkowy układ był podobny do ostatecznego.

Uwaga: jeśli użytkownik opuści stronę przed zakończeniem pobierania, dane zostaną odrzucone, a na Dysku Google nie zostanie utworzony żaden plik.

Używanie wielu przycisków na stronie

Na tej samej stronie możesz umieścić kilka przycisków „Zapisz na Dysku”. Możesz na przykład umieścić przycisk u góry i u dołu długiej strony.

Jeśli parametry data-src i data-filename są takie same w przypadku kilku przycisków, zapisanie z jednego przycisku spowoduje, że wszystkie podobne przyciski będą wyświetlać te same informacje o postępie. Jeśli klikniesz kilka różnych przycisków, zostaną one zapisane kolejno.

Obsługa przycisków i zasobów w różnych domenach

Jeśli przycisk "Zapisz na Dysku" znajduje się na innej stronie niż źródło danych, żądanie zapisania pliku musi używać współdzielenia zasobów między domenami (CORS) aby uzyskać dostęp do zasobu. CORS to mechanizm umożliwiający aplikacji internetowej w jednej domenie dostęp do zasobów z serwera w innej domenie.

Jeśli na przykład przycisk „Zapisz na Dysku” znajduje się na stronie http://example.com/page.html, a źródło danych jest określone jako data-src="https://otherserver.com/files/file.pdf", przycisk nie będzie mógł uzyskać dostępu do pliku PDF, chyba że przeglądarka będzie mogła użyć CORS do uzyskania dostępu do zasobu.

Adres URL data-src może być obsługiwany z innej domeny, ale odpowiedzi z serwera HTTP muszą obsługiwać żądania HTTP OPTION i zawierać te specjalne nagłówki HTTP:

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

Access-Control-Allow-Origin może mieć wartość *, aby zezwalać na CORS z dowolnej domeny, lub może określać domeny, które mają dostęp do zasobu za pomocą CORS, np. http://example.com/page.html. Jeśli nie masz serwera do hostowania treści, rozważ użycie Google App Engine.

Więcej informacji znajdziesz w dokumentacji serwera na temat włączania CORS z domeny, która obsługuje przycisk „Zapisz na Dysku”. Więcej informacji o włączaniu CORS na serwerze znajdziesz w artykule Chcę dodać obsługę CORS do mojego serwera.

JavaScript API

JavaScript przycisku „Zapisz na Dysku” definiuje 2 funkcje renderowania przycisków w przestrzeni nazw gapi.savetodrive. Jeśli wyłączysz automatyczne renderowanie, musisz wywołać jedną z tych funkcji , ustawiając parsetags na explicit.

Metoda	Opis
gapi.savetodrive.render( container, parameters )	Renderuje określony kontener jako widżet przycisku „Zapisz na Dysku”. container Kontener do renderowania jako przycisk „Zapisz na Dysku”. Określ identyfikator kontenera (ciąg znaków) lub sam element DOM. parameters Obiekt zawierający atrybuty tagu „Zapisz na Dysku” jako pary klucz-wartość bez prefiksów data-. Na przykład, {"src": "//example.com/path/to/myfile.pdf", "filename": "My Statement.pdf", "sitename": "My Company Name"}.
gapi.savetodrive.go( opt_container )	Renderuje wszystkie tagi i klasy „Zapisz na Dysku” w określonym kontenerze. Tej funkcji należy używać tylko wtedy, gdy parsetags ma wartość explicit, co może być konieczne ze względu na wydajność. opt_container Kontener zawierający tagi przycisku „Zapisz na Dysku” do renderowania. Określ identyfikator kontenera (ciąg znaków) lub sam element DOM. Jeśli parametr opt_container zostanie pominięty, zostaną wyrenderowane wszystkie tagi „Zapisz na Dysku” na stronie.

Przykład kodu JavaScript „Zapisz na Dysku” z jawnym wczytywaniem

<!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>

Przykład kodu JavaScript „Zapisz na Dysku” z jawnym renderowaniem

    <!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>

Lokalizowanie przycisku „Zapisz na Dysku”

Jeśli Twoja strona obsługuje określony język, ustaw zmienną window.___gcfg.lang na ten język. Jeśli nie ustawisz tej zmiennej, zostanie użyty język Dysku Google użytkownika.

Dostępne wartości kodu języka znajdziesz na liście obsługiwanych kodów języka.

    <!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>

Rozwiązywanie problemów

Jeśli podczas pobierania adresu URL data-src wystąpi błąd XHR, sprawdź, czy zasób rzeczywiście istnieje i czy nie występuje problem z CORS.

Jeśli duże pliki są obcinane do 2 MB, prawdopodobnie serwer nie udostępnia nagłówka Content-Range, co może być spowodowane problemem z CORS.