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ć instrukcje na Moim dysku.

Gdy użytkownik kliknie przycisk, plik zostanie pobrany ze źródła danych i przesłany na Dysk Google po odebraniu danych. Pobieranie odbywa się w kontekście przeglądarki użytkownika, więc ten proces umożliwia użytkownikowi uwierzytelnienie działania polegającego na zapisywaniu plików przy użyciu ustanowionej sesji przeglądarki.

Obsługiwane przeglądarki

Przycisk „Zapisz na Dysku” obsługuje te przeglądarki.

Dodawanie przycisku „Zapisz na Dysku” do strony

Aby utworzyć instancję przycisku „Zapisz na Dysku”, dodaj do swojej strony internetowej 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ć wyświetlany z tej samej domeny, subdomeny i protokołu co domena, w której hostowany jest przycisk. Musisz używać pasujących protokołów między stroną a źródłem danych.
  • Identyfikatory URI danych i adresy URL file:// nie są obsługiwane.
  • Ze względu na zasady przeglądarki dotyczące tej samej domeny ten adres URL musi być obsługiwany z tej samej domeny co strona, na której się znajduje, lub być dostępny za pomocą współdzielenia zasobów pomiędzy serwerami z różnych domen (CORS). Jeśli przycisk i zasób znajdują się w różnych domenach, zapoznaj się z artykułem Obsługa przycisków i zasobów w różnych domenach (#domain).
  • Aby plik był wyświetlany, gdy ta sama strona jest wyświetlana zarówno przez 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 na podstawie sposobu uzyskania dostępu do strony hostującej.

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

• data-sitename to wymagany parametr zawierający nazwę witryny, która udostępnia plik.

Możesz umieścić te atrybuty 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” wyrenderuje go ponownie.

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

Uwaga: przycisk jest renderowany w tekście. Przycisk „Zapisz na Dysku” można umieścić w innym elemencie, aby początkowy układ wyglądał podobnie do końcowego.

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

Używanie wielu przycisków na stronie

Na tej samej stronie możesz umieścić wiele 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 dla wielu przycisków, zapisanie z jednego przycisku spowoduje, że wszystkie podobne przyciski będą wyświetlać te same informacje o postępach. Jeśli klikniesz kilka różnych przycisków, zostaną one zapisane po kolei.

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 serwerami z różnych domen (CORS), aby uzyskać dostęp do zasobu. CORS to mechanizm, który umożliwia 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 może używać 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 przez 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 o tym, jak włączyć CORS z punktu początkowego, który obsługuje przycisk „Zapisz na Dysku”, znajdziesz w dokumentacji serwera. Więcej informacji o włączaniu mechanizmu CORS na serwerze znajdziesz w artykule I want to add CORS support to my server (Chcę dodać obsługę mechanizmu CORS na serwerze).

JavaScript API

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

Metoda	Opis
gapi.savetodrive.render( container, parameters )	Renderuje określony kontener jako widżet przycisku „Zapisz na Dysku”. kontener Kontener, który ma być renderowany jako przycisk „Zapisz na Dysku”. Podaj identyfikator kontenera (ciąg znaków) lub sam element DOM. parametry 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 parametr 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 wyrenderowania. Podaj 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ładowy kod JavaScript „Zapisz na Dysku” z wyraźnym 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ładowy kod JavaScript „Zapisz na Dysku” z wyraźnym 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 internetowa obsługuje określony język, ustaw zmienną window.___gcfg.lang na ten język. Jeśli nie zostanie ustawiony, używany będzie język Dysku Google użytkownika.

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

    <!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 masz problemu 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.