Проект:Технические работы/Разработчикам скриптов

Материал из Википедии — свободной энциклопедии
Перейти к навигации Перейти к поиску

Короткая ссылка-перенаправление

Здесь собраны некоторые советы разработчикам по написанию гаджетов и персональных скриптов.

Существенную помощь при написании скриптов может оказать знание JavaScript-интерфейса, включая свойства и методы объекта mw и объектов загружаемых модулей. Некоторые важные объекты: mw.config, mw.user.options, mw.util, mw.Title, mw.loader и mw.hook. Некоторые из модулей (включая jQuery) загружены по умолчанию, но большинство надо загружать при помощи mw.loader. Подробная документация по API.

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

( function () {

а в конец — 

}() );

См. также руководство по написанию персональных скриптов в английской Википедии.

Добавление кнопок на панели инструментов[править код]

Чтобы добавить кнопку на классическую (стандартную) панель инструментов и элемент меню в панель инструментов визуального редактора (включая его редактор кода, который на декабрь 2018 года носит название «⧼visualeditor-preference-newwikitexteditor-label⧽» и включается на странице бета-функций), рекомендуется использовать универсальную функцию registerTool(). Если вы имеете дело с гаджетом, он должен иметь в качестве зависимости модуль ext.gadget.registerTool. Если вы пишете персональный скрипт, используйте следующий код: 

mw.loader.using( 'ext.gadget.registerTool' ).done( function () {
	registerTool( {
		// Параметры инструмента, см. ниже
	} );
} );

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

Функция registerTool() вызывается в конце кода гаджета/скрипта и принимает в качестве параметра объект, задающий параметры гаджета/скрипта. Пример для гаджета упрощения ссылок: 

registerTool( {
	name: 'urldecoder',
	position: 200,
	title: 'Раскодировать URL',
	label: 'Раскодировать URL перед курсором или все URL в выделенном тексте',
	callback: urlDecoderRun,
	classic: {
		icon: '//upload.wikimedia.org/wikipedia/commons/0/01/Link_go_remake.png',
	},
	visual: {
		icon: '//upload.wikimedia.org/wikipedia/commons/thumb/3/3d/URL_decoder_VE_icon.svg/20px-URL_decoder_VE_icon.svg.png',
		modes: [ 'source' ],
	},
} );

Этот код добавляет кнопку гаджета на классическую панель и элемент меню в панель инструментов визуального редактора в режиме вики-текста.

О каждом свойстве:

Имя свойства Описание свойства
name Название гаджета латинскими буквами. Используйте lowerCamelCase.
position Позиция кнопки на панели инструментов (см. ниже).
title Название инструмента. Выводится как подпись к иконке в визуальном редакторе.
label Описание инструмента. Выводится как всплывающая подсказка к кнопке в классической панели.
icon Иконка инструмента. Рекомендуется использовать вместо этого параметра свойства classic.icon и visual.icon, так как иконки для разных панелей имеют разный размер — 22×22 для классической панели инструментов и 20×20 для панели инструментов визуального редактора — и иногда стиль.
filters Массив, содержащий строки-селекторы. Кнопка будет добавлена только в том случае, если на странице есть элементы, соответствующие одному из селекторов. Подробнее. Обычно используется для указания классов пространств имён, типа 'body.ns-talk'. В настоящее время работает только для классического редактора.
callback Функция, запускаемая при выборе инструмента (нажатии на кнопку).
addCallback Функция, запускаемая после добавления инструмента на панель.
classic Объект, свойства которого задают параметры конкретно для кнопки на классической панели (перезаписывают параметры, заданные для обеих панелей). Присвойте этому свойству как минимум пустой объект {}, иначе кнопка на классической панели не появится.
visual Объект, свойства которого задают параметры конкретно для элемента меню на панели инструментов визуального редактора (перезаписывают параметры, заданные для обеих панелей). Присвойте этому свойству как минимум пустой объект {}, иначе элемент меню на панели инструментов визуального редактора не появится.
visual.modes Массив, в котором перечислены режимы, в которых должен работать инструмент. Возможные значения элементов массива — 'visual' для самого визуального редактора, 'source' для редактора кода (нового режима вики-текста).
visual.addRightAway Булево значение, по умолчанию — false. Если задано true, элемент меню добавляется сразу вместо того, чтобы регистрировать новый плагин для визуального редактора через функцию mw.libs.ve.addPlugin() и становиться в очередь. (Используется для Викификатора, так как он уже регистрируется как плагин в MediaWiki:Common.js.)

position[править код]

Свойство position используется для указания позиции инструмента на панелях: 100, 150, 200, 300… Кнопки располагаются в порядке от инструмента с самым малым значением позиции к инструменту с самой большим. (Если некий гаджет/скрипт не успел загрузиться до момента, когда выполняется функция, добавляющая кнопки на панель, его кнопка добавляется в конец.) Позиции всех гаджетов/скриптов должны отличаться. При выборе значения для самого инструмента взвесьте, в каком месте должна располагаться ваша кнопка, и выберите соответствующее значение (желательно круглое). Если вас устраивает, чтобы кнопка располагалась в конце, просто добавьте 100 к максимальному значению из этой таблицы. Не забудьте добавить свой инструмент в эту таблицу, чтобы не было конфликта кнопки вашего инструмента с кнопками будущих инструментов.

Инструмент Позиция
Викификатор 100
Code Prettifier 150, 151, 152
Упрощение ссылок 200
Викиссыльщик 300
Ёфикатор 777

Быстродействие[править код]

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

Если эффект вашего скрипта виден сразу после загрузки страницы, рекомендуется «вешать» его выполнение либо на один из «хуков» (например, wikipage.content), либо на момент полной загрузки страницы посредством метода $ (но в таком случае он не будет выполняться заново в случае перезагрузки страницы при помощи AJAX).

Отслеживать промежутки времени между определёнными точками в скрипте удобно расставлением в них кода наподобие 

console.log((-window.lastTime + (window.lastTime = $.now())) + ' мс — Событие А');

В консоли JavaScript будут отражаться произошедшие события вместе с промежутками времени после предыдущего события.

Редактор кода[править код]

При правке скриптов вместо стандартного окна редактирования включается редактор кода (это расширение CodeEditor MediaWiki). Открыть панель настроек в редакторе кода можно с помощью сочетания клавиш Ctrl+,, но измененные значения не сохраняются при обновлении страницы.

Встроенный в редактор кода линтер по каким-то причинам ограничивается парой сотен строк, добавляя предупреждение «Too many errors» даже при отсутствии ошибок (подробнее). Чтобы это исправить, добавьте в свой common.js: 

mw.hook('codeEditor.configure').add(function (codeEditorSession) {
	setTimeout(function () {
		codeEditorSession.$worker.call("setOptions", [{
			esnext: true,
			moz: true,
			devel: true,
			browser: true,
			node: true,
			laxcomma: true,
			laxbreak: true,
			lastsemic: true,
			onevar: false,
			passfail: false,
			maxerr: 2000,
			expr: true,
			multistr: true,
			globalstrict: true
		}]);
	}, 2000);
});

— дело в значении maxerr. Если это не работает, можно добавлять в начало кода скриптов /* jshint maxerr: 2000 */. Дополнительно внутри функции в setTimeout() могут быть настроены шрифты и межстрочное расстояние: 

		$('.ace_editor').css('font-size', '13px');
		$('.ace_editor').css('line-height', '1.2em');

См. также[править код]

Источник — https://ru.wikipedia.org/w/index.php?title=Проект:Технические_работы/Разработчикам_скриптов&oldid=119435335