Модуль «Сценарии и фрагменты» KateМодуль «Сценарии и фрагменты» Kate позволяет пользователю добавлять собственные элементы автоматизации и управлять ими. Они могут быть разными: от статических фрагментов обычного текста для многократного использования до очень сложных шаблонов с настраиваемыми автоматизированными полями с поддержкой сценариев, а также полностью настраиваемых сценариев JavaScript для изменения содержимого документа.
В большинстве случаев с этими типами содержимого можно работать одним и тем же образом. Поэтому, чтобы воспринимать информацию было легче, далее в тексте не говорится отдельно о статических фрагментах, содержащих сценарии фрагментах и сценариях. Вместо этого просто используется термин «фрагмент».
Модуль также поддерживает назначение комбинаций клавиш и вставку фрагментов с помощью автодополнения кода. Более того, можно загружать подборки фрагментов (так называемые комплекты) из Интернета.
На панели отображается список комплектов фрагментов, а также опции создания собственных комплектов, получения их из Интернета или загрузки из локального файла. Для каждого комплекта предусмотрен флажок, который возможно использовать для его активации или деактивации. Также имеются кнопки для редактирования и удаления существующих комплектов.
Комплекты фрагментов возможно загрузить из Интернета. Достаточно нажать кнопку , и откроется окно со списком комплектов фрагментов, доступных для загрузки. После загрузки комплект следует активировать.
Чтобы создать новый комплект фрагментов, нажмите кнопку . Появится диалоговое окно, в котором следует указать название файла фрагментов, лицензию и автора. Указав необходимые данные, нажмите кнопку .
В редакторе комплектов фрагментов доступны следующие параметры:
- Название
Появляется в списке фрагментов на панели, а также по нему выполняется поиск при использовании функции автодополнения кода.
- Пространство имён
Префикс при использовании функции автодополнения кода.
- Лицензия
Позволяет выбрать лицензию для комплекта фрагментов.
- Авторы
Позволяет ввести имена авторов файла фрагментов.
- Типы файлов
Позволяет выбрать типы файлов, к которым должен применяться комплект фрагментов. По умолчанию установлено значение «», поэтому комплект будет применяться ко всем файлам. Установленное значение возможно изменить, указав, например,
C++, или выбрав готовый вариант из списка. Возможно установить более одного типа, если удерживать нажатой клавишу Shift при их добавлении.
- Название
Название в списке фрагментов и в списке автодополнения (обязательно).
- Тип
Фрагменты могут быть текстовыми шаблонами или сценариями. Оба типа позволяют использовать функции JavaScript (подробные сведения приводятся далее) и, соответственно, получить схожие результаты. Вместе с тем, текстовые шаблоны лучше подходят для случаев, когда основной задачей является вставка текста, а сценарии зачастую значительно упрощают работу, когда текст нужно изменить.
Примечание
Чтобы эта функциональная возможность была доступна, программа Kate должна быть собрана с KTextEditor версии 6.15.0 или выше. При использовании более ранних версий будут доступны только фрагменты типа «текстовый шаблон».
- Комбинация клавиш
Нажатие этой комбинации позволяет вставить фрагмент в текущий документ (или выполнить его там).
- Фрагмент (тип
Текстовый шаблон) Текст, который будет вставлен в документ.
Фрагмент может содержать поля, которые возможно редактировать. Циклический переход между ними выполняется с помощью клавиши Tab. В тексте шаблона возможно использовать следующие выражения для создания полей:
${создаёт простое редактируемое поле. При редактировании все последующие вхождения того жеимя_поля}имени_полябудут копиями содержимого первого поля.Подсказка
Имена полей могут содержать любые символы, кроме закрывающей фигурной скобки (
}).Чтобы вставить
${text}без изменения в виде фрагмента, экранируйте символ$обратной косой чертой:\${text}. В этом случае текст не превратится в поле. Чтобы вставить перед полем символы обратной косой черты без изменения, экранируйте каждый из них отдельной обратной косой чертой:\\${field},\\\\${field}и так далее.${func(создаёт поле, которое будет содержать актуальный результат выполнения функции JavaScript при каждом редактировании. Более подробные сведения доступны на вкладке Библиотека сценариев.другое_поле1,другое_поле2, ...)}${устанавливает значение по умолчанию для поля.имя_поля=значение по умолчанию}Значение по умолчанию— это выражение JavaScript. Используйте кавычки (${) для указания фиксированной строки в качестве значения по умолчанию.имя_поля="текст"}Подсказка
При использовании значений по умолчанию (
${) следует помнить о том, что значение по умолчанию вычисляется сразу после вставки фрагмента в документ и не обновляется при изменении полей в дальнейшем.имя_поля=значение по умолчанию}В значениях по умолчанию можно ссылаться на другие поля, если таковые определены до вычисляемого значения по умолчанию. Но это позволит получить доступ только к стандартным значениям этих полей.
Если не задано пользовательское значение по умолчанию, значением по умолчанию будет имя поля.
${cursor}отмечает конечную позицию курсора после заполнения всех полей. Вставка текста в этой позиции приведёт к завершению редактирования. Кроме того, после нажатия клавиши Esc для завершения редактирования курсор перейдёт в эту позицию.- Фрагмент (тип
Сценарий) Код JavaScript для обработки этого фрагмента
Если в этом коде есть инструкция
return, возвращённая строка будет вставлена в текущей позиции курсора. Также можно воспользоваться программным интерфейсом сценариев Kate, чтобы внести изменения в документ напрямую.Кроме того, в коде можно использовать функции, определённые на вкладке Библиотека сценариев; они являются общими для всех фрагментов в комплекте.
- Библиотека сценариев
Вспомогательные функции JavaScript для использования во фрагментах. Они являются общими для всех фрагментов в комплекте.
Возможно использовать программный интерфейс для работы со сценариями Kate, чтобы получить обозначенный фрагмент текста, весь текст, имя файла и другие данные с помощью соответствующих методов объектов
documentиview. Дополнительные сведения доступны в документации программного интерфейса для работы со сценариями.Когда функция вызывается в поле фрагмента типа
Текстовый шаблон, возвращённое ей значение вставляется в текст.Примечание
Использование функций во фрагментах типа
Текстовый шаблон:Функции могут получать доступ к актуальному содержимому всех полей с помощью объекта
fields: используйтеfields.my_fieldилиfields["my_field"]. Когда функция используется в качестве значения по умолчанию для поля, доступны только ранее определённые в тексте поля.Поля можно передавать функциям как аргументы. Можно использовать непосредственно имя поля, если оно представляет собой корректный идентификатор JavaScript и нет переменных с таким же именем. Если это не так, следует использовать объект
fields:${func(field)},${func(fields.document)},${func(fields["my field"])}Поля функций (например,
${func()}) каждый раз вычисляются заново при изменении содержимого поля. Однако это не относится к вызовам функций в значениях по умолчанию; они вычисляются только один раз, при вставке фрагмента в документ.В случае более сложных сценариев важно понимать, что сначала в документ вставляется необработанный фрагмент, а потом — вычисляемые функции. Например, если функция извлекает текст в строке, куда вставляется фрагмент, этот текст также будет содержать
${functionCall()}. Там, где это приводит к сложностям, рекомендуется использовать фрагмент типаСценарий.Чтобы обернуть текущий выбранный текст в теги:
<strong>${view.selectedText()}</strong>Помните, что в поле вставляется только возвращаемое значение функции.
- Description
Необязательное описание функционала фрагмента. Оно будет показано во всплывающих подсказках. Описание может содержать базовое форматирование HTML.
- Пример использования
В следующем примере вызывается сценарий, оборачивающий выбранный текст (если нечего не выбрано — текст по умолчанию) в теги (тип фрагмента
Сценарий):let range = view.hasSelection() ? view.selection() : new Range(view.cursorPosition(), view.cursorPosition()); let innertext = range.isEmpty() ? "Bold" : document.text(range); document.removeText(range); document.insertText(range.start, "<strong>" + innertext + "</strong>");
Получить доступ к фрагментам возможно несколькими способами:
Щёлкнуть по фрагменту на боковой панели.
Воспользоваться комбинацией клавиш (если она была назначена).
Использовать во время редактирования комбинацию клавиш Ctrl+Пробел для просмотра всех фрагментов в удобном окне и выбора нужного. Эта комбинация клавиш обеспечивает функциональность, аналогичную дополнению кода.
Если во фрагменте содержатся переменные (кроме ${cursor}), курсор будет автоматически перемещён к первому вхождению переменной, после чего программа перейдёт в состояние ожидания ввода текста. Переход к следующей переменной выполняется с помощью клавиши Tab.