Создайте свой первый пакет Atom
Введение в атом
Atom — это текстовый редактор с открытым исходным кодом (в основном используемый разработчиками), который является мультиплатформенным и разработан компанией GitHub. Он основан на фреймворке Electron, разработанном Github, который позволяет разработчикам создавать собственные настольные приложения для любых операционных систем с помощью написания кода Javascript.
Основная интересная особенность Atom заключается в том, что он также имеет отличный инструмент управления пакетами, а пакеты также написаны на Javascript, поэтому любой может легко создать их. Эта статья призвана рассказать об этом.
Наконец, его сообщество также активно, поскольку у него уже есть много доступных пакетов: 5 285 на данный момент.
Вы можете просмотреть все пакеты, перейдя по следующему адресу: https:/ /atom.io/пакеты
Однако, если вы не можете найти пакет, который соответствует вашим потребностям, вы можете начать создавать свой собственный, и мы увидим, насколько это просто.
Создайте свой первый пакет
Для того, чтобы создать свой собственный пакет, не волнуйтесь, вы не начнете с нуля. Действительно, мы будем использовать команду Package Generator, которая предоставлена нам ядром Atom.
Для этого вам просто нужно перейти в раздел Пакеты -> Генератор пакетов -> Создать пакет Atom.
[note]Для создания пакета вы можете выбрать язык между Javascript и Coffeescript . В этой статье будет использоваться Javascript.[/note]
Когда команда будет выполнена, Atom откроет новое окно в вашем проекте пакета, которое по умолчанию называется my-package.
Структура пакета
Теперь мы подробно рассмотрим, что находится внутри нашего каталога проекта пакета:
├── CHANGELOG.md ├── LICENSE.md ├── README.md ├── keymaps │ └── my-package.json <- Key shortcuts registered by your package ├── lib │ ├── my-package-view.js │ └── my-package.js <- Entry point of your package ├── menus │ └── my-package.json <- Menus declaration of your package into Atom application ├── package.json <- Description and library dependencies of your package ├── spec <- Tests directory (Jasmine) of your package │ ├── my-package-spec.js │ └── my-package-view-spec.js └── styles <- Stylesheets used by your package └── my-package.less
Первым элементом, который нужно добавить в пакет, является файл package.json, который должен содержать всю информацию о вашем пакете, такую как его имя, версия, тип лицензии, ключевые слова, которые позволят вам найти ваш пакет в Реестр Atom, а также зависимости вашего пакета.
Также обратите внимание, что существует раздел под названием activationCommands, который позволяет определить выполняемую команду при загрузке вашего пакета.
Затем у нас есть файл keymaps/my-package.json, который позволяет вам очень легко определять ярлыки в вашем пакете. Вот пример по умолчанию:
{
"atom-workspace": {
"ctrl-alt-p": "my-package:toggle"
}
}
Далее мы перейдем к точке входа вашего пакета. Он находится в файле lib/my-package.js.
Этот файл экспортирует объект по умолчанию, который содержит свойство subscriptions, а также методы activate() и deactivate().
Во время активации пакета (внутри метода activate()) мы зарегистрируем объект типа CompositeDisposable внутри нашего свойства subscriptions, что позволит нам добавить и, возможно, позже удалить некоторые команды, предлагаемые нашим пакетом:
activate(state) {
this.subscriptions = new CompositeDisposable();
this.subscriptions.add(atom.commands.add('atom-workspace', {
'my-package:toggle': () => this.toggle()
}));
}
Теперь, когда наша команда зарегистрирована, мы можем протестировать ее, просто введя следующие слова в палитру команд Atom: Мой пакет: Toggle.
Эта команда выполнит код, содержащийся в toggle() класса и отобразит небольшое модальное окно в верхней части окна.
Вы можете добавить столько команд, сколько хотите, и я настоятельно рекомендую вам отделить свой код.
Добавьте настройки для вашего пакета
Компонент Конфигурация позволяет вашему пакету иметь некоторые настройки.
Чтобы добавить новую настройку, вам просто нужно определить свойство config в классе вашего пакета, которое является объектом, содержащим определение каждой настройки, следующим образом:
config: {
"gitlabUrl": {
"description": "If you rely on a private Gitlab server, please type your base URI here (default: https://gitlab.com).",
"type": "string",
"default": "https://gitlab.com"
}
}
Настройки Atom допускают несколько типов настроек (boolean , color , integer , string , …), поэтому он может соответствовать вашим потребности в установке значений вашими пользователями.
После добавления, если вы перезагрузите свой пакет, вы увидите, что настройки вашего пакета появляются в настройках Atom:
Чтобы получить значение (или значение по умолчанию), определенное пользователем для данного параметра в вашем коде, вам просто нужно использовать следующую строку:
let gitlabUrl = atom.config.get('gitlabUrl');
Обзор компонентов
Итак, теперь вы готовы разработать свой пакет. У нас будет краткий обзор некоторых интересных компонентов, которые Atom предлагает вам и позволяет использовать в вашем пакете.
TextEditor: взаимодействие с текстовым редактором
С помощью компонента TextEditor вы сможете вставлять текст в пользовательский текстовый редактор, сохранять текущий файл, перемещаться вперед и назад по истории, перемещать курсор в редактор, копировать/вставлять в буфер обмена, играть с отступом строки, прокручивать и делать многое другое…
Вот несколько примеров вставки текста в определенное место и автоматического сохранения файла:
editor.setCursorBufferPosition([row, column]);
editor.insertText('foo');
editor.save();
ViewRegistry & View: создание и отображение собственного окна
Эти компоненты позволяют создавать представления (модальные окна/окна) внутри Atom и отображать их.
У вас есть пример модального View в пакете по умолчанию:
export default class MyPackageView {
constructor(serializedState) {
// Create root element
this.element = document.createElement('div');
this.element.classList.add('my-package');
// Create message element
const message = document.createElement('div');
message.textContent = 'The MyPackage package is Alive! It\'s ALIVE!';
message.classList.add('message');
this.element.appendChild(message);
}
// ...
}
let myPackageView = new MyPackageView(state.myPackageViewState);
let modalPanel = atom.workspace.addModalPanel({
item: myPackageView.getElement(),
visible: false;
});
modalPanel.show();
NotificationManager & Notification: оповещайте пользователей с помощью уведомлений
Ваш пакет также может отображать различные уведомления от «успешно» до «фатальной ошибки»:
atom.notifications.addSuccess('My success notification');
atom.notifications.addInfo('My info notification');
atom.notifications.addWarning('My warning notification');
atom.notifications.addError('My error notification');
atom.notifications.addFatalError('My fatal error notification');
GitRepository
Это тоже очень интересно: действительно, вы можете получить доступ ко всем свойствам git текущего используемого репозитория git.
Таким образом, вы сможете получить доступ к текущему имени ветки, удаленному URL-адресу репозитория, а также увидеть, считается ли файл новым или измененным файлом. Давайте посмотрим на это в действии:
let repository = atom.project.getRepositoryForDirectory('/path/to/project');
console.log(repository.getOriginURL()); // -> [email protected]:eko/atom-pull-request.git
console.log(repository.getShortHead()); // -> master
console.log(repository.isStatusNew('/path/to/file')); // -> true
И многое другое…
Мы только что сделали обзор компонентов, с которыми я играл, но я предлагаю вам прочитать больше по следующей ссылке, если вы хотите пойти дальше: https://atom.io/docs/api/latest/AtomEnvironment.
Протестируйте свой пакет со спецификациями
Наш пакет уже разработан, но мы не должны забывать о тестах. Для этого Атом использует Жасмин.
В вашем пакете по умолчанию уже есть готовый тестовый файл:
import MyPackageView from '../lib/my-package-view';
describe('MyPackageView', () => {
it('has one valid test', () => {
expect('life').toBe('easy');
});
});
Тесты спецификаций Jasmine записываются следующим образом:
- describe(): набор тестов Jasmine начинается с функции «describe», которая принимает имя в качестве первого аргумента и функцию в качестве второго.
- it(): спецификация добавляется с помощью этой функции, «это» должно содержаться в спецификации,
- expect() : это утверждение, когда мы ожидаем, что что-то произойдет.
Теперь ваша очередь поиграть с Жасмин и проверить логику вашего пакета.
Чтобы запустить тесты спецификаций, вам просто нужно перейти в следующее меню: Вид -> Пакеты -> Выполнить спецификации пакетов .
Опубликуйте свой пакет
Наш пакет готов к развертыванию! Отправим.
Для этого мы будем использовать инструмент командной строки apm, который поставляется вместе с Atom при его установке.
После отправки кода в репозиторий Github просто перейдите в каталог пакета и введите следующую команду. :
$ apm publish --tag v0.0.1 minor Preparing and tagging a new version ✓ Pushing v0.0.1 tag ✓ ...
Эта команда будет отвечать за создание тега новой версии в репозитории и публикацию этой версии в реестре Atom.
Поздравляем, ваш пакет теперь опубликован и доступен по следующему URL-адресу: https://atom.io/packages/‹your-package›!
Непрерывная интеграция
Последний шаг — убедиться, что ваш пакет продолжит работать в будущем, когда вы или ваши участники добавите новые функции, а также когда Atom выпустит новую бета-версию. Для этого вы можете использовать Travis-CI на своем репозитории со следующей конфигурацией:
language: objective-c
notifications:
email:
on_success: never
on_failure: change
script: 'curl -s https://raw.githubusercontent.com/nikhilkalige/docblockr/develop/spec/atom-build-package.sh | sh'
env:
global:
- APM_TEST_PACKAGES=""
matrix:
- ATOM_CHANNEL=stable
- ATOM_CHANNEL=beta
Вывод
Лично я считаю, что это небольшая революция, позволяющая разработчикам создавать свой собственный редактор и привносить в него те функции, которые они хотят.
Более того, API Atom уже очень богат и очень прост в использовании, и это, безусловно, главная причина, по которой сообщество предлагает большое количество пакетов.
В заключение, как и для всех библиотек, бесполезно изобретать велосипед, создавая уже существующие пакеты. Идея состоит в том, чтобы добавить функции, если они еще не существуют, чтобы обогатить ваш пользовательский опыт.
Автор: Винсент Композье
Twitter: Винсент Композье
