Что такое помощник ввода
Помощник ввода — это небольшое окно со списком, которое плагин показывает под курсором, пока пользователь набирает текст. Так работают автодополнение и подсказки: пользователь начинает слово, видит подходящие варианты и выбирает нужный клавишами или мышью.
Примеры задач:
- подсказать термины, названия продуктов или реквизиты компании;
- предложить фамилию сотрудника из справочника;
- исправить частую опечатку сразу при вводе.
Помощник ввода работает в Документах, Таблицах (при вводе в ячейку) и Презентациях (при вводе в надписи).
Как это устроено
Плагин с помощником ввода — фоновый ("isVisual": false): у него нет своей панели. Страница плагина сама становится окном со списком: редактор показывает ее рядом с курсором и прячет, когда список не нужен.
Работа идет по четырем шагам:
1. При запуске плагин создает помощник ввода и превращает свою страницу в список.
2. Пока пользователь набирает слово, редактор присылает событие onInputHelperInput с набранным текстом. Плагин заполняет список и показывает его или прячет, если подсказать нечего.
3. Когда слово закончено, редактор присылает onInputHelperClear, и плагин прячет список.
4. Когда пользователь выбирает вариант, вызывается inputHelper_onSelectItem. Плагин стирает набранное начало слова и вводит выбранный вариант методом InputText ↗.
Методы и события
| Что | Зачем |
|---|---|
| createInputHelper ↗ | Создает помощник ввода плагина. Вызывается один раз, в init. |
| getInputHelper ↗ | Возвращает созданный помощник ввода. |
createWindow() | Заменяет содержимое страницы плагина списком с прокруткой и подключает управление с клавиатуры. |
setItems(items) | Заполняет список. Каждый элемент — объект { id, text }, первый элемент сразу выделен. |
show(ширина, высота, фокус) | Показывает список под курсором, а если снизу нет места — над ним. Размеры в пикселях. С третьим параметром false фокус остается в документе, и пользователь продолжает печатать. |
unShow() | Прячет список. |
getItemsHeight(n) | Высота списка из n строк в пикселях: удобно передать в show. |
Событие onInputHelperInput | Пользователь набирает текст. В data.text — набираемое слово. |
Событие onInputHelperClear | Слово закончено: пользователь ввел Пробел, точку, запятую или нажал Enter. |
inputHelper_onSelectItem(item) | Пользователь выбрал вариант клавишей Enter или щелчком. В item — выбранный элемент { id, text }. |
Оба события нужно перечислить в массиве events файла config.json. Методы ShowInputHelper и UnShowInputHelper вызывать не нужно: их вызывают show и unShow.
Пока список на экране, редактор передает в него клавиши управления: стрелки вверх и вниз, Tab, Home, End, Page Up, Page Down, Enter и Esc. Все остальные клавиши попадают в документ. Выбор строки, скрытие по Esc и вызов inputHelper_onSelectItem по Enter уже реализованы в createWindow. Подробнее об объекте — в статье Объект InputHelper ↗.
Пример: подсказки терминов
Плагин подсказывает термины из словаря: после двух набранных букв показывает термины, которые начинаются с этих букв, а выбранный термин вставляет вместо набранного начала слова. Плагин состоит из трех файлов и папки с иконками. GUID в config.json у каждого плагина свой: для своего плагина сгенерируйте новый.
config.json
{
"name": "Term hints",
"nameLocale": { "ru": "Подсказки терминов" },
"guid": "asc.{A3F1C2D4-5B6E-4F70-8A9B-1C2D3E4F5A61}",
"version": "1.0.0",
"variations": [
{
"description": "Suggests terms while typing",
"descriptionLocale": { "ru": "Подсказывает термины при вводе текста" },
"url": "index.html",
"icons": [ "resources/icon.png", "resources/icon@2x.png" ],
"isViewer": false,
"EditorsSupport": [ "word", "cell", "slide" ],
"isVisual": false,
"isModal": false,
"isInsideMode": false,
"initDataType": "none",
"initData": "",
"buttons": [],
"events": [ "onInputHelperInput", "onInputHelperClear" ]
}
]
}
index.html
Разметка не нужна: список создает createWindow.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Term hints</title>
<script type="text/javascript" src="../v1/plugins.js"></script>
<script type="text/javascript" src="../v1/plugins-ui.js"></script>
<link rel="stylesheet" href="../v1/plugins.css">
<script type="text/javascript" src="code.js"></script>
</head>
<body></body>
</html>
code.js
// Пример «Подсказки при вводе текста». Автор: Александр Поляков
(function (window) {
// Словарь терминов: замените своим списком
var TERMS = [
"договор", "дополнительное соглашение", "доверенность",
"спецификация", "счет-фактура", "товарная накладная"
];
var MIN_LENGTH = 2; // подсказки появляются после двух букв
var currentText = ""; // слово, которое пользователь сейчас набирает
// Термины, которые начинаются с набранного текста
function findTerms(text) {
var start = text.toLowerCase();
return TERMS.filter(function (term) {
return term.indexOf(start) === 0 && term !== start;
});
}
window.Asc.plugin.init = function () {
// 1. Создаем помощник ввода и его окно со списком
this.createInputHelper();
this.getInputHelper().createWindow();
};
// 2. Пользователь набирает текст: в data.text текущее слово
window.Asc.plugin.event_onInputHelperInput = function (data) {
currentText = data.text;
var helper = this.getInputHelper();
var terms = currentText.length >= MIN_LENGTH ? findTerms(currentText) : [];
if (terms.length === 0) {
helper.unShow();
return;
}
helper.setItems(terms.map(function (term, i) {
return { id: "term" + i, text: term };
}));
// Ширина и высота окна в пикселях, false — фокус остается в документе
helper.show(220, helper.getItemsHeight(Math.min(terms.length, 6)), false);
};
// 3. Слово закончилось (пробел, точка, запятая, Enter): прячем список
window.Asc.plugin.event_onInputHelperClear = function () {
currentText = "";
this.getInputHelper().unShow();
};
// 4. Пользователь выбрал термин щелчком или клавишей Enter
window.Asc.plugin.inputHelper_onSelectItem = function (item) {
var helper = this.getInputHelper();
helper.unShow();
if (!item) {
return;
}
// Стираем набранное начало слова и вводим термин целиком
this.executeMethod("InputText", [item.text, currentText]);
currentText = "";
};
window.Asc.plugin.button = function () {
this.executeCommand("close", "");
};
})(window);
Второй параметр InputText — текст, который нужно стереть перед вводом: редактор нажимает Backspace столько раз, сколько в нем символов. Поэтому плагин запоминает набранное слово в currentText.
Как установить и проверить
1. Создайте папку плагина, положите в нее три файла и папку resources с иконками и установите плагин по инструкции Установка и удаление плагина ↗.
2. Откройте документ и на вкладке Плагины нажмите Подсказки терминов. Панель не откроется, а кнопка плагина останется нажатой — плагин работает.
3. Наберите с клавиатуры «до». Под курсором появится список терминов.
4. Выберите термин стрелками и нажмите Enter. Набранное «до» заменится термином целиком. Чтобы закрыть список без выбора, нажмите Esc.
В Таблицах набирайте текст в ячейку, в Презентациях — в надпись на слайде. Чтобы выключить плагин, снова нажмите его кнопку. После изменения code.js плагин нужно выключить и включить заново. Если список не появляется, проверьте массив events и откройте консоль по инструкции Отладка плагина ↗.
Результат
Документы: после «до» плагин предлагает три термина, первый выделен:

После стрелки вниз и Enter «до» заменено на «дополнительное соглашение»:

Таблицы: список появляется под ячейкой, в которую идет ввод:

Презентации: после «сч» в подзаголовке слайда плагин предлагает один термин:

Особенности
- Только ввод с клавиатуры. Событие
onInputHelperInputприходит, когда текст набирают на клавиатуре. Текст, вставленный из буфера обмена, подсказок не вызывает; - Выбор мышью. После щелчка по строке списка термин вставляется, но фокус остается в окне плагина: пока пользователь не щелкнет в документе, набранные символы туда не попадают. Выбор клавишей Enter этого недостатка не имеет;
- Таблицы. После выбора термина ячейка остается в режиме редактирования. Второе нажатие Enter завершает ввод;
- Текст элементов — это HTML.
setItemsвставляетtextв список как разметку: на проверке<b>отобразился жирным,<i>— курсивом, а<— знаком<. При этомitem.textвinputHelper_onSelectItemприходит без изменений, иInputTextввел в документ теги и<буквально. Если варианты могут содержать<или&(например, приходят с сервера), вtextпередавайте экранированную строку, а для вставки берите исходный текст поitem.id.
Как доработать
- Словарь с сервера. Загрузите список терминов запросом
fetchвinit, чтобы все сотрудники пользовались одним словарем; - Автозамена опечаток. Храните пары «опечатка ⟶ исправление» и показывайте исправление одной строкой, когда набранное слово совпадает с опечаткой.













