From 074785cea106179cb3305637055ab0a009ca74f2 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:42:52 -0500 Subject: initial commit --- .../client-side_storage/index.html | 794 +++++++++++++++++++++ .../client-side_web_apis/fetching_data/index.html | 379 ++++++++++ .../javascript/client-side_web_apis/index.html | 53 ++ .../client-side_web_apis/introduction/index.html | 277 +++++++ .../manipulating_documents/index.html | 321 +++++++++ .../third_party_apis/index.html | 482 +++++++++++++ 6 files changed, 2306 insertions(+) create mode 100644 files/ru/learn/javascript/client-side_web_apis/client-side_storage/index.html create mode 100644 files/ru/learn/javascript/client-side_web_apis/fetching_data/index.html create mode 100644 files/ru/learn/javascript/client-side_web_apis/index.html create mode 100644 files/ru/learn/javascript/client-side_web_apis/introduction/index.html create mode 100644 files/ru/learn/javascript/client-side_web_apis/manipulating_documents/index.html create mode 100644 files/ru/learn/javascript/client-side_web_apis/third_party_apis/index.html (limited to 'files/ru/learn/javascript/client-side_web_apis') diff --git a/files/ru/learn/javascript/client-side_web_apis/client-side_storage/index.html b/files/ru/learn/javascript/client-side_web_apis/client-side_storage/index.html new file mode 100644 index 0000000000..114e7821a1 --- /dev/null +++ b/files/ru/learn/javascript/client-side_web_apis/client-side_storage/index.html @@ -0,0 +1,794 @@ +--- +title: Client-side storage +slug: Learn/JavaScript/Client-side_web_APIs/Client-side_storage +translation_of: Learn/JavaScript/Client-side_web_APIs/Client-side_storage +--- +

{{LearnSidebar}}

+ +
{{PreviousMenu("Learn/JavaScript/Client-side_web_APIs/Video_and_audio_APIs", "Learn/JavaScript/Client-side_web_APIs")}}
+ +
+ +

Современные веб-браузеры поддерживают несколько способов хранения данных из веб-сайтов на компьютере пользователя - с разрешения пользователя - чтобы потом получать их, когда это необходимо. Это позволяет долгосрочно хранить данные, сохранять сайты или документы для использования без подключения к сети, сохранять пользовательские настройки для вашего сайта и многое другое. В этой статье объясняются основы того, как это все работает.

+ + + + + + + + + + + + +
Что нужно знать:JavaScript basics (see first steps, building blocks, JavaScript objects), the basics of Client-side APIs
Цель статьи:To learn how to use client-side storage APIs to store application data.
+ +

Хранение данных на стороне клиента?

+ +

Ранее, мы говорили о разнице между статическими и динамическими сайтами. Большинство современных веб-сайтов являются динамическими - они хранят данные на сервере, используя какую-то базу данных (серверное хранилище), а затем запускают код на стороне сервера чтобы извлечь необходимые данные, вставить их в шаблоны статических страниц и передать полученный HTML-код клиенту для отображения в браузере пользователя.

+ +

Хранилище на стороне клиента работает по схожим принципам, но используется по-другому. Оно состоит из API-интерфейсов JavaScript, которые позволяют вам хранить данные на клиенте (то есть на компьютере пользователя), а затем извлекать их при необходимости. Это имеет много разных применений, таких как:

+ + + +

Часто, хранилища на сторонах клиента и сервера используются совместно. К примеру, вы должны загрузить из базы данных пакет музыкальных файлов для веб-игры, или музыкальный плеер хранит их в базе данных на стороне клиента, и воспроизводит по мере необходимости.

+ +

Пользователь должен будет загрузить музыкальные файлы только один раз - при последующих посещениях они будут извлечены из локальной базы данных.

+ +
+

Примечание. Существуют ограничения на объем данных, которые вы можете хранить с помощью API-интерфейсов на стороне клиента (возможно, как для отдельных API, так и в совокупности). Точный лимит варьируется в зависимости от браузера и, возможно, в зависимости от пользовательских настроек. Смотри Ограничения хранилища браузера и критерии переполнения для большей информации.

+
+ +

Старый подход: куки

+ +

Концепция хранения на стороне клиента существует уже давно. С первых дней Интернета, использовали cookies для хранения информации, чтобы персонализировать пользовательский опыт на веб-сайтах. Это самая ранняя форма хранилища на стороне клиента, обычно используемая в Интернете.

+ +

Из-за этого возраста существует ряд проблем - как технических, так и с точки зрения пользовательского опыта - связанных с файлами cookie. Эти проблемы настолько значительны, что при первом посещении сайта людям, живущим в Европе, показываются сообщения, информирующие их о том, будут ли они использовать файлы cookie для хранения данных о них. Это связано с частью законодательства Европейского Союза, известного как  EU Cookie directive.

+ +

+ +

По этим причинам мы не будем учить вас, как использовать куки в этой статье. Они устарели, у них множество проблем с безопастностью, и неспособны хранить сложные данные. При этом существуют лучшие, более современные, способы хранения более широкого спектра данных на компьютере пользователя.

+ +

Единственным преимуществом файлов cookie является то, что они поддерживаются очень старыми браузерами, поэтому, если ваш проект требует, чтобы вы поддерживали устаревшие браузеры (например, Internet Explorer 8 или более ранние версии), файлы cookie могут по-прежнему быть полезными, но для большинства проектов вы не нужно больше прибегать к ним.

+ +
+

Почему по-прежнему создаются новые сайты с использованием файлов cookie? Это происходит главным образом из-за привычек разработчиков, использования старых библиотек, которые всё ещё используют куки-файлы, и наличия множества веб-сайтов, предоставляющих устаревшие справочные и учебные материалы для обучения хранению данных.

+
+ +

Новый подход: Web Storage и IndexedDB

+ +

Современные браузеры имеют гораздо более простые и эффективные API для хранения данных на стороне клиента, чем при использовании файлов cookie.

+ + + +

Вы узнаете больше об этих API ниже.

+ +

Что нас ждёт в будущем: Cache API

+ +

Некоторые современные браузеры поддерживают новое {{domxref("Cache")}} API. Этот API предназначен для хранения HTTP-ответов на конкретные запросы и очень полезен для таких вещей, как хранение ресурсов сайта в автономном режиме, чтобы впоследствии сайт можно было использовать без сетевого подключения. Cache обычно используется в сочетании с Service Worker API, однако это не обязательно.

+ +

Использование Cache и Service Workers - сложная тема, и мы не будем подробно останавливаться на ней в этой статье, хотя приведем простой пример {{anch("Offline asset storage")}} в разделе ниже.

+ +

Хранение простых данных — web storage

+ +

Web Storage API очень легко использовать — вы храните простые пары данных имя/значение (только строки, цифры и т.п.) и получаете их, когда необходимо.

+ +

Базовый синтаксис

+ +

Посмотрите:

+ +
    +
  1. +

    Во-первых, посмотрите наши web storage шаблоны на GitHub (откройте в новой вкладке).

    +
    2. +
  2. +

    Откройте консоль инструментов JavaScript разработчика вашего браузера.

    +
    3. +
  3. +

    Все данные вашего веб-хранилища содержатся в двух объектоподобных структурах внутри браузера: {{domxref("Window.sessionStorage", "sessionStorage")}} и {{domxref("Window.localStorage", "localStorage")}}. Первый сохраняет данные до тех пор, пока браузер открыт (данные теряются при закрытии браузера), а второй сохраняет данные даже после того, как браузер закрыт, а затем снова открыт. Мы будем использовать второй в этой статье, так как он, как правило, более полезен.

    + +

    {{domxref("Storage.setItem()")}} метод позволяет сохранить элемент данных в хранилище - он принимает два параметра: имя элемента и его значение. Попробуйте ввести это в свою консоль JavaScript (измените значение на свое собственное имя, если хотите!):

    + + 
    localStorage.setItem('name','Chris');
    +
    4. +
  4. +

    {{domxref("Storage.getItem()")}} метод принимает один параметр - имя элемента данных, который вы хотите получить - и возвращает значение элемента. Теперь введите эти строки в вашу консоль JavaScript:

    + + 
    var myName = localStorage.getItem('name');
+myName
    + +

    После ввода во второй строке вы должны увидеть, что переменная myName теперь содержит значение элемента данных name.

    +
    5. +
  5. +

    {{domxref("Storage.removeItem()")}} метод принимает один параметр - имя элемента данных, который вы хотите удалить, - и удаляет этот элемент из веб-хранилища. Введите следующие строки в вашу консоль JavaScript:

    + + 
    localStorage.removeItem('name');
+var myName = localStorage.getItem('name');
+myName
    + +

    Третья строка должна теперь возвращать ноль - элемент name больше не существует в веб-хранилище.

    +
    6. +
+ +

Данные сохраняются!

+ +

Одной из ключевых особенностей веб-хранилища является то, что данные сохраняются между загрузками страниц (и даже в случае закрытия браузера, в случае localStorage). Давайте посмотрим на это в действии.

+ +
    +
  1. +

    Снова откройте пустой шаблон нашего веб-хранилища, но на этот раз в другом браузере, отличном от того, в котором вы открыли этот учебник! Так будет удобнее.

    +
    2. +
  2. +

    Введите эти строки в консоль JavaScript браузера:

    + + 
    localStorage.setItem('name','Chris');
+var myName = localStorage.getItem('name');
+myName
    + +

    Вы должны увидеть возвращенное имя элемента.

    +
    3. +
  3. +

    Теперь закройте браузер и откройте его снова.

    +
    4. +
  4. +

    Введите следующий код:

    + + 
    var myName = localStorage.getItem('name');
+myName
    + +

    Вы должны увидеть, что значение всё ещё доступно, даже после закрытия / открытия браузера.

    +
    5. +
+ +

Для каждого домена отдельное хранилище

+ +

Существуют отдельные хранилища данных для каждого домена (каждый отдельный веб-адрес загружается в браузер). Вы увидите, что если вы загрузите два веб-сайта (например, google.com и amazon.com) и попытаетесь сохранить элемент на одном веб-сайте, он не будет доступен для другого веб-сайта.

+ +

Это имеет смысл - вы можете представить себе проблемы безопасности, которые могут возникнуть, если веб-сайты смогут видеть данные друг друга!

+ +

Более развернутый пример

+ +

Давайте применим эти новые знания, написав простой рабочий пример, чтобы дать вам представление о том, как можно использовать веб-хранилище. Наш пример позволит вам ввести имя, после чего страница обновится, чтобы дать вам персональное приветствие. Это состояние также будет сохраняться при перезагрузке страницы / браузера, поскольку имя хранится в веб-хранилище.

+ +

Вы можете найти пример HTML на personal-greeting.html — он содержит простой веб-сайт с заголовком, контентом и нижним колонтитулом, а также форму для ввода вашего имени.

+ +

+ +

Давайте создадим пример, чтобы вы могли понять, как он работает.

+ +
    +
  1. +

    Во-первых, сделайте локальную копию нашего  personal-greeting.html файла в новом каталоге на вашем компьютере.

    +
    2. +
  2. +

    Далее обратите внимание, как наш HTML ссылается на файл JavaScript с именем index.js (см. строку 40). Нам нужно создать его, и записать в него наш код JavaScript. Создайте файл index.js в том же каталоге, что и ваш HTML-файл.

    +
    3. +
  3. +

    Мы начнем с создания ссылок на все функции HTML, которыми мы должны манипулировать в этом примере - мы создадим их все как константы, поскольку эти ссылки не нужно изменять в жизненном цикле приложения. Добавьте следующие строки в ваш файл JavaScript:

    + + 
    // create needed constants
+const rememberDiv = document.querySelector('.remember');
+const forgetDiv = document.querySelector('.forget');
+const form = document.querySelector('form');
+const nameInput = document.querySelector('#entername');
+const submitBtn = document.querySelector('#submitname');
+const forgetBtn = document.querySelector('#forgetname');
+
+const h1 = document.querySelector('h1');
+const personalGreeting = document.querySelector('.personal-greeting');
    +
    4. +
  4. +

    Далее нам нужно включить небольшой прослушиватель событий, чтобы форма фактически не отправляла себя при нажатии кнопки отправки, так как это не то поведение, которое нам нужно. Добавьте этот фрагмент ниже вашего предыдущего кода:

    + + 
    // Stop the form from submitting when a button is pressed
+form.addEventListener('submit', function(e) {
+  e.preventDefault();
+});
    +
    5. +
  5. +

    Теперь нам нужно добавить прослушиватель событий, функция-обработчик которого будет запускаться при нажатии кнопки «Say hello». В комментариях подробно объясняется, что делает каждый бит, но в сущности здесь мы берем имя, которое пользователь ввел в поле ввода текста, и сохраняем его в веб-хранилище с помощью setItem(), затем запускаем функцию nameDisplayCheck(), которая будет обрабатывать обновление фактического текста сайта. Добавьте это в конец: 

    + + 
    // run function when the 'Say hello' button is clicked
+submitBtn.addEventListener('click', function() {
+  // store the entered name in web storage
+  localStorage.setItem('name', nameInput.value);
+  // run nameDisplayCheck() to sort out displaying the
+  // personalized greetings and updating the form display
+  nameDisplayCheck();
+});
    +
    6. +
  6. +

    На этом этапе нам также необходим прослушиватель событий для запуска функции при нажатии кнопки «Forget» — она будет отображена только после того как кнопка «Say hello» будет нажата (две формы состояния для переключения между ними). В этой функции мы удаляем переменную name из веб-хранилища используя removeItem(), затем снова запускаем nameDisplayCheck() для обновления. Добавьте этот код в конец:

    + + 
    // run function when the 'Forget' button is clicked
+forgetBtn.addEventListener('click', function() {
+  // Remove the stored name from web storage
+  localStorage.removeItem('name');
+  // run nameDisplayCheck() to sort out displaying the
+  // generic greeting again and updating the form display
+  nameDisplayCheck();
+});
    +
    7. +
  7. +

    Самое время для определения самой функции nameDisplayCheck(). Здесь мы проверяем была ли переменная name сохранена в веб-хранилище с помощью localStorage.getItem('name') в качестве условия. Если переменная name была сохранена, то вызов вернёт - true; если же нет, то - false. Если true, мы показываем персональное приветствие, отображаем кнопку «Forget», и скрываем кнопку «Say hello». Если же false, мы отображаем общее приветствие и делаем обратное. Опять же, добавьте следующий код в конец:

    + + 
    // define the nameDisplayCheck() function
+function nameDisplayCheck() {
+  // check whether the 'name' data item is stored in web Storage
+  if(localStorage.getItem('name')) {
+    // If it is, display personalized greeting
+    let name = localStorage.getItem('name');
+    h1.textContent = 'Welcome, ' + name;
+    personalGreeting.textContent = 'Welcome to our website, ' + name + '! We hope you have fun while you are here.';
+    // hide the 'remember' part of the form and show the 'forget' part
+    forgetDiv.style.display = 'block';
+    rememberDiv.style.display = 'none';
+  } else {
+    // if not, display generic greeting
+    h1.textContent = 'Welcome to our website ';
+    personalGreeting.textContent = 'Welcome to our website. We hope you have fun while you are here.';
+    // hide the 'forget' part of the form and show the 'remember' part
+    forgetDiv.style.display = 'none';
+    rememberDiv.style.display = 'block';
+  }
+}
    +
    8. +
  8. +

    Последнее но не менее важное, нам необходимо запускать функцию nameDisplayCheck() при каждой загрузке страницы. Если мы не сделаем этого, персональное приветствие не будет сохранятся после перезагрузки страницы. Добавьте следующий фрагмент в конец вашего кода:

    + + 
    document.body.onload = nameDisplayCheck;
    +
    9. +
