jQuery метод .finish()

Определение и применение

jQuery метод .finish() останавливает все выполняющиеся в настоящее время анимации, удаляет все очереди анимаций и завершает все анимации для выбранных элементов.

Обращаю Ваше внимание, что вы можете остановить все анимации глобально, для этого необходимо установить свойство глобального объекта $.fx.off в логическое значение true. Когда это будет сделано, все методы анимации немедленно установят элементы в их окончательное состояние при вызове (без отображения эффекта анимации). Кроме того, вы можете воспользоваться методом .stop(), который позволяет остановить выполняемую анимацию у выбранных элементов.

jQuery синтаксис:

Синтаксис 1.9:
// останавливает все выполняющиеся в настоящее время анимации
$( selector ).finish() 

// останавливает все выполняющиеся в настоящее время анимации с определенной очередью
$( selector ).finish( queue ) 

queue - String

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

Метод .finish() аналогичен вызову метода .stop( true, true ) в том, что он очищает очередь и текущая анимация переходит к ее конечному значению, однако, отличие метода .finish() заключается в том, что он также устанавливает все CSS свойства для всех анимаций в очереди к их конечным значениям.

Добавлен в версии jQuery

1.9

Значения параметров

Параметр	Описание
queue	Строковое значение, определяющее имя очереди, в которой необходимо остановить анимацию. По умолчанию используется очередь стандартных эффектов `fx`. Необязательный параметр.

Пример использования

<!DOCTYPE html>
<html>
	<head>
		<title>Пример использования jQuery методов .finish() и .stop()</title>
		<style>div {
	width: 80px; /* ширина элемента */	
	height: 80px; /* высота элемента */	
	border: 2px solid orange; /* сплошная граница размером 2 пикселя оранжевого цвета */	
	margin-top: 50px; /* внешний отступ от верхнего края элемента */
}
</style>
		<script src = "https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
		<script>
	$( document ).ready(function(){
	  // функция выполняющая анимации элемента
	  function first() {
	    $( "div" ).css( "width", "80px" ) // устанавливаем ширину элемента равную 80 пикселей
                      .animate({width: "30%"}, 2000) // анимируем увеличение ширины элемента до 30% за 2 секунды
                      .animate({width: "50%"}, 2000) // анимируем увеличение ширины элемента до 50% за 2 секунды
                      .animate({width: "70%"}, 2000) // анимируем увеличение ширины элемента до 70% за 2 секунды
                      .animate({width: "90%"}, 2000);// анимируем увеличение ширины элемента до 90% за 2 секунды
	  }
	  
	  $( ".start" ).click(function(){ // задаем функцию при нажатии на элемент с классом start 
	    first() // запускаем функцию
	  });
		
	  $( ".finish" ).click(function(){ // задаем функцию при нажатии на элемент с классом finish 
	    $( "div" ).finish(); // останавливаем все выполняющиеся в настоящее время анимации, удаляем все очереди анимаций, и завершаем все анимации 
	  });
		
	  $( ".stop" ).click(function(){ // задаем функцию при нажатии на элемент с классом stop 
	    $( "div" ).stop(); // останавливаем выполняемую анимацию
	  });

	  $( ".stop2" ).click(function(){ // задаем функцию при нажатии на элемент с классом stop2 
	    $( "div" ).stop( true, true ); // останавливаем все выполняющиеся в настоящее время анимации, удаляем все очереди анимаций, и завершаем все анимации 
	  });
	});
		</script>
	</head>
	<body>
		<button class = "start">start</button>
		<button class = "finish">finish()</button>
		<button class = "stop">stop()</button>
		<button class = "stop2">stop( true, true )</button>
		<div></div>
	</body>
</html>

В этом примере мы разместили в документе один элемент <div> и четыре кнопки (элементы <button>), для каждой назначили обработчик события "click" (клик левой кнопкой мыши):

При нажатии на элемент с классом start вызываем функцию, которая запускает функцию first(), которая выполняет анимации элемента <div>. Функция с помощью метода .css() устанавливает элементу первоначальную ширину, заданную в стилях, это необходимо для возможности перезапуска анимации, затем с помощью методов .animate() поочередно запускает четыре различных анимации, которые увеличивают ширину элемента, длительностью 2 секунды каждая.
При нажатии на элемент с классом finish вызываем функцию, которая с помощью метода finish() останавливает все выполняющиеся в настоящее время анимации, удаляет все очереди анимаций и завершает все анимации у выбранного элемента <div>. Обратите внимание на важный момент, метод finish() также устанавливает все CSS свойства для всех анимаций в очереди к их конечным значениям, в результате элемент получит значение ширины равное 90%.
При нажатии на элемент с классом stop вызываем функцию, которая с помощью метода .stop() останавливает текущую анимацию у выбранного элемента <div>, следующая анимация в очереди при этом начинает проигрываться.
При нажатии на элемент с классом stop2 вызываем функцию, которая с помощью метода .stop() оостанавливает все выполняющиеся в настоящее время анимации, удаляет все очереди анимаций и завершает все анимации у выбранного элемента <div>. Это аналогично использованию метода finish, за тем исключением, что CSS свойства не устанавливаются к их конечным значениям.

Результат нашего примера:

Пример использования jQuery методов .finish() и .stop()

Рассмотрим следующий пример в котором с помощью метода .finish() мы будем останавливать элемент в зависимости от его имени очереди:

<!DOCTYPE html>
<html>
	<head>
		<title>Использование jQuery метода .finish() (остановка анимации с определенной очередью)</title>
		<style>div {
	width: 80px; /* ширина элемента */	
	height: 80px; /* высота элемента */	
	border: 2px solid orange; /* сплошная граница размером 2 пикселя оранжевого цвета */	
	margin-top: 50px; /* внешний отступ от верхнего края элемента */
}
</style>
		<script src = "https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
		<script>
	$( document ).ready(function(){
	  // функция выполняющая анимации элемента с классом first
	  function animateFirst() {
	    $( ".first" ).css( "width", "80px" ) // устанавливаем ширину элемента равную 80 пикселей
                         .animate({width: "30%"}, {duration: 2000, queue: "myAnimation"}) // анимируем увеличение ширины элемента до 30% за 2 секунды и устанавливаем имя очереди
                         .animate({width: "50%"}, {duration: 2000, queue: "myAnimation"}) // анимируем увеличение ширины элемента до 50% за 2 секунды и устанавливаем имя очереди
                         .animate({width: "70%"}, {duration: 2000, queue: "myAnimation"}) // анимируем увеличение ширины элемента до 70% за 2 секунды и устанавливаем имя очереди
                         .animate({width: "90%"}, {duration: 2000, queue: "myAnimation"});// анимируем увеличение ширины элемента до 90% за 2 секунды и устанавливаем имя очереди
	    $( ".first" ).dequeue( "myAnimation" ); // выполняем для выбранного элемента функцию из очереди под именем myAnimation
	  }

	  // функция выполняющая анимации элемента с классом second
	  function animateSecond() {
	    $( ".second" ).css( "width", "80px" ) // устанавливаем ширину элемента равную 80 пикселей
                         .animate({width: "30%"}, {duration: 2000, queue: "myAnimation2"}) // анимируем увеличение ширины элемента до 30% за 2 секунды и устанавливаем имя очереди
                         .animate({width: "50%"}, {duration: 2000, queue: "myAnimation2"}) // анимируем увеличение ширины элемента до 50% за 2 секунды и устанавливаем имя очереди
                         .animate({width: "70%"}, {duration: 2000, queue: "myAnimation2"}) // анимируем увеличение ширины элемента до 70% за 2 секунды и устанавливаем имя очереди
                         .animate({width: "90%"}, {duration: 2000, queue: "myAnimation2"});// анимируем увеличение ширины элемента до 90% за 2 секунды и устанавливаем имя очереди
	    $( ".second" ).dequeue( "myAnimation2" ); // выполняем для выбранного элемента функцию из очереди под именем myAnimation2
	  }

	  $( ".start" ).click(function(){ // задаем функцию при нажатии на элемент с классом start 
	    animateFirst();  // запускаем функцию
	    animateSecond(); // запускаем функцию
	  });
		
	  $( ".finish" ).click(function(){ // задаем функцию при нажатии на элемент с классом finish 
	    $( "div" ).finish( "myAnimation" ); // 
	    $( "div" ).finish( "myAnimation2" ); // 
	  });
		
	  $( ".finish2" ).click(function(){ // задаем функцию при нажатии на элемент с классом finish2 
	    $( "div" ).finish( "myAnimation" ); // 
	  });

	  $( ".finish3" ).click(function(){ // задаем функцию при нажатии на элемент с классом finish3 
	    $( "div" ).finish( "myAnimation2" ); // 
	  });
	});
		</script>
	</head>
	<body>
		<button class = "start">start</button>
		<button class = "finish">finish all queues</button>
		<button class = "finish2">finish("myAnimation")</button>
		<button class = "finish3">finish("myAnimation2")</button>
		<div class = "first"></div>
		<div class = "second"></div>
	</body>
</html>

В этом примере мы разместили в документе два элемента <div> и четыре кнопки (элементы <button>), для каждой назначили обработчик события "click" (клик левой кнопкой мыши):

При нажатии на элемент с классом start вызываем функцию, которая запускает функции animateFirst(), которая выполняет анимации элемента <div> с классом first и animateSecond(), которая выполняет анимации элемента <div> с классом second. Функции с помощью метода .css() устанавливают элементу первоначальную ширину, заданную в стилях, это необходимо для возможности перезапуска анимации, затем с помощью методов .animate() поочередно устанавливают четыре различных анимации, которые увеличивают ширину элемента, длительностью 2 секунды каждая. Обратите внимание на то, что в зависимости от функции дополнительно указывается имя очереди функций, в этом случае запуск анимаций возможен только с использованием метода .dequeue(), который мы используем для запуска анимаций в конце каждой функции.
При нажатии на элемент с классом finish вызываем функции, которые с помощью метода finish() останавливают все выполняющиеся в настоящее время анимации в очереди "myAnimation" и "myAnimation2", удаляет все очереди анимаций и завершает все анимации у выбранного элемента <div>. Важным нюансом здесь будет то, что если вы указываете имя очереди, то вызов метода finish(), вызванный без параметра, который указывает имя очереди не сработает и не остановит анимацию.
При нажатии на элемент с классом finish2 вызываем функцию, которая с помощью метода finish() останавливает все выполняющиеся в настоящее время анимации в очереди "myAnimation", удаляет все очереди анимаций и завершает все анимации у выбранного элемента <div>. Обратие внимание, что второй элемент, чье имя очереди анимации отличается продолжит выполнение своих анимаций.
При нажатии на элемент с классом finish3 вызываем функцию, которая с помощью метода finish() останавливает все выполняющиеся в настоящее время анимации в очереди "myAnimation2", удаляет все очереди анимаций и завершает все анимации у выбранного элемента <div>.

Результат нашего примера:

Пример использования jQuery метода .finish() (остановка анимации с определенной очередью)

jQuery эффекты