Tulpar RPA

Документация 0.4 Студия

Пикер элементов

Чтобы нажать кнопку или ввести текст, робот должен найти элемент: в окне программы Windows — по селектору Windows (путь от окна к элементу), на веб-странице — по селектору страницы (CSS, текст, роль). Селектор Windows указывается пикером прямо на экране, селектор страницы пишется в поле.

Элемент окна Windows #

У действий „Windows“ (ui.click, ui.typeInto, ui.getText и других) в свойствах шага есть поле селектора и кнопки «Указать на экране», «Подсветить» и «Изменить».

Селектор шага „Клик по элементу“: путь от окна к кнопке и кнопки пикера
Селектор шага „Клик по элементу“: путь от окна к кнопке и кнопки пикера

Как указать элемент:

  1. Откройте программу и нужное окно.
  2. В свойствах шага нажмите «Указать на экране». Окно студии свернётся.
  3. Наведите курсор на элемент: вокруг него появится красная рамка, рядом — подсказка: тип элемента, имя и идентификатор (Button · Отправить · btnSend).
  4. Нажмите Ctrl — элемент выбран, студия вернётся с готовым селектором. Esc — отмена. Через 2 минуты без выбора пикер закрывается сам.

Пикер сам подбирает надёжный селектор: окно программы (имя процесса, тип и заголовок окна) и элемент (тип и идентификатор automationId, если он есть, иначе имя или класс). Если такой путь находит несколько элементов, пикер добавляет промежуточный элемент с именем (до трёх) или номер совпадения index.

«Подсветить» ищет элемент по селектору, обводит его красной рамкой на 2 секунды и сообщает, сколько элементов найдено. Так селектор проверяют без запуска процесса — например, после обновления программы.

Как устроен селектор #

В поле селектор показан коротко: Окно "Tulpar Test App" › Button btnSend. «Изменить» открывает его целиком:

«Селектор (JSON)»: окно и элемент, проверка при вводе
«Селектор (JSON)»: окно и элемент, проверка при вводе
{
  "kind": "uia",
  "path": [
    { "processName": "Tulpar.TestApp", "controlType": "Window", "name": "Tulpar Test App" },
    { "controlType": "Button", "automationId": "btnSend" }
  ]
}

Каждый элемент пути (сегмент) описывается атрибутами — нужен хотя бы один:

Атрибут Что значит
processName Имя процесса программы без .exe; только в первом сегменте
controlType Тип элемента: Window, Button, Edit, Text, ComboBox, CheckBox, List, ListItem, DataItem, Pane, Document, MenuItem, TabItem, Hyperlink …
automationId Идентификатор элемента, заданный разработчиком программы, — самый надёжный атрибут
name Видимое имя: текст кнопки, заголовок окна, подпись
className Класс окна Windows
index Номер среди совпадений, с 1 — если других различий нет

Как ищется элемент: первый сегмент — среди окон верхнего уровня, каждый следующий — среди всех вложенных элементов предыдущего. Сравнение без учёта регистра; в тексте атрибутов допускаются * (любые символы) и ? (один символ) и подстановки {{ }}. Элемент ищется до таймаута шага, каждые 200 мс; если поиск занял больше 2 секунд, в лог пишется совет уточнить селектор.

Советы:

  • Заголовок окна часто меняется (Документ1 - Word, Счёт № 15 — 1С) — оставьте постоянную часть: * - Word.
  • Имя, которое зависит от данных, подставьте из переменной: Счёт № {{ invoiceNumber }}*.
  • index используйте в последнюю очередь: порядок элементов может измениться.
  • Если робот и программа запущены с разными правами (программа — от администратора), элементы программы могут быть недоступны: запускайте их одинаково.

Элемент веб-страницы #

У действий „Браузер“ (browser.click, browser.typeInto, browser.getText и других) селектор — текстовое поле. Пикера страниц в версии 0.4 нет: селектор пишется вручную.

Селектор страницы у шага „Клик на странице“: CSS-селектор кнопки
Селектор страницы у шага „Клик на странице“: CSS-селектор кнопки
Вид Пример Когда удобен
CSS #submit, .btn-primary, input[name="phone"] У элемента есть id или постоянный класс
Текст text=Отправить Кнопки и ссылки с постоянной надписью
Роль role=button[name="Отправить"], role=textbox[name="Телефон"] Элементы с подписью — так их видят программы чтения экрана
XPath xpath=//table[@id="orders"]//tr[2]/td[1] Сложная структура, таблицы
Цепочка #orders >> text=П-0001, .row >> nth=0 Уточнить: внутри элемента, первый из найденных

Как найти селектор: откройте страницу в Edge, щёлкните по элементу правой кнопкой → „Проверить“ (инструменты разработчика, F12). У выделенного элемента посмотрите id, name или текст; правой кнопкой по нему в коде страницы → „Копировать“ → „Копировать селектор“ даёт готовый CSS-селектор. Проверить селектор можно там же: в консоли document.querySelectorAll('#submit') должен найти один элемент.

Если селектор находит несколько элементов, действие завершается ошибкой — уточните селектор или добавьте >> nth=0. Значения переменных подставляются через {{ }}: text={{ item.reference }}.