+ +

Ваш пример закончен — отличная работа! Всё что теперь осталось это сохранить ваш код и протестировать вашу HTML страницу в браузере. Вы можете посмотреть нашу завершённую версию работающую здесь.

+ +
+

Есть и другой, немного более комплексный пример описываемый в Using the Web Storage API.

+
+ +

Храним более сложную информацию в IndexedDB

+ +

IndexedDB API (иногда сокращают до IDB) это полная база данных, доступная в браузере, в которой вы можете хранить сложные связанные данные, типы которых не ограничиваются простыми значениями, такими как строки или числа.

+ +

Вы можете сохранить видео, фото, и почти все остальные файлы с IndexedDB. 

+ +

Однако это обходится дорого: IndexedDB гораздо сложнее в использовании, чем Web Storage API.

+ +

В этом разделе мы действительно только коснемся того, на что он способен, но мы дадим вам достаточно, чтобы начать.

+ +

Работа с примером хранения заметок

+ +

Here we'll run you through an example that allows you to store notes in your browser and view and delete them whenever you like, getting you to build it up for yourself and explaining the most fundamental parts of IDB as we go along.

+ +

The app looks something like this:

+ +

+ +

Each note has a title and some body text, each individually editable. The JavaScript code we'll go through below has detailed comments to help you understand what's going on.

+ +

Предустановка

+ +
    +
  1. First of all, make local copies of our index.html, style.css, and index-start.js files into a new directory on your local machine.
    2. +
  2. Have a look at the files. You'll see that the HTML is pretty simple: a web site with a header and footer, as well as a main content area that contains a place to display notes, and a form for entering new notes into the database. The CSS provides some simple styling to make it clearer what is going on. The JavaScript file contains five declared constants containing references to the {{htmlelement("ul")}} element the notes will be displayed in, the title and body {{htmlelement("input")}} elements, the {{htmlelement("form")}} itself, and the {{htmlelement("button")}}.
    3. +
  3. Rename your JavaScript file to index.js. You are now ready to start adding code to it.
    4. +
+ +

Настраиваем базу данных

+ +

Now let's look at what we have to do in the first place, to actually set up a database.

+ +
    +
  1. +

    Below the constant declarations, add the following lines:

    + + 
    // Create an instance of a db object for us to store the open database in
+let db;
    + +

    Here we are declaring a variable called db — this will later be used to store an object representing our database. We will use this in a few places, so we've declared it globally here to make things easier.

    +
    2. +
  2. +

    Next, add the following to the bottom of your code:

    + + 
    window.onload = function() {
+
+};
    + +

    We will write all of our subsequent code inside this window.onload event handler function, called when the window's {{event("load")}} event fires, to make sure we don't try to use IndexedDB functionality before the app has completely finished loading (it could fail if we don't).

    +
    3. +
  3. +

    Inside the window.onload handler, add the following:

    + + 
    // Open our database; it is created if it doesn't already exist
+// (see onupgradeneeded below)
+let request = window.indexedDB.open('notes', 1);
    + +

    This line creates a request to open version 1 of a database called notes. If this doesn't already exist, it will be created for you by subsequent code. You will see this request pattern used very often throughout IndexedDB. Database operations take time. You don't want to hang the browser while you wait for the results, so database operations are {{Glossary("asynchronous")}}, meaning that instead of happening immediately, they will happen at some point in the future, and you get notified when they're done.

    + +

    To handle this in IndexedDB, you create a request object (which can be called anything you like — we called it request so it is obvious what it is for). You then use event handlers to run code when the request completes, fails, etc., which you'll see in use below.

    + +
    +

    Note: The version number is important. If you want to upgrade your database (for example, by changing the table structure), you have to run your code again with an increased version number, different schema specified inside the onupgradeneeded handler (see below), etc. We won't cover upgrading databases in this simple tutorial.

    +
    +
    4. +
  4. +

    Now add the following event handlers just below your previous addition — again inside the window.onload handler:

    + + 
    // onerror handler signifies that the database didn't open successfully
+request.onerror = function() {
+  console.log('Database failed to open');
+};
+
+// onsuccess handler signifies that the database opened successfully
+request.onsuccess = function() {
+  console.log('Database opened successfully');
+
+  // Store the opened database object in the db variable. This is used a lot below
+  db = request.result;
+
+  // Run the displayData() function to display the notes already in the IDB
+  displayData();
+};
    + +

    The {{domxref("IDBRequest.onerror", "request.onerror")}} handler will run if the system comes back saying that the request failed. This allows you to respond to this problem. In our simple example, we just print a message to the JavaScript console.

    + +

    The {{domxref("IDBRequest.onsuccess", "request.onsuccess")}} handler on the other hand will run if the request returns successfully, meaning the database was successfully opened. If this is the case, an object representing the opened database becomes available in the {{domxref("IDBRequest.result", "request.result")}} property, allowing us to manipulate the database. We store this in the db variable we created earlier for later use. We also run a custom function called displayData(), which displays the data in the database inside the {{HTMLElement("ul")}}. We run it now so that the notes already in the database are displayed as soon as the page loads. You'll see this defined later on.

    +
    5. +
  5. +

    Finally for this section, we'll add probably the most important event handler for setting up the database: {{domxref("IDBOpenDBRequest.onupgradeneeded", "request.onupdateneeded")}}. This handler runs if the database has not already been set up, or if the database is opened with a bigger version number than the existing stored database (when performing an upgrade). Add the following code, below your previous handler:

    + + 
    // Setup the database tables if this has not already been done
+request.onupgradeneeded = function(e) {
+  // Grab a reference to the opened database
+  let db = e.target.result;
+
+  // Create an objectStore to store our notes in (basically like a single table)
+  // including a auto-incrementing key
+  let objectStore = db.createObjectStore('notes', { keyPath: 'id', autoIncrement:true });
+
+  // Define what data items the objectStore will contain
+  objectStore.createIndex('title', 'title', { unique: false });
+  objectStore.createIndex('body', 'body', { unique: false });
+
+  console.log('Database setup complete');
+};
    + +

    This is where we define the schema (structure) of our database; that is, the set of columns (or fields) it contains. Here we first grab a reference to the existing database from e.target.result (the event target's result property), which is the request object. This is equivalent to the line db = request.result; inside the onsuccess handler, but we need to do this separately here because the onupgradeneeded handler (if needed) will run before the onsuccess handler, meaning that the db value wouldn't be available if we didn't do this.

    + +

    We then use {{domxref("IDBDatabase.createObjectStore()")}} to create a new object store inside our opened database. This is equivalent to a single table in a conventional database system. We've given it the name notes, and also specified an autoIncrement key field called id — in each new record this will automatically be given an incremented value — the developer doesn't need to set this explicitly. Being the key, the id field will be used to uniquely identify records, such as when deleting or displaying a record.

    + +

    We also create two other indexes (fields) using the {{domxref("IDBObjectStore.createIndex()")}} method: title (which will contain a title for each note), and body (which will contain the body text of the note).

    +
    6. +
+ +

So with this simple database schema set up, when we start adding records to the database each one will be represented as an object along these lines:

+ +
{
+  title: "Buy milk",
+  body: "Need both cows milk and soya.",
+  id: 8
+}
+ +

Добавляем данные в базу данных

+ +

Now let's look at how we can add records to the database. This will be done using the form on our page.

+ +

Below your previous event handler (but still inside the window.onload handler), add the following line, which sets up an onsubmit handler that runs a function called addData() when the form is submitted (when the submit {{htmlelement("button")}} is pressed leading to a successful form submission):

+ +
// Create an onsubmit handler so that when the form is submitted the addData() function is run
+form.onsubmit = addData;
+ +

Now let's define the addData() function. Add this below your previous line:

+ +
// Define the addData() function
+function addData(e) {
+  // prevent default - we don't want the form to submit in the conventional way
+  e.preventDefault();
+
+  // grab the values entered into the form fields and store them in an object ready for being inserted into the DB
+  let newItem = { title: titleInput.value, body: bodyInput.value };
+
+  // open a read/write db transaction, ready for adding the data
+  let transaction = db.transaction(['notes'], 'readwrite');
+
+  // call an object store that's already been added to the database
+  let objectStore = transaction.objectStore('notes');
+
+  // Make a request to add our newItem object to the object store
+  var request = objectStore.add(newItem);
+  request.onsuccess = function() {
+    // Clear the form, ready for adding the next entry
+    titleInput.value = '';
+    bodyInput.value = '';
+  };
+
+  // Report on the success of the transaction completing, when everything is done
+  transaction.oncomplete = function() {
+    console.log('Transaction completed: database modification finished.');
+
+    // update the display of data to show the newly added item, by running displayData() again.
+    displayData();
+  };
+
+  transaction.onerror = function() {
+    console.log('Transaction not opened due to error');
+  };
+}
+ +

This is quite complex; breaking it down, we:

+ + + +

Отображаем данные

+ +

We've referenced displayData() twice in our code already, so we'd probably better define it. Add this to your code, below the previous function definition:

+ +
// Define the displayData() function
+function displayData() {
+  // Here we empty the contents of the list element each time the display is updated
+  // If you ddn't do this, you'd get duplicates listed each time a new note is added
+  while (list.firstChild) {
+    list.removeChild(list.firstChild);
+  }
+
+  // Open our object store and then get a cursor - which iterates through all the
+  // different data items in the store
+  let objectStore = db.transaction('notes').objectStore('notes');
+  objectStore.openCursor().onsuccess = function(e) {
+    // Get a reference to the cursor
+    let cursor = e.target.result;
+
+    // If there is still another data item to iterate through, keep running this code
+    if(cursor) {
+      // Create a list item, h3, and p to put each data item inside when displaying it
+      // structure the HTML fragment, and append it inside the list
+      let listItem = document.createElement('li');
+      let h3 = document.createElement('h3');
+      let para = document.createElement('p');
+
+      listItem.appendChild(h3);
+      listItem.appendChild(para);
+      list.appendChild(listItem);
+
+      // Put the data from the cursor inside the h3 and para
+      h3.textContent = cursor.value.title;
+      para.textContent = cursor.value.body;
+
+      // Store the ID of the data item inside an attribute on the listItem, so we know
+      // which item it corresponds to. This will be useful later when we want to delete items
+      listItem.setAttribute('data-note-id', cursor.value.id);
+
+      // Create a button and place it inside each listItem
+      let deleteBtn = document.createElement('button');
+      listItem.appendChild(deleteBtn);
+      deleteBtn.textContent = 'Delete';
+
+      // Set an event handler so that when the button is clicked, the deleteItem()
+      // function is run
+      deleteBtn.onclick = function(e) {
+        deleteItem(e);
+      };
+
+      // Iterate to the next item in the cursor
+      cursor.continue();
+    } else {
+      // Again, if list item is empty, display a 'No notes stored' message
+      if(!list.firstChild) {
+        let listItem = document.createElement('li');
+        listItem.textContent = 'No notes stored.'
+        list.appendChild(listItem);
+      }
+      // if there are no more cursor items to iterate through, say so
+      console.log('Notes all displayed');
+    }
+  };
+}
+ +

Again, let's break this down:

+ + + +

Удаляем данные

+ +

As stated above, when a note's delete button is pressed, the note is deleted. This is achieved by the deleteItem() function, which looks like so:

+ +
// Define the deleteItem() function
+function deleteItem(e) {
+  // retrieve the name of the task we want to delete. We need
+  // to convert it to a number before trying it use it with IDB; IDB key
+  // values are type-sensitive.
+  let noteId = Number(e.target.parentNode.getAttribute('data-note-id'));
+
+  // open a database transaction and delete the task, finding it using the id we retrieved above
+  let transaction = db.transaction(['notes'], 'readwrite');
+  let objectStore = transaction.objectStore('notes');
+  let request = objectStore.delete(noteId);
+
+  // report that the data item has been deleted
+  transaction.oncomplete = function() {
+    // delete the parent of the button
+    // which is the list item, so it is no longer displayed
+    e.target.parentNode.parentNode.removeChild(e.target.parentNode);
+    console.log('Note ' + noteId + ' deleted.');
+
+    // Again, if list item is empty, display a 'No notes stored' message
+    if(!list.firstChild) {
+      let listItem = document.createElement('li');
+      listItem.textContent = 'No notes stored.';
+      list.appendChild(listItem);
+    }
+  };
+}
+ + + +

So that's it! Your example should now work.

+ +

If you are having trouble with it, feel free to check it against our live example (see the source code also).

+ +

Храним сложные данные через IndexedDB

+ +

As we mentioned above, IndexedDB can be used to store more than just simple text strings. You can store just about anything you want, including complex objects such as video or image blobs. And it isn't much more difficult to achieve than any other type of data.

+ +

To demonstrate how to do it, we've written another example called IndexedDB video store (see it running live here also). When you first run the example, it downloads all the videos from the network, stores them in an IndexedDB database, and then displays the videos in the UI inside {{htmlelement("video")}} elements. The second time you run it, it finds the videos in the database and gets them from there instead befoire displaying them — this makes subsequent loads much quicker and less bandwidth-hungry.

+ +

Let's walk through the most interesting parts of the example. We won't look at it all — a lot of it is similar to the previous example, and the code is well-commented.

+ +
    +
  1. +

    For this simple example, we've stored the names of the videos to fetch in an array of objects:

    + + 
    const videos = [
+  { 'name' : 'crystal' },
+  { 'name' : 'elf' },
+  { 'name' : 'frog' },
+  { 'name' : 'monster' },
+  { 'name' : 'pig' },
+  { 'name' : 'rabbit' }
+];
    +
    2. +
  2. +

    To start with, once the database is successfully opened we run an init() function. This loops through the different video names, trying to load a record identified by each name from the videos database.

    + +

    If each video is found in the database (easily checked by seeing whether request.result evaluates to true — if the record is not present, it will be undefined), its video files (stored as blobs) and the video name are passed straight to the displayVideo() function to place them in the UI. If not, the video name is passed to the fetchVideoFromNetwork() function to ... you guessed it — fetch the video from the network.

    + + 
    function init() {
+  // Loop through the video names one by one
+  for(let i = 0; i < videos.length; i++) {
+    // Open transaction, get object store, and get() each video by name
+    let objectStore = db.transaction('videos').objectStore('videos');
+    let request = objectStore.get(videos[i].name);
+    request.onsuccess = function() {
+      // If the result exists in the database (is not undefined)
+      if(request.result) {
+        // Grab the videos from IDB and display them using displayVideo()
+        console.log('taking videos from IDB');
+        displayVideo(request.result.mp4, request.result.webm, request.result.name);
+      } else {
+        // Fetch the videos from the network
+        fetchVideoFromNetwork(videos[i]);
+      }
+    };
+  }
+}
    +
    3. +
  3. +

    The following snippet is taken from inside fetchVideoFromNetwork() — here we fetch MP4 and WebM versions of the video using two separate {{domxref("fetch()", "WindowOrWorkerGlobalScope.fetch()")}} requests. We then use the {{domxref("blob()", "Body.blob()")}} method to extract each response's body as a blob, giving us an object representation of the videos that can be stored and displayed later on.

    + +

    We have a problem here though — these two requests are both asynchronous, but we only want to try to display or store the video when both promises have fulfilled. Fortunately there is a built-in method that handles such a problem — {{jsxref("Promise.all()")}}. This takes one argument — references to all the individual promises you want to check for fulfillment placed in an array — and is itself promise-based.

    + +

    When all those promises have fulfilled, the all() promise fulfills with an array containing all the individual fulfillment values. Inside the all() block, you can see that we then call the displayVideo() function like we did before to display the videos in the UI, then we also call the storeVideo() function to store those videos inside the database.

    + + 
    let mp4Blob = fetch('videos/' + video.name + '.mp4').then(response =>
+  response.blob()
+);
+let webmBlob = fetch('videos/' + video.name + '.webm').then(response =>
+  response.blob()
+);;
+
+// Only run the next code when both promises have fulfilled
+Promise.all([mp4Blob, webmBlob]).then(function(values) {
+  // display the video fetched from the network with displayVideo()
+  displayVideo(values[0], values[1], video.name);
+  // store it in the IDB using storeVideo()
+  storeVideo(values[0], values[1], video.name);
+});
    +
    4. +
  4. +

    Let's look at storeVideo() first. This is very similar to the pattern you saw in the previous example for adding data to the database — we open a readwrite transaction and get an object store reference our videos, create an object representing the record to add to the database, then simply add it using {{domxref("IDBObjectStore.add()")}}.

    + + 
    function storeVideo(mp4Blob, webmBlob, name) {
+  // Open transaction, get object store; make it a readwrite so we can write to the IDB
+  let objectStore = db.transaction(['videos'], 'readwrite').objectStore('videos');
+  // Create a record to add to the IDB
+  let record = {
+    mp4 : mp4Blob,
+    webm : webmBlob,
+    name : name
+  }
+
+  // Add the record to the IDB using add()
+  let request = objectStore.add(record);
+
+  ...
+
+};
    +
    5. +
  5. +

    Last but not least, we have displayVideo(), which creates the DOM elements needed to insert the video in the UI and then appends them to the page. The most interesting parts of this are those shown below — to actually display our video blobs in a <video> element, we need to create object URLs (internal URLs that point to the video blobs stored in memory) using the {{domxref("URL.createObjectURL()")}} method. Once that is done, we can set the object URLs to be the vaues of our {{htmlelement("source")}} element's src attributes, and it works fine.

    + + 
    function displayVideo(mp4Blob, webmBlob, title) {
+  // Create object URLs out of the blobs
+  let mp4URL = URL.createObjectURL(mp4Blob);
+  let webmURL = URL.createObjectURL(webmBlob);
+
+  ...
+
+  let video = document.createElement('video');
+  video.controls = true;
+  let source1 = document.createElement('source');
+  source1.src = mp4URL;
+  source1.type = 'video/mp4';
+  let source2 = document.createElement('source');
+  source2.src = webmURL;
+  source2.type = 'video/webm';
+
+  ...
+}
    +
    6. +
+ +

Оффлайн хранение данных

+ +

Пример ниже показывает, как создать приложение, которое будет хранить данные большого объема в хранилище IndexedDB, избегая необходимости скачивать их повторно. Это важное улучшение пользовательского опыта, но есть одно замечание — основной HTML, CSS, и файлы JavaScript все еще нужно загружать каждый раз при запросе сайта, это значит, что данный пример не будет работать при отсутствии сетевого соединения.

+ +

+ +

Это тот случай, когда Service workers и Cache API приходят на помощь.

+ +

Сервис-воркер это файл JavaScript, который регистрируется на конкретном источнике (веб-сайте или части сайта на конкретном домене) при обращении браузером. После регистрации, он может управлять страницами на этом источнике. Воркер находится между загруженной страницей и сетевым соединением, перехватывая сетевые запросы источника.

+ +

Когда worker перехватывает запрос, он может делать многие вещи (смотри идеи для использования сервис-воркеров), но классический пример это сохранение сетевых ответов и затем доступ к ним при запросе, вместо запросов по сети. В результате, это позволяет сделать веб-сайт полностью работающим в офлайне.

+ +

Cache API это еще один механизм хранения данных на клиенте с небольшим отличием — он разработан для хранения HTTP ответов, и прекрасно работает с сервис-воркерами.

+ +
+

Note: Service workers и Cache доступны в большинстве современных браузеров. В момент написания статьи, Safari еще не имел реализации, но скоро должна быть.

+
+ +

Пример сервис воркера

+ +

Давайте взглянем на пример, чтобы дать вам немного мыслей о том, что из этого может выйти. Мы создали другую версию примера хранения видео, который использовался в предыдущей секции — эта функциональность идентична, за исключением того, что этот пример также сохраняет HTML, CSS, и JavaScript в Cache API посредством сервис-воркеров, что позволяет приложению работать полностью в офлайне!

+ +

Смотри пример хранилище видео с IndexedDB и сервис-воркером, и его исходный код.

+ +

Регистрируем сервис воркер

+ +

Первое, что нужно заметить, это дополнительный кусок кода, расположенный в основном JavaScript файле (см. index.js). Первое,что мы делаем, это проверка на то, что serviceWorker доступен в объекте {{domxref("Navigator")}}. Если этот так, тогда мы знаем, что как минимум, базовые функции сервис-воркера доступны. Внутри проверки мы используем метод {{domxref("ServiceWorkerContainer.register()")}} для регистрации сервис-воркера, находящегося в файле sw.js на текущем источнике, таким образом, он может управлять страницами в текущей или внутренних директориях. Когда обещание выполнится, сервис-воркер считается зарегистрированным.

+ +
  // Регистрация сервис-воркера для обеспечения оффлайн доступности сайта
+
+  if('serviceWorker' in navigator) {
+    navigator.serviceWorker
+             .register('/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/sw.js')
+             .then(function() { console.log('Service Worker зарегистрирован'); });
+  }
+ +
+

Примечание: Путь к файлу sw.js указан относительно корня сайта, а не JavaScript файла, содержащего основной код. Полный путь - https://mdn.github.io/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/sw.js. Корень -  https://mdn.github.io, и следовательно указываемый путь должен быть /learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/sw.js. Если вы хотите использовать данный пример на своем сервере, вы также должны изменить путь к скрипту. Это довольно запутанно, но обязано так работать по причинам безопасности.

+
+ +

Устанавливаем сервис воркер

+ +

В следующий раз, когда страница с сервис-воркером будет запрошена (например когда страница будет перезагружена), сервис-воркер запустится на этой странице и начнет контролировать её. Когда это произойдет, событие install будет вызвано в сервис-воркере; вы можете написать код внутри сервис-воркера, который будет вызван в процессе установки.

+ +

Давайте взглянем на файл сервис-воркера sw.js. Вы можете видеть, что слушатель события install зарегистрирован на self. Ключевое слово self это способ ссылки на глобальную область видимости сервис-воркера из файла с сервис-воркером.

+ +

Внутри обработчика install мы используем метод {{domxref("ExtendableEvent.waitUntil()")}}, доступном в объекте события, чтобы сигнализировать, что работа продолжается, и браузер не должен завершать установку, пока все задачи внутри блока не будут выполнены.

+ +

Здесь мы видим Cache API в действии. Мы используем метод {{domxref("CacheStorage.open()")}} для открытия нового объекта кэша, в котором ответы могут быть сохранены (похоже на объект хранилища IndexedDB). Обещание выполнится с объектом {{domxref("Cache")}}, представляющим собой кэш video-store . Затем мы используем метод {{domxref("Cache.addAll()")}} для получения ресурсов и добавления ответов в кэш.

+ +
self.addEventListener('install', function(e) {
+ e.waitUntil(
+   caches.open('video-store').then(function(cache) {
+     return cache.addAll([
+       '/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/',
+       '/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/index.html',
+       '/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/index.js',
+       '/learning-area/javascript/apis/client-side-storage/cache-sw/video-store-offline/style.css'
+     ]);
+   })
+ );
+});
+ +

На этом установка завершена.

+ +

Отвечаем на последующие запросы

+ +

Когда сервис-воркер зарегистрирован и установлен на странице HTML и сопутствующие ресурсы добавлены в кэш, все практически готово. Нужно сделать еще одну вещь - написать код для ответа на дальнейшие сетевые запросы.

+ +

Это то, что делает вторая часть кода файла sw.js. Мы добавили еще один слушатель к сервис-воркеру в глобальной области видимости, который запускает функцию-обработчик при событии fetch. Это происходит всякий раз, когда браузер делает запрос ресурса в директорию, где зарегистрирован сервис-воркер.

+ +

Внутри обработчика, мы сначала выводим в консоль URL запрашиваемого ресурса. Затем отдаем особый ответ на запрос, используя метод {{domxref("FetchEvent.respondWith()")}}.

+ +

Внутри блока мы используем {{domxref("CacheStorage.match()")}} чтобы проверить, можно ли найти соответствующий запрос (т.е. совпадение по URL) в кэше. Обещание возвращает найденный ответ или undefined, если ничего не нашлось.

+ +

Если совпадение нашлось, то просто возвращаем его как особый ответ. В противном случае, используем fetch() для запроса ресурса из сети.

+ +
self.addEventListener('fetch', function(e) {
+  console.log(e.request.url);
+  e.respondWith(
+    caches.match(e.request).then(function(response) {
+      return response || fetch(e.request);
+    })
+  );
+});
+ +

На этом все для нашего простого сервис-воркера. Используя подобный метод, вы можете сделать гораздо больше вещей — для получения доп. информации смотрите рецепты использования сервис-воркеров. Спасибо Paul Kinlan за его статью Adding a Service Worker and Offline into your Web App, которая вдохновила на написание данного примера.

+ +

Тестируем наш пример оффлайн

+ +

Для тестирования примера, вам нужно загрузить его несколько раз, чтобы быть уверенным, что сервис-воркер точно установлен. Когда это сделано, вы можете:

+ + + +

Если обновите страницу с примером снова, вы увидите, что все работает как обычно. Все данные хранятся в офлайн хранилище — ресурсы страницы в кэше, а видео в базе данных IndexedDB.

+ +

Итого

+ +

Это всё, пока что. Мы надеемся наш краткий обзор client-side storage окажется полезным для вас.

+ +

Также стоит почитать

+ + + +

{{PreviousMenu("Learn/JavaScript/Client-side_web_APIs/Video_and_audio_APIs", "Learn/JavaScript/Client-side_web_APIs")}}

+ +

В этом модуле

+ + diff --git a/files/ru/learn/javascript/client-side_web_apis/fetching_data/index.html b/files/ru/learn/javascript/client-side_web_apis/fetching_data/index.html new file mode 100644 index 0000000000..63d9010aab --- /dev/null +++ b/files/ru/learn/javascript/client-side_web_apis/fetching_data/index.html @@ -0,0 +1,379 @@ +--- +title: Получение данных с сервера +slug: Learn/JavaScript/Client-side_web_APIs/Fetching_data +tags: + - AJAX + - API + - Fetch + - JavaScript + - XHR + - Новичку +translation_of: Learn/JavaScript/Client-side_web_APIs/Fetching_data +--- +
{{LearnSidebar}}
+ +
{{PreviousMenuNext("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs/Third_party_APIs", "Learn/JavaScript/Client-side_web_APIs")}}
+ +

Другой очень распространенной задачей в современных веб-сайтах и ​​приложениях является получение отдельных элементов данных с сервера для обновления разделов веб-страницы без необходимости загрузки всей новой страницы. Эта, казалось бы, небольшая деталь оказала огромное влияние на производительность и поведение сайтов, поэтому в этой статье мы объясним концепцию и рассмотрим технологии, которые делают это возможным, например XMLHttpRequest и API Fetch.

+ + + + + + + + + + + + +
Необходимые условия:Основы JavaScript (см. первые шаги, структурные элементы, объекты JavaScript), основы клиентских API
Задача:Узнать, как извлекать данные с сервера и использовать их для обновления содержимого веб-страницы.
+ +

В чем проблема?

+ +

Первоначальная загрузка страницы в Интернете была простой - вы отправляли запрос на сервер  web-сайта, и если всё работает, как и должно, то вся необходимая информация о странице будет загружена и отображена на вашем компьютере.

+ +

A basic representation of a web site architecture

+ +

Проблема с этой моделью заключается в том, что всякий раз, когда вы хотите обновить любую часть страницы, например, чтобы отобразить новый набор продуктов или загрузить новую страницу, вам нужно снова загрузить всю страницу. Это очень расточительно и приводит к плохому пользовательскому опыту, особенно по мере того, как страницы становятся все более сложными.

+ +

Появление Ajax

+ +

Это привело к созданию технологий, позволяющих веб-страницам запрашивать небольшие фрагменты данных (например, HTML, {{glossary("XML")}}, JSON или обычный текст) и отображать их только при необходимости, помогая решать проблему, описанную выше.

+ +

Это достигается с помощью таких API, как {{domxref("XMLHttpRequest")}} или - более новой - Fetch API. Эти технологии позволяют веб-страницам напрямую обрабатывать запросы HTTP для определенных ресурсов, доступных на сервере, и форматировать результирующие данные по мере необходимости перед их отображением.

+ +
+

Примечание: Вначале эта общая техника была известна как Асинхронный JavaScript и XML (Ajax), поскольку она, как правило, использовала {{domxref("XMLHttpRequest")}} для запроса данных XML. В наши дни это обычно не так (вы, скорее всего, будете использовать XMLHttpRequest или Fetch для запроса JSON), но результат все тот же, и термин «Ajax» по-прежнему часто используется для описания этой техники.

+
+ +

A simple modern architecture for web sites

+ +

Модель Ajax предполагает использование веб-API в качестве прокси для более разумного запроса данных, а не просто для того, чтобы браузер перезагружал всю страницу. Давайте подумаем о значении этого:

+ +
    +
  1. Перейдите на один из ваших любимых сайтов, богатых информацией, таких как Amazon, YouTube, CNN и т.д., и загрузите его.
    2. +
  2. Теперь найдите что-нибудь, например, новый продукт. Основной контент изменится, но большая часть информации, подобной заголовку, нижнему колонтитулу, навигационному меню и т. д., останется неизменной.
    3. +
+ +

Это действительно хорошо, потому что:

+ + + +

Чтобы ускорить работу, некоторые сайты также сохраняют необходимые файлы и данные на компьютере пользователя при первом обращении к сайту, а это означает, что при последующих посещениях они используют локальные версии вместо загрузки свежих копий,  как при первой загрузке страницы. Содержимое загружается с сервера только при его обновлении.

+ +

A basic web app data flow architecture

+ +

Основной запрос Ajax

+ +

Давайте посмотрим, как обрабатывается такой запрос, используя как {{domxref ("XMLHttpRequest")}}, так и Fetch. В этих примерах мы будем запрашивать данные из нескольких текстовых файлов и использовать их для заполнения области содержимого.

+ +

Этот набор файлов будет действовать как наша поддельная база данных; в реальном приложении мы с большей вероятностью будем использовать серверный язык, такой как PHP, Python или Node, чтобы запрашивать наши данные из базы данных. Здесь, однако, мы хотим сохранить его простым и сосредоточиться на стороне клиента.

+ +

XMLHttpRequest

+ +

XMLHttpRequest (который часто сокращается до XHR) является довольно старой технологией сейчас - он был изобретен Microsoft в конце 1990-х годов и уже довольно долго стандартизирован в браузерах.

+ +
    +
  1. +

    Чтобы начать этот пример, создайте локальную копию ajax-start.html и четырех текстовых файлов - verse1.txt, verse2.txt, verse3.txt и verse4.txt - в новом каталоге на вашем компьютере. В этом примере мы загрузим другое стихотворение (который вы вполне можете распознать) через XHR, когда он будет выбран в выпадающем меню.

    +
    2. +
  2. +

    Внутри элемента {{htmlelement("script")}} добавьте следующий код. В нем хранится ссылка на элементы {{htmlelement("select")}} и {{htmlelement("pre")}} в переменных и определяется {{domxref ("GlobalEventHandlers.onchange", "onchange")}} обработчика событий, так что, когда значение select изменяется, его значение передается вызываемой функции updateDisplay() в качестве параметра.

    + + 
    var verseChoose = document.querySelector('select');
+var poemDisplay = document.querySelector('pre');
+
+verseChoose.onchange = function() {
+  var verse = verseChoose.value;
+  updateDisplay(verse);
+};
    +
    3. +
  3. +

    Давайте определим нашу функцию updateDisplay(). Прежде всего, поставьте следующее ниже своего предыдущего блока кода - это пустая оболочка функции:

    + + 
    function updateDisplay(verse) {
+
+};
    +
    4. +
  4. +

    Мы начнем нашу функцию с создания относительного URL-адреса, указывающего на текстовый файл, который мы хотим загрузить и который понадобится нам позже. Значение элемента {{htmlelement("select")}} в любой момент совпадает с текстом внутри выбранного {{htmlelement("option")}} (если вы не укажете другое значение в атрибуте value) - например, «Verse 1». Соответствующий текстовый файл стиха является «verse1.txt» и находится в том же каталоге, что и файл HTML, поэтому будет использоваться только имя файла.

    + +

    Тем не менее, веб-серверы, как правило, чувствительны к регистру, и имя файла не имеет символа "пробела". Чтобы преобразовать «Verse 1» в «verse1.txt», нам нужно преобразовать V в нижний регистр, удалить пробел и добавить .txt в конец. Это можно сделать с помощью {{jsxref("String.replace", "replace ()")}}, {{jsxref("String.toLowerCase", "toLowerCase ()")}} и простой конкатенации строк. Добавьте следующие строки внутри функции updateDisplay():

    + + 
    verse = verse.replace(" ", "");
+verse = verse.toLowerCase();
+var url = verse + '.txt';
    +
    5. +
  5. +

    Чтобы начать создание запроса XHR, вам нужно создать новый объект запроса, используя конструктор {{domxref("XMLHttpRequest()")}}. Вы можете назвать этот объект так, как вам нравится, но мы будем называть его request (запросом), чтобы все было просто. Добавьте следующие ниже строки:

    + + 
    var request = new XMLHttpRequest();
    +
    6. +
  6. +

    Затем вам нужно использовать метод {{domxref("XMLHttpRequest.open", "open()")}}, чтобы указать, какой HTTP request method использовать для запроса ресурса из сети и какой его URL-адрес. Мы просто используем метод GET здесь и задаем URL как нашу переменную url. Добавьте это ниже вашей предыдущей строки:

    + + 
    request.open('GET', url);
    +
    7. +
  7. +

    Затем мы зададим тип ожидаемого ответа, который определяется как свойство {{domxref("XMLHttpRequest.responseType", "responseType")}} - как text. Здесь это не является абсолютно необходимым - XHR возвращает текст по умолчанию - но это хорошая идея, чтобы привыкнуть к настройке этого, если вы хотите получить другие типы данных в будущем. Добавьте следующее:

    + + 
    request.responseType = 'text';
    +
    8. +
  8. +

    Получение ресурса из сети - это {{glossary("asynchronous")}} операция, означающая, что вам нужно дождаться завершения этой операции (например, ресурс возвращается из сети), прежде чем вы сможете сделать что-либо с этим ответом, иначе будет выброшена ошибка. XHR позволяет вам обрабатывать это, используя обработчик события {{domxref("XMLHttpRequest.onload", "onload")}} - он запускается при возникновении события {{event("load")}} (когда ответ вернулся). Когда это произойдет, данные ответа будут доступны в свойстве response (ответ) объекта запроса XHR.

    + +

    Добавьте следующее ниже вашего последнего дополнения. Вы увидите, что внутри обработчика события onload мы устанавливаем textContent poemDisplay (элемент {{htmlelement("pre")}}) в значение {{domxref("XMLHttpRequest.response", "request. response ")}}.

    + + 
    request.onload = function() {
+  poemDisplay.textContent = request.response;
+};
    +
    9. +
  9. +

    Вышеприведенная конфигурация запроса XHR  фактически не будет выполняться до тех пор, пока мы не вызовем метод {{domxref("XMLHttpRequest.send", "send()")}}. Добавьте следующее ниже вашего предыдущего дополнения для вызова функции:

    + + 
    request.send();
    +
    10. +
  10. +

    Одна из проблем с примером заключается в том, что он не покажет ни одного стихотворения, когда он впервые загружается. Чтобы исправить это, добавьте следующие две строки внизу вашего кода (чуть выше закрывающего тега </script>), чтобы загрузить стих 1 по умолчанию и убедитесь, что элемент {{htmlelement("select")}} всегда показывает правильное значение:

    + + 
    updateDisplay('Verse 1');
+verseChoose.value = 'Verse 1';
    +
    11. +
+ +

Обслуживание вашего примера с сервера

+ +

Некоторые браузеры (включая Chrome) не будут запускать запросы XHR, если вы просто запускаете пример из локального файла. Это связано с ограничениями безопасности (для получения дополнительной информации о безопасности в Интернете, ознакомьтесь с Website security).

+ +

Чтобы обойти это, нам нужно протестировать пример, запустив его через локальный веб-сервер. Чтобы узнать, как это сделать, прочитайте Как настроить локальный тестовый сервер?

+ +

Fetch

+ +

API-интерфейс Fetch - это, в основном, современная замена XHR - недавно он был представлен в браузерах для упрощения асинхронных HTTP-запросов в JavaScript, как для разработчиков, так и для других API, которые строятся поверх Fetch.

+ +

Давайте преобразуем последний пример, чтобы использовать Fetch!

+ +
    +
  1. +

    Сделайте копию своего предыдущего готового каталога примеров. (Если вы не работали над предыдущим упражнением, создайте новый каталог и внутри него создайте копии xhr-basic.html и четырех текстовых файлов — verse1.txt, verse2.txt, verse3.txt и verse4.txt.)

    +
    2. +
  2. +

    Внутри функции updateDisplay() найдите код XHR:

    + + 
    var request = new XMLHttpRequest();
+request.open('GET', url);
+request.responseType = 'text';
+
+request.onload = function() {
+  poemDisplay.textContent = request.response;
+};
+
+request.send();
    +
    3. +
  3. +

    Замените весь XHR-код следующим:

    + + 
    fetch(url).then(function(response) {
+  response.text().then(function(text) {
+    poemDisplay.textContent = text;
+  });
+});
    +
    4. +
  4. +

    Загрузите пример в свой браузер (запустите его через веб-сервер), и он должен работать так же, как и версия XHR, при условии, что вы используете современный браузер.

    +
    5. +
+ +

Итак, что происходит в коде Fetch?

+ +

Прежде всего, мы вызываем метод {{domxref("WorkerOrWindowGlobalScope.fetch()", "fetch()")}}, передавая ему URL-адрес ресурса, который мы хотим получить. Это современный эквивалент {{domxref("XMLHttpRequest.open", "request.open()")}} в XHR, плюс вам не нужен эквивалент .send().

+ +

После этого вы можете увидеть метод {{jsxref("Promise.then", ".then()")}}, прикреплённый в конец fetch() - этот метод является частью {{jsxref("Promise","Promises")}} - современная функция JavaScript для выполнения асинхронных операций. fetch() возвращает обещание, которое разрешает ответ, отправленный обратно с сервера, - мы используем .then() для запуска некоторого последующего кода после того, как обещание будет разрешено, что является функцией, которую мы определили внутри нее. Это эквивалент обработчика события onload в XHR-версии.

+ +

Эта функция автоматически передает ответ от сервера в качестве параметра, когда обещает fetch(). Внутри функции мы берем ответ и запускаем его метод {{domxref("Body.text", "text()")}}, который в основном возвращает ответ как необработанный текст. Это эквивалент request.responseType = 'text' в версии XHR.

+ +

Вы увидите, что text()также возвращает обещание, поэтому мы привязываем к нему другой .then(), внутри которого мы определяем функцию для получения необработанного текста, который обещает решение text().

+ +

Внутри функции внутреннего обещания мы делаем то же самое, что и в версии XHR, - устанавливаем текстовое содержимое {{htmlelement("pre")}} в текстовое значение.

+ +

Помимо обещаний

+ +

Обещания немного запутывают первый раз, когда вы их встречаете, но не беспокойтесь об этом слишком долго. Через некоторое время вы привыкнете к ним, особенно, когда вы узнаете больше о современных JavaScript-API. Большинство из них в большей степени основаны на обещаниях.

+ +

Давайте посмотрим на структуру обещаний сверху, чтобы увидеть, можем ли мы еще немного понять это:

+ +
fetch(url).then(function(response) {
+  response.text().then(function(text) {
+    poemDisplay.textContent = text;
+  });
+});
+ +

В первой строке говорится: «Получить ресурс, расположенный по адресу url» (fetch(url)) и «затем запустить указанную функцию, когда обещание будет разрешено» (.then(function() { ... })). «Resolve» означает «завершить выполнение указанной операции в какой-то момент в будущем». Указанная операция в этом случае заключается в извлечении ресурса с указанного URL (с использованием HTTP-запроса) и возврата ответа для нас, чтобы что-то сделать.

+ +

Фактически, функция, переданная в then(), представляет собой кусок кода, который не запускается немедленно - вместо этого он будет работать в какой-то момент в будущем, когда ответ будет возвращен. Обратите внимание, что вы также можете сохранить свое обещание в переменной и цепочку {{jsxref("Promise.then", ".then()")}} вместо этого. Ниже код будет делать то же самое:

+ +
var myFetch = fetch(url);
+
+myFetch.then(function(response) {
+  response.text().then(function(text) {
+    poemDisplay.textContent = text;
+  });
+});
+ +

Поскольку метод fetch() возвращает обещание, которое разрешает HTTP-ответ, любая функция, которую вы определяете внутри .then(), прикованная к концу, будет автоматически передаваться как параметр. Вы можете вызвать параметр, который вам нравится - приведенный ниже пример будет работать:

+ +
fetch(url).then(function(dogBiscuits) {
+  dogBiscuits.text().then(function(text) {
+    poemDisplay.textContent = text;
+  });
+});
+ +

Но имеет смысл называть параметр тем, что описывает его содержимое!

+ +

Теперь давайте сосредоточимся только на функции:

+ +
function(response) {
+  response.text().then(function(text) {
+    poemDisplay.textContent = text;
+  });
+}
+ +

Объект ответа имеет метод {{domxref("Body.text", "text()")}}, который берет необработанные данные, содержащиеся в теле ответа, и превращает его в обычный текст, который является форматом, который мы хотим в нем А также возвращает обещание (которое разрешает полученную текстовую строку), поэтому здесь мы используем другой {{jsxref("Promise.then", ".then()")}}, внутри которого мы определяем другую функцию, которая диктует что мы хотим сделать с этой текстовой строкой. Мы просто устанавливаем свойство textContent элемента {{htmlelement("pre")}} нашего стихотворения равным текстовой строке, так что это получается довольно просто.

+ +

Также стоит отметить, что вы можете напрямую связывать несколько блоков обещаний (.then(), но есть и другие типы) на конце друг друга, передавая результат каждого блока следующему блоку по мере продвижения по цепочке , Это делает обещания очень мощными.

+ +

Следующий блок делает то же самое, что и наш оригинальный пример, но написан в другом стиле:

+ +
fetch(url).then(function(response) {
+  return response.text()
+}).then(function(text) {
+  poemDisplay.textContent = text;
+});
+ +

Многие разработчики любят этот стиль больше, поскольку он более плоский и, возможно, легче читать для более длинных цепочек обещаний - каждое последующее обещание приходит после предыдущего, а не внутри предыдущего (что может стать громоздким). Единственное отличие состоит в том, что мы должны были включить оператор return перед response.text(), чтобы заставить его передать результат в следующую ссылку в цепочке.

+ +

Какой механизм следует использовать?

+ +

Это действительно зависит от того, над каким проектом вы работаете. XHR существует уже давно и имеет отличную кросс-браузерную поддержку. Fetch and Promises, с другой стороны, являются более поздним дополнением к веб-платформе, хотя они хорошо поддерживаются в браузере, за исключением Internet Explorer и Safari (которые на момент написания Fetch были доступны в своем предварительный просмотр технологии).

+ +

Если вам необходимо поддерживать старые браузеры, тогда может быть предпочтительным решение XHR. Если, однако, вы работаете над более прогрессивным проектом и не так обеспокоены старыми браузерами, то Fetch может быть хорошим выбором.

+ +

Вам действительно нужно учиться - Fetch станет более популярным, так как Internet Explorer отказывается от использования (IE больше не разрабатывается, в пользу нового браузера Microsoft Edge), но вам может понадобиться XHR еще некоторое время.

+ +

Более сложный пример

+ +

Чтобы завершить статью, мы рассмотрим несколько более сложный пример, который показывает более интересные применения Fetch. Мы создали образец сайта под названием The Can Store - это вымышленный супермаркет, который продает только консервы. Вы можете найти этот пример в прямом эфире на GitHub и посмотреть исходный код.

+ +

A fake ecommerce site showing search options in the left hand column, and product search results in the right hand column.

+ +

По умолчанию на сайте отображаются все продукты, но вы можете использовать элементы управления формы в столбце слева, чтобы отфильтровать их по категориям, поисковому запросу или и тому и другому.

+ +

Существует довольно много сложного кода, который включает фильтрацию продуктов по категориям и поисковым запросам, манипулирование строками, чтобы данные отображались правильно в пользовательском интерфейсе и т.д. Мы не будем обсуждать все это в статье, но вы можете найти обширные комментарии в коде (см. can-script.js).

+ +

Однако мы объясним код Fetch.

+ +

Первый блок, который использует Fetch, можно найти в начале JavaScript:

+ +
fetch('products.json').then(function(response) {
+  if(response.ok) {
+    response.json().then(function(json) {
+      products = json;
+      initialize();
+    });
+  } else {
+    console.log('Network request for products.json failed with response ' + response.status + ': ' + response.statusText);
+  }
+});
+ +

Это похоже на то, что мы видели раньше, за исключением того, что второе обещание находится в условном выражении. В этом случае мы проверяем, был ли возвращенный ответ успешным - свойство {{domxref("response.ok")}} содержит логическое значение, которое true, если ответ был в порядке (например, 200 meaning "OK") или false, если он не увенчался успехом.

+ +

Если ответ был успешным, мы выполняем второе обещание - на этот раз мы используем {{domxref("Body.json", "json()")}}, а не {{domxref("Body.text", "text()")}}, так как мы хотим вернуть наш ответ как структурированные данные JSON, а не обычный текст.

+ +

Если ответ не увенчался успехом, мы выводим сообщение об ошибке в консоль, в котором сообщается о сбое сетевого запроса, который сообщает о статусе сети и описательном сообщении ответа (содержащемся в {{domxref("response.status")}} и {{domxref("response.statusText")}}, соответственно). Конечно, полный веб-сайт будет обрабатывать эту ошибку более грациозно, отображая сообщение на экране пользователя и, возможно, предлагая варианты для исправления ситуации.

+ +

Вы можете проверить сам случай отказа:

+ +
    +
  1. Создание локальной копии файлов примеров (загрузка и распаковка the can-store ZIP file)
    2. +
  2. Запустите код через веб-сервер (как описано выше, в {{anch("Serving your example from a server")}})
    3. +
  3. Измените путь к извлеченному файлу, например, «product.json» (т.е. убедитесь, что он написан неправильно)
    4. +
  4. Теперь загрузите индексный файл в свой браузер (например, через localhost:8000) и посмотрите в консоли разработчика браузера. Вы увидите сообщение в строке «Запрос сети для продуктов.json не удалось с ответом 404: Файл не найден»
    5. +
+ +

Второй блок Fetch можно найти внутри функции fetchBlob():

+ +
fetch(url).then(function(response) {
+  if(response.ok) {
+    response.blob().then(function(blob) {
+      objectURL = URL.createObjectURL(blob);
+      showProduct(objectURL, product);
+    });
+  } else {
+    console.log('Network request for "' + product.name + '" image failed with response ' + response.status + ': ' + response.statusText);
+  }
+});
+ +

Это работает во многом так же, как и предыдущий, за исключением того, что вместо использования {{domxref("Body.json", "json()")}} мы используем {{domxref("Body.blob", "blob()")}} - в этом случае мы хотим вернуть наш ответ в виде файла изображения, а формат данных, который мы используем для этого - Blob - этот термин является аббревиатурой от« Binary Large Object »и может в основном использоваться для представляют собой большие файловые объекты, такие как изображения или видеофайлы.

+ +

После того как мы успешно получили наш blob, мы создаем URL-адрес объекта, используя {{domxref("URL.createObjectURL()", "createObjectURL()")}}. Это возвращает временный внутренний URL-адрес, указывающий на объект, указанный в браузере. Они не очень читаемы, но вы можете видеть, как выглядит, открывая приложение Can Store, Ctrl-/щелкнуть правой кнопкой мыши по изображению и выбрать опцию «Просмотр изображения» (которая может немного отличаться в зависимости от того, какой браузер вы ). URL-адрес объекта будет отображаться внутри адресной строки и должен выглядеть примерно так:

+ +
blob:http://localhost:7800/9b75250e-5279-e249-884f-d03eb1fd84f4
+ +

Вызов: XHR версия the Can Store

+ +

Мы хотели бы, чтобы вы решили преобразовать версию приложения Fetch для использования XHR в качестве полезной части практики. Возьмите копию ZIP файла и попробуйте изменить JavaScript, если это необходимо.

+ +

Некоторые полезные советы:

+ + + +
+

Примечание: Если у вас есть проблемы с этим, не стесняйтесь сравнить свой код с готовой версией на GitHub (см. исходник здесь, а также см. это в действии).

+
+ +

Резюме

+ +

Это завершает нашу статью по извлечению данных с сервера. К этому моменту вы должны иметь представление о том, как начать работать как с XHR, так и с Fetch.

+ +

Смотрите также

+ +

Однако в этой статье обсуждается много разных тем, которые только поцарапали поверхность. Для получения более подробной информации по этим темам, попробуйте следующие статьи:

+ + + +
{{PreviousMenuNext("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs/Third_party_APIs", "Learn/JavaScript/Client-side_web_APIs")}}
+ +
+

В этом модуле

+ + +
diff --git a/files/ru/learn/javascript/client-side_web_apis/index.html b/files/ru/learn/javascript/client-side_web_apis/index.html new file mode 100644 index 0000000000..b5e7493f19 --- /dev/null +++ b/files/ru/learn/javascript/client-side_web_apis/index.html @@ -0,0 +1,53 @@ +--- +title: Клиентский веб API +slug: Learn/JavaScript/Client-side_web_APIs +tags: + - API + - Articles + - Beginner + - CodingScripting + - DOM + - Graphics + - JavaScript + - Landing + - Learn + - Media + - Module + - NeedsTranslation + - TopicStub + - WebAPI + - data +translation_of: Learn/JavaScript/Client-side_web_APIs +--- +
{{LearnSidebar}}
+ +

При написании клиентского JavaScript для приложений или веб-сайтов Вам не приходится слишком сильно углубляться, пока Вы не начнете использовать API — интерфейсы управления различными аспектами браузера или операционной системы на которой этот сайт работает, или же с данными с других веб-сайтов или сервисов. В этом модуле мы рассмотрим что API из себя представляет и как использовать самые распространенные из них, с которыми Вы можете столкнуться в разработке.

+ +

Прежде чем начать

+ +

Убедитесь, что вы прочли и хорошо разбираетесь в следующих модулях (Первые шаги, Структурные элементы, и Введение в объекты). Эти модули включали в себя простое использование API, так как зачастую без них сложно писать примеры клиентского кода JavaScript. В данном модуле мы предполагаем, что вы хорошо знакомы с основами JavaScript, и немного подробнее рассмотрим общие веб-API.

+ +

Естественно знание HTML и CSS здесь также необходимо.

+ +
+

Примечание: Если вы работаете на устройстве, где у вас нет возможности создавать свои собственные файлы, вы можете проверить большинство примеров кода в онлайн-программах вроде JSBin или Thimble.

+
+ +

Руководства

+ +
+
Введение в различные web API
+
Прежде всего, мы начнем изучение API с основ - что это такое, как это работает, как вы используете их в своем коде и как они структурированы? Мы также рассмотрим, что представляют собой различные основные классы API, и как их можно использовать.
+
Управление документами
+
При написании веб-страниц и приложений Вы чаще всего будете управлять каким-либо образом веб-документами.  Обычно это делается с помощью Document Object Model (DOM), набора API-интерфейсов для управления HTML-разметкой и стилями, которые используют объект {{domxref ("Document")}}. В этой статье мы рассмотрим, как использовать DOM, а также некоторые интересные API, которые могут изменить рабочую среду интересными способами.
+
Получение данных с сервера
+
Другой очень распространенной задачей в современных веб-сайтах и приложениях является получение отдельных элементов данных с сервера для обновления разделов веб-страницы без необходимости загрузки абсолютно новой страницы. Эта, казалось бы, небольшая деталь оказала огромное влияние на производительность и поведение сайтов, поэтому в этой статье мы объясним концепцию и рассмотрим технологии, которые позволяют это, например {{domxref("XMLHttpRequest")}} и Fetch API.
+
Сторонние API
+
API, которые мы рассматривали до сих пор, встроены в браузер, но не все API встроены в браузер. Многие крупные веб-сайты и сервисы, такие как Google Maps, Twitter, Facebook, PayPal и т.д. предоставляют API-интерфейсы, позволяющие разработчикам использовать свои данные (например, показывать ваш Twitter-поток в вашем блоге) или сервисы (например, отображение пользовательских карт Google на вашем сайте, или с помощью входа в систему Facebook для входа в систему пользователей). В этой статье рассматривается различие между API браузера и сторонними API и показано типичное использование последнего.
+
Рисование графики
+
В браузере содержатся очень мощные инструменты графического программирования, начиная с языка Scalable Vector Graphics (SVG) и заканчивая API для рисования элементов HTML {{htmlelement("canvas")}} (см. The Canvas API и WebGL). В статье содержится введение в Canvas API и дополнительные ресурсы, чтобы вы могли узнать больше.
+
Видео и аудио API
+
HTML5 поставляется с элементами для размещения мультимедийных материалов в документах - {{htmlelement("video")}} и {{htmlelement("audio")}} - которые, в свою очередь, имеют свои собственные API для управления воспроизведением, поиском и т. д. В статье показано, как выполнять общие задачи, такие как создание пользовательских элементов управления воспроизведением.
+
Клиентское хранилище
+
Современные веб-браузеры имеют ряд различных технологий, которые позволяют хранить данные, связанные с веб-сайтами, и извлекать их, когда это необходимо, что позволяет вам сохранять данные в долгосрочной перспективе, сохранять сайты в автономном режиме и многое другое. В этой статье объясняются самые основы того, как они работают.
+
diff --git a/files/ru/learn/javascript/client-side_web_apis/introduction/index.html b/files/ru/learn/javascript/client-side_web_apis/introduction/index.html new file mode 100644 index 0000000000..bc710c0d37 --- /dev/null +++ b/files/ru/learn/javascript/client-side_web_apis/introduction/index.html @@ -0,0 +1,277 @@ +--- +title: Введение в web APIs +slug: Learn/JavaScript/Client-side_web_APIs/Introduction +translation_of: Learn/JavaScript/Client-side_web_APIs/Introduction +--- +
{{LearnSidebar}}
+ +
{{NextMenu("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs")}}
+ +

Начнём с рассмотрения того что представляют собой API на высоком уровне и выясним, как они работают, как их использовать в своих программах и как они структурированы. Также рассмотрим основные виды API и их применение.

+ + + + + + + + + + + + +
Необходимые знания:Базовая компьютерная грамотность, понимание основ HTML и CSS,  основы JavaScript (см. первые шаги, building blocks, объекты JavaScript).
Цель:Познакомиться с API, выяснить что они могут делать и как их использовать.
+ +

Что такое API?

+ +

Интерфейс прикладного программирования (Application Programming Interfaces, APIs) - это готовые конструкции языка программирования, позволяющие разработчику строить сложный функционал с меньшими усилиями. Они "скрывают" более сложный код от программиста, обеспечивая простоту использования.

+ +

Для лучшего понимания рассмотрим аналогию с домашними электросетями. Когда вы хотите использовать какой-то электроприбор, вы просто подключаете его к розетке, и всё работает. Вы не пытаетесь подключить провода напрямую к источнику тока — делать это бесполезно и, если вы не электрик, сложно и опасно.

+ +

+ +

Image source: Overloaded plug socket by The Clear Communication People, on Flickr.

+ +

Точно также, если мы хотим, например, программировать 3D графику, гораздо легче сделать это с использованием API, написанных на языках высокого уровня, таких как JavaScript или Python.

+ +
+

Note: См. также API в словаре.

+
+ +

API клиентской части JavaScript

+ +

Для JavaScript на стороне клиента, в частности, существует множество API. Они не являются частью языка, а построены с помощью встроенных функций JavaScript для того, чтобы увеличить ваши возможности при написании кода. Их можно разделить на две категории:

+ + + +

+ +

Взаимодействие JavaScript, API и других средств JavaScript

+ +

Итак, выше мы поговорили о том, что такое JavaScript API клиентской части и как они связаны с языком JavaScript. Давайте теперь тезисно запишем основные понятия и определим назначение других инструментов JavaScript:

+ + + +

На что способны API?

+ +

Широкое разнообразие API в современных браузерах позволяет наделить ваше приложение большими возможностями. Достаточно посмотреть список на странице MDN APIs index page.

+ +

Распространённые API браузера

+ +

В частности, к наиболее часто используемым категориям API (и которые мы рассмотрим далее в этом модуле) относятся :

+ + + +

Распространённые сторонние API

+ +

Существует множество сторонних API; некоторые из наиболее популярных, которые вы рано или поздно будете использовать, включают:

+ + + +
+

Note: Вы можете найти информацию о гораздо большем количестве сторонних API в Каталоге Web API.

+
+ +

Как работает API?

+ +

Работа разных JavaScript API немного отличается, но, в основном, у них похожие функции и принцип работы.

+ +

Они основаны на объектах

+ +

Взаимодействие с API в коде происходит через один или больше объектов JavaScript, которые служат контейнерами для информации, с которой работает API (содержится в свойствах объекта), и реализуют функционал, который предоставляет API (содержится в методах объекта).

+ +
+

Note: Если вам ещё не известно как работают объекты, советуем вернуться назад и изучить модуль Основы объектов JavaScript прежде чем продолжать.

+
+ +

Вернёмся к примеру с API Геолокации — очень простой API, состоящий из нескольких простых объектов:

+ + + +

Так как же эти объекты взаимодействуют? Если вы посмотрите на наш пример maps-example.html (see it live also), вы увидите следующий код:

+ +
navigator.geolocation.getCurrentPosition(function(position) {
+  var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);
+  var myOptions = {
+    zoom: 8,
+    center: latlng,
+    mapTypeId: google.maps.MapTypeId.TERRAIN,
+    disableDefaultUI: true
+  }
+  var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions);
+});
+ +
+

Note: Когда вы впервые загрузите приведённый выше пример, появится диалоговое окно, запрашивающее разрешение на передачу данных о местонахождении этому приложению (см. раздел {{anch("У них есть дополнительные средства безопасности там, где это необходимо")}} далее в этой статье). Вам нужно разрешить передачу данных, чтобы иметь возможность отметить своё местоположение на карте. Если вы всё ещё не видите карту, возможно, требуется установить разрешения вручную; это делается разными способами в зависимости от вашего браузера; например, в Firefox перейдите > Tools > Page Info > Permissions, затем измените настройки Share Location; в Chrome перейдите Settings > Privacy > Show advanced settings > Content settings и измените настройки Location.

+
+ +

Во-первых, мы хотим использовать метод {{domxref("Geolocation.getCurrentPosition()")}}, чтобы получить текущее положение нашего устройства. Доступ к объекту браузера {{domxref("Geolocation")}} производится с помощью свойства {{domxref("Navigator.geolocation")}}, так что мы начнём с

+ +
navigator.geolocation.getCurrentPosition(function(position) { ... });
+ +

Это эквивалентно следующему коду

+ +
var myGeo = navigator.geolocation;
+myGeo.getCurrentPosition(function(position) { ... });
+ +

Но мы можем использовать точки, чтобы связать доступ к свойствам/методам объекта в одно выражение, уменьшая количество строк в программе.

+ +

Метод {{domxref("Geolocation.getCurrentPosition()")}} имеет один обязательный параметр - анонимную функцию, которая запустится, когда текущее положение устройства будет успешно считано. Сама эта функция принимает параметр, являющийся объектом {{domxref("Position")}}, представляющим данные о текущем местоположении.

+ +
+

Note: Функция, которая передаётся другой функции в качестве параметра, называется функцией обратного вызова (callback function).

+
+ +

Такой подход, при котором функция вызывается только тогда, когда операция была завершена, очень распространён в JavaScript API — убедиться, что операция была завершена прежде, чем пытаться использовать данные, которые она возвращает, в другой операции. Такие операции также называют асинхронными операциями (asynchronous operations). Учитывая, что получение данных геолокации производится из внешнего устройства (GPS-устройства или другого устройства геолокации), мы не можем быть уверены, что операция считывания будет завершена вовремя и мы сможем незамедлительно использовать возвращаемые ею данные. Поэтому такой код не будет работать:

+ +
var position = navigator.geolocation.getCurrentPosition();
+var myLatitude = position.coords.latitude;
+ +

Если первая строка ещё не вернула результат, вторая вызовет ошибку из-за того, что данные геолокации ещё не стали доступны. По этой причине, API, использующие асинхронные операции, разрабатываются с использованием {{glossary("callback function")}}, или более современной системы Обещаний(Promises), которая появилась в ECMAScript 6 и широко используются в новых API.

+ +

Мы совмещаем API Геолокации со сторонним API - Google Maps API, который используем для того, чтобы отметить расположение, возвращаемое  getCurrentPosition() , на Google Map. Чтобы Google Maps API стал доступен на нашей странице, мы включаем его в HTML документ:

+ +
<script type="text/javascript" src="https://maps.google.com/maps/api/js?key=AIzaSyDDuGt0E5IEGkcE6ZfrKfUtE9Ko_de66pA"></script>
+ +

Чтобы использовать этот API, во-первых создадим объект LatLng с помощью конструктора google.maps.LatLng() , принимающим данные геолокации {{domxref("Coordinates.latitude")}} и {{domxref("Coordinates.longitude")}} :

+ +
var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);
+ +

Этот объект сам является значением свойства center объекта настроек (options), который мы назвали myOptions. Затем мы создаём экземпляр объекта, представляющего нашу карту, вызывая конструктор google.maps.Map() и передавая ему два параметра — ссылку на элемент {{htmlelement("div")}}, на котором мы хотим отрисовывать карту (с ID map_canvas), и объект настроек (options), который мы определили выше.

+ +
var myOptions = {
+  zoom: 8,
+  center: latlng,
+  mapTypeId: google.maps.MapTypeId.TERRAIN,
+  disableDefaultUI: true
+}
+
+var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions);
+ +

Когда это сделано, наша карта отрисовывается.

+ +

Последний блок кода демонстрирует два распространённых подхода, которые вы увидите во многих API:

+ + + +
+

Note: Не отчаивайтесь, если вы что-то не поняли из этого примера сразу. Мы рассмотрим использование сторонних API более подробно в следующих статьях.

+
+ +

У них узнаваемые точки входа

+ +

При использовании API убедитесь, что вы знаете где точка входа для API. В API Геолокации это довольно просто — это свойство {{domxref("Navigator.geolocation")}}, возвращающее объект браузера {{domxref("Geolocation")}}, внутри которого доступны все полезные методы геолокации.

+ +

Найти точку входа Document Object Model (DOM) API ещё проще — при применении этого API используется объект {{domxref("Document")}}, или экземпляр элемента HTML, с которым вы хотите каким-либо образом взаимодействовать, к примеру:

+ +
var em = document.createElement('em'); // создаёт новый элемент em
+var para = document.querySelector('p'); // ссылка на существующий элемент p
+em.textContent = 'Hello there!'; // присвоение текстового содержимого
+para.appendChild(em); // встроить em внутрь para
+ +

Точки входа других API немного сложнее, часто подразумевается создание особого контекста, в котором будет написан код API. Например, объект контекста Canvas API создаётся получением ссылки на элемент {{htmlelement("canvas")}}, на котором вы хотите рисовать, а затем необходимо вызвать метод {{domxref("HTMLCanvasElement.getContext()")}}:

+ +
var canvas = document.querySelector('canvas');
+var ctx = canvas.getContext('2d');
+ +

Всё, что мы хотим сделать с canvas после этого, достигается вызовом свойств и методов объекта содержимого (content) (который является экземпляром {{domxref("CanvasRenderingContext2D")}}), например:

+ +
Ball.prototype.draw = function() {
+  ctx.beginPath();
+  ctx.fillStyle = this.color;
+  ctx.arc(this.x, this.y, this.size, 0, 2 * Math.PI);
+  ctx.fill();
+};
+ +
+

Note: Вы можете увидеть этот код в действии в нашем bouncing balls demo (see it running live also).

+
+ +

Они используют события для управления состоянием

+ +

Мы уже обсуждали события ранее в этом курсе, в нашей статье Introduction to events — в этой статье детально описываются события на стороне клиента и их применение. Если вы ещё не знакомы с тем, как работают события клиентской части, рекомендуем прочитать эту статью прежде, чем продолжить.

+ +

В некоторых API содержится ряд различных событий, в некоторых - событий нет. Свойства обработчика, позволяющие запускать функции при совершении какого-либо события по большей части перечислены в нашем материале отдельного раздела "Обработчики событий (Event handlers)". Как простой пример, экземпляры объекта XMLHttpRequest (каждый представляет собой HTTP-запрос к серверу на получение каких-либо ресурсов (resource)) имеют несколько доступных событий, например, событие load происходит, когда ответ с запрашиваемым ресурсом был успешно возвращён и доступен в данный момент.

+ +

Следующий код содержит простой пример использования событий:

+ +
var requestURL = 'https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json';
+var request = new XMLHttpRequest();
+request.open('GET', requestURL);
+request.responseType = 'json';
+request.send();
+
+request.onload = function() {
+  var superHeroes = request.response;
+  populateHeader(superHeroes);
+  showHeroes(superHeroes);
+}
+ +
+

Note: Вы можете увидеть этот код в действии в примере ajax.html (see it live also).

+
+ +

В первых пяти строках мы задаём расположение ресурса, который хотим получить, создаём экземпляр объекта запроса с помощью конструктора XMLHttpRequest(), открываем HTTP-запрос GET, чтобы получить запрашиваемый ресурс, определяем, что мы хотим получить этот ресурс в формате json, после чего отсылаем запрос.

+ +

Затем функция-обработчик onload определяет наши действия по обработке ответа сервера. Нам известно, что ответ успешно возвращён и доступен после наступления события load (и если не произойдёт ошибка), так что мы сохраняем ответ, содержащий возвращённый сервером объект JSON в переменной superHeroes, которую затем передаём двум различным функциям для дальнейшей обработки.

+ +

У них есть дополнительные средства безопасности там, где это необходимо

+ +

Функционал WebAPI подвержен тем же соображениям безопасности , что и JavaScript или другие веб-технологии (например, same-origin policy), но иногда они содержат дополнительные механизмы защиты. К примеру, некоторые из наиболее современных WebAPI работают только со страницами, обслуживаемыми через HTTPS в связи с передачей конфиденциальных данных (примеры: Service Workers и Push).

+ +

К тому же, некоторые WebAPI запрашивают разрешение от пользователя, как только к ним происходит вызов в коде. В качестве примера, вы, возможно, встречали такое диалоговое окно при загрузке нашего примера Geolocation ранее:

+ +

+ +

Notifications API запрашивает разрешение подобным образом:

+ +

+ +

Запросы разрешений необходимы для обеспечения безопасности пользователей — не будь их, сайты могли бы скрытно отследить ваше местоположение, не создавая множество надоедливых уведомлений.

+ +

Итоги

+ +

На данном этапе, у вас должно сформироваться представление о том, что такое API, как они работают и как вы можете применить их в своём JavaScript коде. Вам наверняка не терпится начать делать по-настоящему интересные вещи с конкретными API, так вперёд! В следующий раз мы рассмотрим работу с документом с помощью Document Object Model (DOM).

+ +

{{NextMenu("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs")}}

+ +

В этом модуле

+ + diff --git a/files/ru/learn/javascript/client-side_web_apis/manipulating_documents/index.html b/files/ru/learn/javascript/client-side_web_apis/manipulating_documents/index.html new file mode 100644 index 0000000000..e93334902a --- /dev/null +++ b/files/ru/learn/javascript/client-side_web_apis/manipulating_documents/index.html @@ -0,0 +1,321 @@ +--- +title: Управление документами +slug: Learn/JavaScript/Client-side_web_APIs/Manipulating_documents +tags: + - API + - DOM + - Изучение + - Навигатор + - Новичек + - Окно +translation_of: Learn/JavaScript/Client-side_web_APIs/Manipulating_documents +--- +
{{LearnSidebar}}
+ +
{{PreviousMenuNext("Learn/JavaScript/Client-side_web_APIs/Introduction", "Learn/JavaScript/Client-side_web_APIs/Fetching_data", "Learn/JavaScript/Client-side_web_APIs")}}
+ +

При написании веб-страниц и приложений вам придётся часто каким-либо образом управлять структурой документа. Обычно это делается с помощью Document Object Model (DOM), набора API для управления разметкой HTML и стилями, которая сильно использует объект {{domxref ("Document")}}. В этой статье мы подробно рассмотрим, как использовать DOM и некоторые другие интересные API, которые могут изменить вашу среду интересными способами.

+ + + + + + + + + + + + +
Предпосылки:Базовая компьютерная грамотность, базовое понимание HTML, CSS и JavaScript - включая объекты JavaScript.
Задача:Познакомиться с основными DOM API и другими API, обычно связанными с DOM, и манипулированием документами
+ +

Важные элементы веб-браузера

+ +

Веб-браузеры - очень сложные части программного обеспечения с множеством движущихся частей, многие из которых не могут управляться или управляться веб-разработчиком с использованием JavaScript. Вы можете подумать, что такие ограничения - это плохо, но браузеры заблокированы по уважительным причинам (в основном ради безопасности). Представьте себе, что веб-сайт может получить доступ к вашим сохраненным паролям или другой конфиденциальной информации и войти на веб-сайты так, как если бы это были вы?

+ +

Несмотря на ограничения, Web API по-прежнему дают нам доступ к множеству функциональных возможностей, которые позволяют нам многое делать с веб-страницами. Есть несколько действительно очевидных моментов, на которые вы будете регулярно ссылаться в своем коде. Рассмотрим следующую диаграмму, которая представляет основные части браузера, непосредственно участвующие в просмотре веб-страниц:

+ +

+ + + +

В этой статье мы сосредоточимся главным образом на манипулировании документом, но мы покажем ещё несколько полезных моментов.

+ +

Объектная модель документа

+ +

Документ, загруженный в каждый из ваших вкладок браузера, представлен объектной моделью документа. Это представление «древовидной структуры», созданное браузером, которое позволяет легко получить доступ к структуре HTML с помощью языков программирования - например, сам браузер использует его для применения стиля и другой информации к правильным элементам, поскольку он отображает страницу, а разработчики (как Вы) могут манипулировать DOM с JavaScript после того, как страница была отображена.

+ +

Мы создали простую страницу примера в dom-example.html (см. также live). Попробуйте открыть это в своем браузере - это очень простая страница, содержащая элемент {{htmlelement("section")}}, внутри которого вы можете найти изображение и абзац со ссылкой внутри. Исходный код HTML выглядит так:

+ +
<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Simple DOM example</title>
+  </head>
+  <body>
+      <section>
+        <img src="dinosaur.png" alt="A red Tyrannosaurus Rex: A two legged dinosaur standing upright like a human, with small arms, and a large head with lots of sharp teeth.">
+        <p>Here we will add a link to the <a href="https://www.mozilla.org/">Mozilla homepage</a></p>
+      </section>
+  </body>
+</html>
+ +

DOM, с другой стороны, выглядит так:

+ +

+ +
+

Примечание. Эта диаграмма дерева DOM была создана с использованием Live DOM viewer Яна Хиксона.

+
+ +

Вы можете видеть здесь, что каждый элемент и бит текста в документе имеют свою собственную запись в дереве - каждый из них называется узлом (node). Вы также столкнетесь с различными терминами, используемыми для описания типа узла, и их положением в дереве относительно друг друга:

+ + + +

Полезно ознакомиться с этой терминологией перед тем, как работать с DOM, поскольку некоторые термины кода, с которыми вы столкнетесь, используют их.. Возможно, вы уже сталкивались с ними, если вы изучали CSS (например, селектор потомков, дочерний селектор).

+ +

Активное обучение: основы управления структурой DOM

+ +

Чтобы начать изучение по управлению структуры DOM, давайте начнем с практического примера.

+ +
    +
  1. Возьмите локальную копию страницы dom-example.html page и изображение, которое вместе с ним.
    2. +
  2. Добавьте элемент <script></script> чуть выше закрывающего тега </body>.
    3. +
  3. Чтобы управлять элементом внутри DOM, вам сначала нужно выбрать его и сохранить ссылку на него внутри переменной. Внутри вашего скриптового элемента добавьте следующую строку: + 
    var link = document.querySelector('a');
    +
    4. +
  4. Теперь у нас есть ссылка на элемент, хранящаяся в переменной, мы можем начать ее манипулировать с использованием доступных ему свойств и методов (они определены на таких интерфейсах, как {{domxref("HTMLAnchorElement")}} в случае {{htmlelement ("a")}}, его более общий родительский интерфейс {{domxref ("HTMLElement")}} и {{domxref("Node")}} - который представляет все узлы в DOM). Прежде всего, давайте изменим текст внутри ссылки, обновив значение свойства {{domxref("Node.textContent")}}. Добавьте следующую строку ниже предыдущей: + 
    link.textContent = 'Mozilla Developer Network';
    +
    5. +
  5. Мы также должны изменить URL-адрес, на который указывает ссылка, чтобы он не попадал в неправильное место при нажатии. Добавьте следующую строку, опять внизу: + 
    link.href = 'https://developer.mozilla.org';
    +
    6. +
+ +
+

Обратите внимание, что, как и во многих вещах в JavaScript, существует множество способов выбора элемента и хранения ссылки на него в переменной. {{domxref("Document.querySelector()")}} - рекомендуемый современный подход, который считается удобным, потому что он позволяет вам выбирать элементы с помощью селекторов CSS. Вышеупомянутый запрос querySelector() будет соответствовать первому элементу {{htmlelement("a")}}, который появляется в документе. Если вы хотите совместить и делать что-то с несколькими элементами, вы можете использовать {{domxref ("Document.querySelectorAll()")}}, который соответствует каждому элементу документа, который соответствует селектору и сохраняет ссылки на них в массиве массиво-подобном объекте, называемом NodeList.

+ +

Существуют более старые методы для захвата ссылок на элементы, например:

+ + + +

Эти два работают в более старых браузерах, чем современные методы, такие как querySelector(), но не так удобны. Осмотритесь и вы увидите, что ещё можно найти!

+
+ +

Создание и размещение новых узлов

+ +

Вышесказанное дало вам немного вкуса от того, что вы можете сделать, но давайте продолжим и посмотрим, как мы можем создавать новые элементы.

+ +
    +
  1. Возвращаясь к текущему примеру, давайте начнем с захвата ссылки на наш элемент {{htmlelement("section")}} - добавьте следующий код внизу существующего скрипта (сделайте то же самое с другими строками): + 
    var sect = document.querySelector('section');
    +
    2. +
  2. Теперь давайте создадим новый абзац, используя {{domxref("Document.createElement()")}} и передадим ему текстовое содержимое так же, как и раньше: + 
    var para = document.createElement('p');
+para.textContent = 'We hope you enjoyed the ride.';
    +
    3. +
  3. Теперь вы можете добавить новый абзац в конце раздела, используя {{domxref("Node.appendChild()")}}: + 
    sect.appendChild(para);
    +
    4. +
  4. Наконец, для этой части, давайте добавим текстовый узел в абзац, где находится ссылка, чтобы оформить предложение красиво. Сначала мы создадим текстовый узел, используя {{domxref("Document.createTextNode()")}}: + 
    var text = document.createTextNode(' — the premier source for web development knowledge.');
    +
    5. +
  5. Теперь мы возьмем ссылку на абзац, в котором находится ссылка, и добавим к нему текстовый узел: + 
    var linkPara = document.querySelector('p');
+linkPara.appendChild(text);
    +
    6. +
+ +

Это большая часть того, что вам нужно для добавления узлов в DOM - вы будете использовать эти методы при построении динамических интерфейсов (мы рассмотрим некоторые примеры позже).

+ +

Перемещение и удаление элементов

+ +

Могут быть моменты, когда вы хотите переместить узлы или вообще удалить их из DOM. Это вполне возможно.

+ +

Если бы мы хотели переместить абзац со ссылкой внутри него в нижней части раздела, мы могли бы просто сделать это:

+ +
sect.appendChild(linkPara);
+ +

Это переводит абзац вниз в нижнюю часть раздела. Вы могли подумать, что это сделает вторую копию, но это не так - linkPara - ссылка на единственную копию этого абзаца. Если вы хотите сделать копию и добавить ее также, вам нужно будет использовать {{domxref("Node.cloneNode()")}}.

+ +

Удаление узла довольно просто, по крайней мере, когда у вас есть ссылка на удаляемый узел и его родительский элемент. В нашем случае мы просто используем {{domxref("Node.removeChild()")}}, например:

+ +
sect.removeChild(linkPara);
+ +

Он становится немного сложнее, если вы хотите удалить узел, основанный только на ссылке на себя, что довольно часто. Нет способа сообщить узлу удалить себя, поэтому вам нужно будет сделать следующее.

+ +
linkPara.parentNode.removeChild(linkPara);
+ +

Попробуйте добавить вышеуказанные строки в свой код.

+ +

Управление стилями

+ +

Можно управлять стилями CSS с помощью JavaScript различными способами.

+ +

Для начала вы можете получить список всех таблиц стилей, прикрепленных к документу, с помощью {{domxref("Document.stylesheets")}}, который возвращает массив объектов {{domxref("CSSStyleSheet")}}. Затем вы можете добавлять / удалять стили по желанию. Однако мы не будем расширять эти функции, потому что они являются несколько архаичным и трудным способом манипулирования стилем. Есть гораздо более простые способы.

+ +

Первый способ - добавить встроенные стили непосредственно на элементы, которые вы хотите динамически стилизовать. Это делается с помощью свойства {{domxref("HTMLElement.style")}}, которое содержит встроенную информацию о стиле для каждого элемента документа. Вы можете установить свойства этого объекта для непосредственного обновления стилей элементов.

+ +
    +
  1. В качестве примера попробуйте добавить эти строки в наш текущий пример: + 
    para.style.color = 'white';
+para.style.backgroundColor = 'black';
+para.style.padding = '10px';
+para.style.width = '250px';
+para.style.textAlign = 'center';
    +
    2. +
  2. Перезагрузите страницу, и вы увидите, что стили были применены к абзацу. Если вы посмотрите на этот параграф в инспекторе Page Inspector/DOM inspector вашего браузера, вы увидите, что эти строки действительно добавляют встроенные стили в документ: + 
    <p style="color: white; background-color: black; padding: 10px; width: 250px; text-align: center;">We hope you enjoyed the ride.</p>
    +
    3. +
+ +
+

Примечание: Обратите внимание на то, как версии свойств JavaScript стилей CSS пишутся в нижнем регистре верблюжьего стиля (lower camel case), в то время как версии свойств стилей CSS используют дефисы  (например, backgroundColor и background-color). Убедитесь, что вы не перепутали их, иначе это не сработает.

+
+ +

Существует еще один распространенный способ динамического управления стилями вашего документа, который мы рассмотрим сейчас.

+ +
    +
  1. Удалите предыдущие пять строк, добавленных в JavaScript.
    2. +
  2. Добавьте в свой HTML-код следующее: {{htmlelement("head")}}: + 
    <style>
+.highlight {
+  color: white;
+  background-color: black;
+  padding: 10px;
+  width: 250px;
+  text-align: center;
+}
+</style>
    +
    3. +
  3. Теперь мы перейдем к очень полезному методу для общего манипулирования HTML - {{domxref("Element.setAttribute()")}} - это принимает два аргумента, атрибут, который вы хотите установить для элемента, и значение, которое вы хотите для его установки. В этом случае мы укажем имя класса выделения в нашем абзаце: + 
    para.setAttribute('class', 'highlight');
    +
    4. +
  4. Обновите свою страницу, и вы не увидите изменений - CSS по-прежнему применяется к абзацу, но на этот раз, предоставив ему класс, который выбран нашим правилом CSS, а не как встроенные стили CSS.
    5. +
+ +

Какой метод вы выбираете, зависит от вас; оба имеют свои преимущества и недостатки. Первый метод принимает меньше настроек и хорош для простого использования, тогда как второй метод более пурист (без смешивания CSS и JavaScript, без встроенных стилей, которые рассматриваются как плохая практика). Когда вы начнете создавать более крупные приложения, вы, вероятно, начнете использовать второй метод больше, но это действительно зависит от вас.

+ +

На данный момент мы не сделали ничего полезного! Нет смысла использовать JavaScript для создания статического контента - вы можете просто записать его в свой HTML и не использовать JavaScript. Это сложнее, чем HTML, и для создания вашего контента с помощью JavaScript также есть другие связанные с ним проблемы (например, не читаемые поисковыми системами).

+ +

В следующих параграфах мы рассмотрим еще несколько практических применений DOM API.

+ +
+

Примечание. Вы можете найти наш пример finished version of the dom-example.html на GitHub (см. также live).

+
+ +

Активное обучение: динамический список покупок

+ +

До сих пор мы действительно смотрели на использование функций {{domxref("Node")}} и {{domxref("Document")}} для управления документами, но нет причин, по которым вы не можете получить данные из других источников и использовать его в пользовательском интерфейсе. Вспомните нашу простую демонстрацию maps-example.html из последней статьи - там мы извлекли некоторые данные о местоположении и использовали ее для отображения карты вашей области. Вам просто нужно убедиться, что ваши данные в правильном формате; JavaScript упрощает работу, чем многие другие языки, будучи слабо типизированным - например, числа автоматически преобразуются в строки, когда вы хотите распечатать их на экране.

+ +

В этом примере мы решим общую проблему: убедитесь, что ваше приложение имеет размер как окно, в котором он просматривается, независимо от его размера. Это часто полезно в таких ситуациях, как игры, где вы хотите использовать как можно большую площадь экрана, чтобы играть в игру.

+ +

Для начала создайте локальную копию наших демо-файлов window-resize-example.html и bgtile.png. Откройте его и посмотрите - вы увидите, что у нас есть элемент {{htmlelement("div")}}, который покрывает небольшую часть экрана, на который нанесена фоновая плитка. Мы будем использовать это, чтобы представить нашу область пользовательского интерфейса приложения.

+ +
    +
  1. Прежде всего, давайте возьмем ссылку на div, а затем возьмем ширину и высоту окна просмотра (внутреннее окно, где отображается ваш документ) и сохраните их в переменных - эти два значения удобно содержатся в {{domxref("Window.innerWidth")}} и {{domxref("Window.innerHeight")}}. Добавьте следующие строки внутри существующего элемента {{htmlelement("script")}}: + 
    var div = document.querySelector('div');
+var WIDTH = window.innerWidth;
+var HEIGHT = window.innerHeight;
    +
    2. +
  2. Затем мы динамически изменяем ширину и высоту div, равную ширине окна просмотра. Добавьте следующие две строки ниже своих первых: + 
    div.style.width = WIDTH + 'px';
+div.style.height = HEIGHT + 'px';
    +
    3. +
  3. Сохраните и попробуйте обновить браузер - теперь вы должны увидеть, что div становится таким же большим, как ваш видовой экран, независимо от того, какой размер экрана вы используете. Если теперь вы попытаетесь изменить размер окна, чтобы увеличить его, вы увидите, что div остается одного размера - мы устанавливаем его только один раз.
    4. +
  4. Как насчет того, чтобы мы использовали событие, чтобы размер div изменялся при изменении размера окна? Объект {{domxref("Window")}} имеет событие, имеющееся на нем с именем resize, которое запускается каждый раз при изменении размера окна - давайте обратимся к нему через обработчик событий {{domxref("Window.onresize")}} и повторяйте наш размерный код каждый раз, когда он изменяется. Добавьте нижеследующую часть кода: + 
    window.onresize = function() {
+  WIDTH = window.innerWidth;
+  HEIGHT = window.innerHeight;
+  div.style.width = WIDTH + 'px';
+  div.style.height = HEIGHT + 'px';
+}
    +
    5. +
+ +
+

Примечание. Если у вас возникла проблема, посмотрите на наш законченный пример изменения размера окна (см. также live).

+
+ +

Активное обучение: динамический список покупок

+ +

Чтобы завершить статью, мы хотели бы задать вам небольшой вызов - мы хотим сделать простой пример списка покупок, который позволяет динамически добавлять элементы в список с помощью ввода формы и кнопки. Когда вы добавляете элемент на вход и нажимаете кнопку:

+ + + +

Готовое демо будет выглядеть примерно так:

+ +

+ +

Чтобы завершить упражнение, выполните следующие действия и убедитесь, что список ведет себя так, как описано выше.

+ +
    +
  1. Для начала загрузите копию нашего начального файла shopping-list.html и скопируйте его где-нибудь. Вы увидите, что у него есть минимальный CSS, список с меткой, ввод и кнопка, пустой список и элемент {{htmlelement("script")}}. Вы будете делать все свои дополнения внутри скрипта.
    2. +
  2. Создайте три переменные, содержащие ссылки на список ({{htmlelement("ul")}}, {{htmlelement("input")}} и {{htmlelement("button")}} элементы.
    3. +
  3. Создайте function, которая будет запускаться в ответ на нажатие кнопки.
    4. +
  4. Внутри тела функции начните с сохранения текущего значения (value) входного элемента в переменной.
    5. +
  5. Затем очистите элемент ввода, установив его значение в пустую строку — ''.
    6. +
  6. Создайте три новых элемента - элемент списка ({{htmlelement('li')}}), {{htmlelement('span')}} и {{htmlelement('button')}} и сохраните их в переменных.
    7. +
  7. Добавьте диапазон и кнопку в качестве дочерних элементов списка.
    8. +
  8. Установите текстовое содержимое диапазона на значение входного элемента, которое вы сохранили ранее, и текстовое содержимое кнопки «Удалить».
    9. +
  9. Добавить элемент списка в качестве дочернего списка.
    10. +
  10. Прикрепите обработчик события к кнопке удаления, чтобы при щелчке удалял весь элемент списка, внутри которого он находится.
    11. +
  11. Наконец, используйте метод focus(), чтобы сфокусировать входной элемент, готовый для входа в следующий элемент списка покупок.
    12. +
+ +
+

Примечание: Если у вас возникла действительно сложная проблема, взгляните на наши примеры finished shopping list (see it running live also.)

+
+ +

Краткая информация

+ +

Мы закончили изучение документа и манипулирования DOM. На этом этапе вы должны понимать, что важная часть веб-браузера связана с управлением документами и другими аспектами веб-интерфейса пользователя. Самое главное, вы должны понять, что такое Document Object Model, и как манипулировать им для создания полезных функций.

+ +

Дополнительная информация

+ +

Есть много возможностей, которые можно использовать для управления вашими документами. Ознакомьтесь с некоторыми нашими рекомендациями и узнайте, что вы можете обнаружить:

+ + + +

(Полный список веб-индексов API, задокументированных MDN: Web API index)

+ +
{{PreviousMenuNext("Learn/JavaScript/Client-side_web_APIs/Introduction", "Learn/JavaScript/Client-side_web_APIs/Fetching_data", "Learn/JavaScript/Client-side_web_APIs")}}
+ +
+

В этот модуль входит

+ + +
diff --git a/files/ru/learn/javascript/client-side_web_apis/third_party_apis/index.html b/files/ru/learn/javascript/client-side_web_apis/third_party_apis/index.html new file mode 100644 index 0000000000..4977fe99c7 --- /dev/null +++ b/files/ru/learn/javascript/client-side_web_apis/third_party_apis/index.html @@ -0,0 +1,482 @@ +--- +title: Сторонние API +slug: Learn/JavaScript/Client-side_web_APIs/Third_party_APIs +tags: + - 3rd party + - API + - Third party + - Новичку +translation_of: Learn/JavaScript/Client-side_web_APIs/Third_party_APIs +--- +
{{LearnSidebar}}{{PreviousMenuNext("Learn/JavaScript/Client-side_web_APIs/Fetching_data", "Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Learn/JavaScript/Client-side_web_APIs")}}
+ +

API, которые мы рассмотрели до сих пор, встроены в браузер, но не все API таковы. Многие крупные веб-сайты и сервисы, такие как Google Maps, Twitter, Facebook, PayPal и т. д., Предоставляют API-интерфейсы, позволяющие разработчикам использовать свои данные (например, показывать ваш твиттер-поток в вашем блоге) или сервисы (например, отображение пользовательских карт Google на вашем сайте, или использование логина Facebook для входа в систему ваших пользователей). В этой статье рассматривается различие между API-интерфейсами браузера и сторонними API и показано типичное использование последних.

+ + + + + + + + + + + + +
Необходимые условия:Основы JavaScript (см. первые шаги, структурные элементы, объекты JavaScript), the основы клиентских API
Задача:Изучить, как работают сторонние API, и как использовать их для улучшения ваших сайтов.
+ +

Что такое сторонние API?

+ +

Сторонние API - это API, предоставляемые третьими лицами — как правило, такими компаниями, как Facebook, Twitter, or Google — чтобы вы могли получить доступ к их функциям с помощью JavaScript и использовать его на своем собственном сайте. Как мы показали в нашей вводной статье об API, одним из наиболее очевидных примеров является использование Google Maps APIs для отображения пользовательских карт на ваших страницах.

+ +

Давайте снова посмотрим на наш пример карты (см. исходный код на GitHub; см. это в действии),  и используем его для иллюстрации того, как сторонние API отличаются от API-интерфейсов браузера.

+ +
+

Примечание: По умолчанию использование сторонних API на вашем сайте позволит им отслеживать файлы cookie своих доменов, устанавливать файлы cookie в исходное состояние, получать заголовки ссылок, определяющие посещаемые страницы, и разрешать им выполнять JavaScript на страницах, на которых они загружаются с теми же разрешениями (например, выполнить запросы AJAX на ваши серверы с теми же кукисами сеанса). Должны быть оценены вопросы регулирования, безопасности и конфиденциальности.

+
+ +
+

Примечание: Возможно, вы захотите сразу получить все наши примеры кода, в этом случае вы можете просто искать репо для файлов примеров, которые вам нужны в каждом разделе.

+
+ +

Они находятся на сторонних серверах

+ +

API браузера встроены в браузер - вы можете получить к ним доступ сразу из JavaScript. Например, API геолокации, доступный в нашем примере, осуществляется с использованием свойства геолокации объекта Navigator, которое возвращает объект Geolocation. Этот пример использует метод getCurrentPosition() этого объекта, для запроса текущего положения устройства:

+ +
navigator.geolocation.getCurrentPosition(function(position) { ... });
+ +

Сторонние API, с другой стороны, расположены на сторонних серверах. Чтобы получить доступ к ним из JavaScript, вам сначала нужно подключиться к функциям API и сделать его доступным на вашей странице. Обычно это связано с первой ссылкой на библиотеку JavaScript, доступную на сервере через элемент {{htmlelement("script")}}, как показано в нашем примере:

+ +
<script type="text/javascript" src="https://maps.google.com/maps/api/js?key=AIzaSyDDuGt0E5IEGkcE6ZfrKfUtE9Ko_de66pA"></script>
+ +

Затем вы можете начать использовать объекты, доступные в этой библиотеке. Например:

+ +
var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);
+var myOptions = {
+  zoom: 8,
+  center: latlng,
+  mapTypeId: google.maps.MapTypeId.TERRAIN,
+  disableDefaultUI: true
+}
+
+var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);
+ +

Здесь мы создаем новый объект LatLng, используя конструктор google.maps.LatLng(), который содержит широту и долготу местоположения, которое мы хотим показать, полученные из API геолокации. Затем мы создаем объект опций (myOptions), содержащий эту и другую информацию, связанную с отображением карты. Наконец, мы фактически создаем карту, используя конструктор google.maps.Map(), который принимает в качестве параметров элемент, на котором мы хотим нарисовать карту, и объект опций.

+ +

Это вся информация, которую API Карт Google требует для построения простой карты. Сервер, к которому вы подключаетесь, обрабатывает все сложные вещи, такие как отображение правильных фрагментов карты для отображаемой области и т. д.

+ +
+

Примечание: Некоторые API обрабатывают доступ к их функциям несколько иначе, требуя от разработчика сделать HTTP-запрос (см. Получение данных с сервера) на определенный шаблон URL для получения определенных данных. Они называются RESTful API, и мы покажем пример этого позже в статье.

+
+ +

Разрешения обрабатываются по-разному

+ +

Безопасность API-интерфейсов браузеров, как правило, обрабатывается запросами разрешения, как описано в нашей первой статье. Целью этого является то, что пользователь знает, что происходит на сайтах, которые он посещает, и с меньшей вероятностью может стать жертвой того, кто использует API, злонамеренно.

+ +

Сторонние API имеют немного другую систему разрешений - они, как правило, используют ключевые коды, чтобы позволить разработчикам получить доступ к функциям API. Просмотрите URL-адрес библиотеки API Карт Google, с которой мы связались:

+ +
https://maps.google.com/maps/api/js?key=AIzaSyDDuGt0E5IEGkcE6ZfrKfUtE9Ko_de66pA
+ +

Параметр URL, указанный в конце URL-адреса, является ключом разработчика - разработчик приложения должен применять его для получения ключа, а затем включать его в свой код определенным образом, чтобы иметь доступ к функциям API. В случае с Картами Google (и другими API Google) вы подаете заявку на получение ключа на Google Cloud Platform.

+ +

Другие API могут потребовать, чтобы вы включили ключ немного по-другому, но шаблон для большинства из них довольно схож. 
+  
+ Требование к ключу заключается в том, что не каждый может использовать функциональность API без какой-либо подотчетности. Когда разработчик зарегистрировался для ключа, они затем известны поставщику API, и действие может быть предпринято, если они начинают делать что-то вредоносное с помощью API (например, отслеживать местоположение пользователей или пытаться спамить API с множеством запросов для остановки его работы, например). Самое простое действие - просто отменить их привилегии API.

+ +

Расширенный пример Карт Google

+ +

Теперь когда мы рассмотрели пример API Карт Google и посмотрели, как он работает, добавим еще несколько функций, чтобы показать, как использовать некоторые другие функции API.

+ +
    +
  1. +

    Чтобы начать этот раздел, сделайте себе копию исходного файла Карт Google, в новой папке. Если Вы уже клонировали репозиторий примеров, у вас уже есть копия этого файла, которую Вы можете найти в папке the javascript/apis/third-party-apis/google-maps.

    +
    2. +
  2. +

    Затем получите свой собственный ключ разработчика, выполнив следующие шаги:

    + +
      +
    1. Перейдите в панель управления API-интерфейсом Google Cloud Platform.
      2. +
    2. Создайте новый проект, если у вас его еще нет.
      3. +
    3. Нажмите кнопку Enable API.
      4. +
    4. Выберите Google Maps JavaScript API.
      5. +
    5. Нажмите кнопку Enable.
      6. +
    6. Нажмите Create credentials, затем выберите API key.
      7. +
    7. Скопируйте свой ключ API и замените существующий ключ в первом элементе {{htmlelement ('script')}} примера вашим собственным (фрагмент между ?key= и меткой закрытия закрытия атрибута (").)
      8. +
    + +
    +

    Примечание: Получение ключей API, связанных с Google, может быть немного затруднительным: в Менеджере API Google Cloud Platform много разных экранов, и рабочий процесс может немного отличаться в зависимости от того, как у вас уже установлена ​​учетная запись. Если у вас возникнут проблемы с этим шагом, мы будем рады помочь — Свяжитесь с нами.

    +
    +
    3. +
  3. Откройте исходный файл Карт Google, найдите строку INSERT-YOUR-API-KEY-HERE, и замените ее фактическим ключом API, который вы получили из панели управления Google Cloud Platform API Manager.
    4. +
+ +

Adding a custom marker

+ +

Adding a marker (icon) at a certain point on the map is easy — you just need to create a new marker using the google.maps.Marker() constructor, passing it an options object containing the position to display the marker at (as a LatLng object), and the Map object to display it on.

+ +
    +
  1. +

    Add the following just below the var map ... line:

    + + 
    var marker = new google.maps.Marker({
+  position: latlng,
+  map: map
+});
    + +

    Now if you refresh your page, you'll see a nice little marker pop up in the centre of the map. This is cool, but it is not exactly a custom marker — it is using the default marker icon.

    +
    2. +
  2. +

    To use a custom icon, we need to specify it when we create the marker, using its URL. First of all, add the following line above the previous block you added:

    + + 
    var iconBase = 'https://maps.google.com/mapfiles/kml/shapes/';
    + +

    This defines the base URL where all the official Google Maps icons are stored (you could also specify your own icon location if you wished).

    +
    3. +
  3. +

    The icon location is specified in the icon property of the options object. Update the constructor like so:

    + + 
    var marker = new google.maps.Marker({
+  position: latlng,
+  icon: iconBase + 'flag_maps.png',
+  map: map
+});
    + +

    Here we specify the icon property value as the iconBase plus the icon filename, to create the complete URL. Now try reloading your example and you'll see a custom marker displayed on your map!

    +
    4. +
+ +
+

Note: See Customizing a Google Map: Custom Markers for more information.

+
+ +
+

Note: See Map marker or Icon names to find out what other icons are available, and see what their reference names are. Their file name will be the icon name they display when you click on them, with ".png" added on the end.

+
+ +

Displaying a popup when the marker is clicked

+ +

Another common use case for Google Maps is displaying more information about a place when its name or marker is clicked (popups are called info windows in the Google Maps API). This is also very simple to achieve, so let's have a look at it.

+ +
    +
  1. +

    First of all, you need to specify a JavaScript string containing HTML that will define the content of the popup. This will be injected into the popup by the API and can contain just about any content you want. Add the following line below the google.maps.Marker() constructor definition:

    + + 
    var contentString = '<div id="content"><h2 id="firstHeading" class="firstHeading">Custom info window</h2><p>This is a cool custom info window.</p></div>';
    +
    2. +
  2. +

    Next, you need to create a new info window object using the google.maps.InfoWindow() constructor. Add the following below your previous line:

    + + 
    var infowindow = new google.maps.InfoWindow({
+  content: contentString
+});
    + +

    There are other properties available (see Info Windows), but here we are just specifying the content property in the options object, which points to the source of the content.

    +
    3. +
  3. +

    Finally, to get the popup to display when the marker is clicked, we use a simple click event handler. Add the following below the google.maps.InfoWindow() constructor:

    + + 
    marker.addListener('click', function() {
+  infowindow.open(map, marker);
+});
    + +

    Inside the function, we simply invoke the infowindow's open() function, which takes as parameters the map you want to display it on, and the marker you want it to appear next to.

    +
    4. +
  4. +

    Now try reloading the example, and clicking on the marker!

    +
    5. +
+ +

Controlling what map controls are displayed

+ +

Inside the original google.maps.Map() constructor, you'll see the property disableDefaultUI: true specified. This disables all the standard UI controls you usually get on Google Maps.

+ +
    +
  1. +

    Try setting its value to false (or just removing the line altogether) then reloading your example, and you'll see the map zoom buttons, scale indicator, etc.

    +
    2. +
  2. +

    Now undo your last change.

    +
    3. +
  3. +

    You can show or hide the controls in a more granular fashion by using other properties that specify single UI features. Try adding the following underneath the disableDefaultUI: true (remember to put a comma after disableDefaultUI: true, otherwise you'll get an error):

    + + 
    zoomControl: true,
+mapTypeControl: true,
+scaleControl: true,
    +
    4. +
  4. +

    Now try reloading the example to see the effect these properties have. You can find more options to experiment with at the MapOptions object reference page.

    +
    5. +
+ +

That's it for now — have a look around the Google Maps APIs documentation, and have some more fun playing!

+ +

A RESTful API — NYTimes

+ +

Now let's look at another API example — the New York Times API. This API allows you to retrieve New York Times news story information and display it on your site. This type of API is known as a RESTful API — instead of getting data using the features of a JavaScript library like we did with Google Maps, we get data by making HTTP requests to specific URLs, with data like search terms and other properties encoded in the URL (often as URL parameters). This is a common pattern you'll encounter with APIs.

+ +

An approach for using third-party APIs

+ +

Below we'll take you through an exercise to show you how to use the NYTimes API, which also provides a more general set of steps to follow that you can use as an approach for working with new APIs.

+ +

Find the documentation

+ +

When you want to use a third party API, it is essential to find out where the documentation is, so you can find out what features the API has, how you use them, etc. The New York Times API documentation is at https://developer.nytimes.com/.

+ +

Get a developer key

+ +

Most APIs require you to use some kind of developer key, for reasons of security and accountability. To sign up for an NYTimes API key, you need to go to https://developer.nytimes.com/signup.

+ +
    +
  1. +

    Let's request a key for the "Article Search API" — fill in the form, selecting this as the API you want to use.

    +
    2. +
  2. +

    Next, wait a few minutes, then get the key from your email.

    +
    3. +
  3. +

    Now, to start the example off, make copies of nytimes_start.html and nytimes.css in a new directory on your computer. If you've already cloned the examples repository, you'll already have a copy of these files, which you can find in the javascript/apis/third-party-apis/nytimes directory. Initially the <script> element contains a number of variables needed for the setup of the example; below we'll fill in the required functionality.

    +
    4. +
+ +

The app will end up allowing you to type in a search term and optional start and end dates, which it will then use to query the Article Search API and display the search results.

+ +

+ +

Connect the API to your app

+ +

First, you'll need to make a connection between the API, and your app. This is usually done either by connecting to the API's JavaScript (as we did in the Google Maps API), or by making requests to the correct URL(s).

+ +

In the case of this API, you need to include the API key as a get parameter every time you request data from it.

+ +
    +
  1. +

    Find the following line:

    + + 
    var key = 'INSERT-YOUR-API-KEY-HERE';
    + +

    Replace INSERT-YOUR-API-KEY-HERE with the actual API key you got in the previous section.

    +
    2. +
  2. +

    Add the following line to your JavaScript, below the "// Event listeners to control the functionality" comment. This runs a function called fetchResults() when the form is submitted (the button is pressed).

    + + 
    searchForm.addEventListener('submit', submitSearch);
    +
    3. +
  3. +

    Now add the submitSearch() and fetchResults() function definitions, below the previous line:

    + + 
    function submitSearch(e) {
+  pageNumber = 0;
+  fetchResults(e);
+}
+
+function fetchResults(e) {
+  // Use preventDefault() to stop the form submitting
+  e.preventDefault();
+
+  // Assemble the full URL
+  url = baseURL + '?api-key=' + key + '&page=' + pageNumber + '&q=' + searchTerm.value + '&fq=document_type:("article")';
+
+  if(startDate.value !== '') {
+    url += '&begin_date=' + startDate.value;
+  };
+
+  if(endDate.value !== '') {
+    url += '&end_date=' + endDate.value;
+  };
+
+}
    +
    4. +
+ +

submitSearch() sets the page number back to 0 to begin with, then calls fetchResults(). This first calls preventDefault() on the event object, to stop the form actually submitting (which would break the example). Next, we use some string manipulation to assemble the full URL that we will make the request to. We start off by assembling the parts we deem as mandatory for this demo:

+ + + +

Next, we use a couple of if() statements to check whether the startDate and endDate <input>s have had values filled in on them. If they do, we append their values to the URL, specified in begin_date and end_date URL parameters respectively.

+ +

So, a complete URL would end up looking something like this:

+ +
https://api.nytimes.com/svc/search/v2/articlesearch.json?api-key=4f3c267e125943d79b0a3e679f608a78&page=0&q=cats
+&fq=document_type:("article")&begin_date=20170301&end_date=20170312
+ +
+

Note: You can find more details of what URL parameters can be included in the Article Search API reference.

+
+ +
+

Note: The example has rudimentary form data validation — the search term field has to be filled in before the form can be submitted (achieved using the required attribute), and the date fields have pattern attributes specified, which means they won't submit unless their values consist of 8 numbers (pattern="[0-9]{8}"). See Form data validation for more details on how these work.

+
+ +

Requesting data from the API

+ +

Now we've constructed our URL, let's make a request to it. We'll do this using the Fetch API.

+ +

Add the following code block inside the fetchResults() function, just above the closing curly brace:

+ +
// Use fetch() to make the request to the API
+fetch(url).then(function(result) {
+  return result.json();
+}).then(function(json) {
+  displayResults(json);
+});
+ +

Here we run the request by passing our url variable to fetch(), convert the response body to JSON using the json() function, then pass the resulting JSON to the displayResults() function so the data can be displayed in our UI.

+ +

Displaying the data

+ +

OK, let's look at how we'll display the data. Add the following function below your fetchResults() function.

+ +
function displayResults(json) {
+  while (section.firstChild) {
+      section.removeChild(section.firstChild);
+  }
+
+  var articles = json.response.docs;
+
+  if(articles.length === 10) {
+    nav.style.display = 'block';
+  } else {
+    nav.style.display = 'none';
+  }
+
+  if(articles.length === 0) {
+    var para = document.createElement('p');
+    para.textContent = 'No results returned.'
+    section.appendChild(para);
+  } else {
+    for(var i = 0; i < articles.length; i++) {
+      var article = document.createElement('article');
+      var heading = document.createElement('h2');
+      var link = document.createElement('a');
+      var img = document.createElement('img');
+      var para1 = document.createElement('p');
+      var para2 = document.createElement('p');
+      var clearfix = document.createElement('div');
+
+      var current = articles[i];
+      console.log(current);
+
+      link.href = current.web_url;
+      link.textContent = current.headline.main;
+      para1.textContent = current.snippet;
+      para2.textContent = 'Keywords: ';
+      for(var j = 0; j < current.keywords.length; j++) {
+        var span = document.createElement('span');
+        span.textContent += current.keywords[j].value + ' ';
+        para2.appendChild(span);
+      }
+
+      if(current.multimedia.length > 0) {
+        img.src = 'http://www.nytimes.com/' + current.multimedia[0].url;
+        img.alt = current.headline.main;
+      }
+
+      clearfix.setAttribute('class','clearfix');
+
+      article.appendChild(heading);
+      heading.appendChild(link);
+      article.appendChild(img);
+      article.appendChild(para1);
+      article.appendChild(para2);
+      article.appendChild(clearfix);
+      section.appendChild(article);
+    }
+  }
+};
+ +

There's a lot of code here; let's explain it step by step:

+ + + +

If you try the example now, it should work, although the pagination buttons won't work yet.

+ +

Wiring up the pagination buttons

+ +

To make the pagination buttons work, we will increment (or decrement) the value of the pageNumber variable, and then re-rerun the fetch request with the new value included in the page URL parameter. This works because the NYTimes API only returns 10 results at a time — if more than 10 results are available, it will return the first 10 (0-9) if the page URL parameter is set to 0 (or not included at all — 0 is the default value), the next 10 (10-19) if it is set to 1, and so on.

+ +

This allows us to easily write a simplistic pagination function.

+ +
    +
  1. +

    Below the existing addEventListener() call, add these two new ones, which cause the nextPage() and previousPage() functions to be invoked when the relevant buttons are clicked:

    + + 
    nextBtn.addEventListener('click', nextPage);
+previousBtn.addEventListener('click', previousPage);
    +
    2. +
  2. +

    Below your previous addition, let's define the two functions — add this code now:

    + + 
    function nextPage(e) {
+  pageNumber++;
+  fetchResults(e);
+};
+
+function previousPage(e) {
+  if(pageNumber > 0) {
+    pageNumber--;
+  } else {
+    return;
+  }
+  fetchResults(e);
+};
    + +

    The first function is simple — we increment the pageNumber variable, then run the fetchResults() function again to display the next page's results.

    + +

    The second function works nearly exactly the same way in reverse, but we also have to take the extra step of checking that pageNumber is not already zero before decrementing it — if the fetch request runs with a minus page URL parameter, it could cause errors. If the pageNumber is already 0, we simply return out of the function, to avoid wasting processing power (If we are already at the first page, we don't need to load the same results again).

    +
    3. +
+ +

YouTube example

+ +

We also built another example for you to study and learn from — see our YouTube video search example. This uses two related APIs:

+ + + +

This example is interesting because it shows two related third-party APIs being used together to build an app. The first one is a RESTful API, while the second one works more like Google Maps (with constructors, etc.). It is worth noting however that both of the APIs require a JavaScript library to be applied to the page. The RESTful API has functions available to handle making the HTTP requests and returning the results, so you don't have to write them out yourself using say fetch or XHR.

+ +

+ +

We are not going to say too much more about this example in the article — the source code has detailed comments inserted inside it to explain how it works.

+ +

Summary

+ +

This article has given you a useful introduction to using third party APIs to add functionality to your websites.

+ +

{{PreviousMenuNext("Learn/JavaScript/Client-side_web_APIs/Fetching_data", "Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Learn/JavaScript/Client-side_web_APIs")}}

+ +

 

+ +

In this module

+ + -- cgit v1.2.3-54-g00ecf