Важно

Перевод - это работа сообщества : ссылка:Вы можете присоединиться. Эта страница в настоящее время переводится |прогресс перевода|.

9.1. Выражения

Основываясь на данных слоя и предварительно построенных или определенных пользователем функциях, Expressions предлагают мощный способ манипулирования значениями атрибутов, геометрией и переменными для динамического изменения стиля геометрии, содержания или положения метки, значения для диаграммы, высоты элемента макета, выбора некоторых функций, создания виртуального поля, …

Примечание

Список функций и переменных по умолчанию для написания выражений можно найти по адресу List of functions, с подробной информацией и примерами.

9.1.1. Построитель строк выражений

Основной диалог для построения выражений, Построитель строк выражений, доступен из многих частей QGIS и, в частности, может быть доступен, когда:

Диалоговое окно «Построитель выражений» предоставляет доступ к функциям:

9.1.1.1. Интерфейс

Вкладка Выражение предоставляет основной интерфейс для написания выражений с использованием функций, полей слоя и значений. Она содержит следующие виджеты:

../../../_images/function_list.png

Рис. 9.1 Вкладка Выражение

  • Область редактора выражений для ввода или вставки выражений. Для ускорения ввода выражений доступно автозавершение:

    • Соответствие переменных, имен функций и названий полей вводимому тексту показано ниже: используйте стрелки Up и Down для просмотра элементов и нажмите Tab для вставки в выражение или просто щелкните на нужном элементе.

    • Параметры функций отображаются при их заполнении.

    QGIS также проверяет правильность выражения и выделяет все ошибки:

    • Подчеркивание: для неизвестных функций, неправильных или недопустимых аргументов;

    • Маркер: для каждой другой ошибки (например, пропущенная скобка, неожиданный символ) в одном месте.

    Совет

    Документируйте свое выражение комментариями

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

    /*
Labels each region with its highest (in altitude) airport(s)
and altitude, eg 'AMBLER : 264m' for the 'Northwest Artic' region
*/
with_variable(
  'airport_alti', -- stores the highest altitude of the region
  aggregate(
    'airports',
    'max',
    "ELEV", -- the field containing the altitude
    -- and limit the airports to the region they are within
    filter := within( @geometry, geometry( @parent ) )
  ),
    aggregate( -- finds airports at the same altitude in the region
      'airports',
      'concatenate',
      "NAME",
      filter := within( @geometry, geometry( @parent ) )
        and "ELEV" = @airport_alti
    )
    || ' : ' || @airport_alti || 'm'
    -- using || allows regions without airports to be skipped
)

  • Над редактором выражений находится набор инструментов, которые помогут вам:

    • fileNewОчистить редактор выражений

    • Создание и управление выражениями пользователя

  • В редакторе выражений вы найдете:

    • Набор основных операторов, которые помогут вам построить выражение

    • Указание на ожидаемый формат вывода данных при определении свойств признаков

    • Живой Вывод предварительного просмотра выражения (до 60 символов), по умолчанию оценивается на первой функции слоя. Для просмотра текста, превышающего 60 символов, можно навести курсор на текст, чтобы отобразить всплывающую подсказку, содержащую весь предварительный просмотр. Чтобы скопировать текст предварительного просмотра в буфер обмена, щелкните правой кнопкой мыши на тексте предварительного просмотра и выберите editCopy Копировать значение выражения.

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

      В случае ошибки он укажет на нее, и вы сможете перейти к деталям по предоставленной гиперссылке.

  • Селектор функций отображает список функций, переменных, полей…, объединенных в группы. Для фильтрации списка и быстрого поиска определенной функции или поля имеется поле поиска. Двойной щелчок по элементу добавляет его в редактор выражений.

  • На панели справки отображается справка для каждого выбранного элемента в селекторе функций.

    Совет

    Нажмите Ctrl+Click при наведении на имя функции в выражении, чтобы автоматически отобразить справку по ней в диалоге.

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

    • Поиск определенного значения поля

    • Отображение списка значений Все уникальные или 10 образцов. Также доступно при нажатии правой кнопки мыши.

      Если поле сопоставлено с другим слоем или набором значений, т.е. если виджет Поле виджета имеет тип RelationReference, ValueRelation или ValueMap, то можно перечислить все значения сопоставленного поля (из сопоставленного слоя, таблицы или списка). Более того, вы можете отфильтровать этот список, чтобы checkbox Отображать только используемые значения в текущем поле.

    Двойной щелчок по значению поля в виджете добавляет его в редактор выражений.

    Совет

    Правая панель, показывающая справку по функциям или значения полей, может быть свернута (невидима) в диалоге. Чтобы вернуть ее, нажмите кнопку Показать значения или Показать справку.

9.1.1.2. Запись выражения

Выражения QGIS используются для выбора характеристик или установки значений. Написание выражения в QGIS подчиняется некоторым правилам:

  1. Диалог определяет контекст: если вы знакомы с SQL, вам наверняка знакомы запросы типа выбрать черты из слоя, где условие или обновить слой, установить поле = новое_значение, где условие. Выражение QGIS также нуждается во всех этих сведениях, но часть из них предоставляет инструмент, который вы используете для открытия диалога построения выражений. Например, задаем слой (``здания““) с полем (``высота““):

    • Нажатие инструмента expressionSelectВыбор по выражению означает, что вы хотите «выбрать признаки из зданий». Условие** - это единственная информация, которую нужно указать в текстовом виджете выражения, например, введите высота'' > 20, чтобы выбрать здания, высота которых превышает 20.

    • При таком выборе, нажав кнопку calculateField Калькулятор полей и выбрав «height» в качестве Обновить существующее поле, вы уже обеспечите команду « обновить здания задать высоту = ???, где высота > 20». Единственное, что вам нужно указать в этом случае, это новое значение, например, просто введите 50 в текстовое поле редактора выражений, чтобы установить высоту ранее выбранных зданий.

  2. Обратите внимание на кавычки: одинарные кавычки возвращают литерал, поэтому текст, помещенный между одинарными кавычками ('145'), интерпретируется как строка. Двойные кавычки дадут вам значение этого текста, поэтому используйте их для полей ("myfield"). Поля также можно использовать без кавычек (myfield). Для чисел кавычки не нужны (3.16).

    Примечание

    Функции обычно принимают в качестве аргумента строку с именем поля. Do:

    attribute( @atlas_feature, 'height' ) -- returns the value stored in the "height" attribute of the current atlas feature

    И не:

    attribute( @atlas_feature, "height" ) -- fetches the value of the attribute named "height" (e.g. 100), and use that value as a field
                                      -- from which to return the atlas feature value. Probably wrong as a field named "100" may not exist.

Совет

Используйте именованные параметры, чтобы облегчить чтение выражений

Некоторые функции требуют задания множества параметров. Механизм выражений поддерживает использование именованных параметров. Это означает, что вместо того, чтобы писать криптографическое выражение clamp( 1, 2, 9), можно использовать clamp( мин:=1, значение:=2, макс:=9). Это также позволяет менять аргументы местами, например, clamp( значение:=2, максимум:=9, минимум:=1). Использование именованных параметров помогает уточнить, к чему относятся аргументы функции выражения, что очень полезно при последующей интерпретации выражения!

9.1.1.3. Некоторые случаи использования выражений

  • В Калькуляторе полей рассчитайте поле «Плотность населения», используя существующие поля «Всего_населения» и «Площадь_км2»:

    "total_pop" / "area_km2"

  • Пометьте или классифицируйте объекты по их площади:

    CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END

  • Обновите поле «density_level» с категориями в соответствии со значениями «pop_density»:

    CASE WHEN "pop_density" < 50 THEN 'Low population density'
     WHEN "pop_density" >= 50 and "pop_density" < 150 THEN 'Medium population density'
     WHEN "pop_density" >= 150 THEN 'High population density'
END

  • Примените категоризацию ко всем характеристикам в зависимости от того, меньше или больше средняя цена дома за квадратный метр:

    "price_m2" > 10000

  • Используя инструмент «Выбрать по выражению…», выберите все объекты, представляющие районы с «высокой плотностью населения», средняя цена домов в которых превышает 10000 евро за квадратный метр:

    "density_level" = 'High population density' and "price_m2" > 10000

    Предыдущее выражение также можно использовать для определения того, какие объекты следует помечать или показывать на карте.

  • Выберите объекты, которые пересекаются с природной зоной, из слоя «Земли»:

    overlay_intersects( layer:='lands', filter:="zone_type"='Natural' )

  • Подсчитайте для каждого объекта количество зданий, которые он содержит:

    array_length( overlay_contains( layer:='buildings', expression:=@id ) )

  • Создайте другой символ (тип) для слоя, используя генератор геометрии:

    point_on_surface( @geometry )

  • Получив точечный объект, создайте замкнутую линию (с помощью make_line) вокруг его геометрии:

    make_line(
  -- using an array of points placed around the original
  array_foreach(
    -- list of angles for placing the projected points (every 90°)
    array:=generate_series( 0, 360, 90 ),
    -- translate the point 20 units in the given direction (angle)
    expression:=project( @geometry, distance:=20, azimuth:=radians( @element ) )
  )
)

  • На этикетке макета печати отобразите названия объектов «Аэропорты», которые находятся в элементе макета «Карта 1»:

    with_variable( 'extent',
               map_get( item_variables( 'Map 1' ), 'map_extent' ),
               aggregate( 'airports', 'concatenate', "NAME",
                          intersects( @geometry, @extent ), ' ,'
                        )
             )

9.1.1.4. Экономия выражений

С помощью кнопки fileSave Добавить текущее выражение в пользовательские выражения над рамкой редактора выражений вы можете сохранить важные выражения, к которым хотите иметь быстрый доступ. Они доступны из группы Выражения пользователя на средней панели. Они сохраняются под профилем пользователя (:file:<userprofile>`/QGIS/QGIS3.ini` файл) и доступны во всех диалогах выражений во всех проектах текущего профиля пользователя.

Набор инструментов, доступных над рамкой редактора выражений, помогает управлять пользовательскими выражениями:

  • fileSaveДобавить текущее выражение в пользовательские выражения: сохранить выражение в профиле пользователя. Для облегчения идентификации можно добавить метку и текст справки.

  • symbologyEdit Редактировать выбранное выражение из пользовательских выражений, а также их справку и метку

  • deleteSelected Удалить выбранное выражение из пользовательских выражений

  • sharingImport Импорт выражений пользователя из файла .json в папку активного профиля пользователя

  • sharingExport Экспорт пользовательских выражений в файл .json; все пользовательские выражения в профиле пользователя QGIS3.ini файл являются общими

9.1.2. Редактор функций

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

../../../_images/function_editor.png

Рис. 9.2 Вкладка Редактор функций

Чтобы создать новую функцию:

  1. Нажмите кнопку symbologyAdd Новый файл.

  2. Выберите, где хранить новую функцию. Вы можете сохранить ее либо в Файл функции, либо в Функции проекта.

    • Если вы выбрали Файл функции, вам нужно ввести имя файла Python .py, который основан на файле шаблона QGIS и хранится в папке /python/expressions в активном каталоге профиля пользователя.

    • Если выбрать Проектные функции, новая функция будет сохранена в файле проекта.

    На левой панели вкладки Редактор функций добавляется новый элемент.

  3. На правой панели отображается содержимое файла: шаблон скрипта python. Обновите код и справку в соответствии с вашими потребностями.

  4. Нажмите кнопку start Сохранить и загрузить функции. Написанная вами функция будет добавлена в дерево функций на вкладке Выражение, по умолчанию в группу Кастомные.

  5. Наслаждайтесь своей новой функцией.

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

Пользовательские функции Python, сохраненные в файлах Function, хранятся в каталоге профиля пользователя, что означает, что при каждом запуске QGIS будет автоматически загружать все функции, определенные в текущем профиле пользователя. Имейте в виду, что для совместного использования функций Python, хранящихся в файлах «Функции», вам необходимо предоставить общий доступ к файлу .py в папке /python/expressions.

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

Чтобы удалить пользовательскую функцию:

  1. Включите вкладку Редактор функций

  2. Выберите функцию в списке

  3. Нажмите кнопку symbologyRemove Удалить выбранную функцию. Функция удаляется из списка и, в зависимости от хранилища, соответствующий файл .py удаляется из папки профиля пользователя, или функции Python удаляются из файла проекта.

Когда файл проекта с функциями Проект закрывается, соответствующие функции Проекта выгружаются и больше не доступны в сеансе QGIS.

Пример

Вот небольшой пример того, как создать собственную функцию my_sum, которая будет оперировать двумя значениями.

from qgis.core import *
from qgis.gui import *

@qgsfunction(args='auto', group='Custom')
def my_sum(value1, value2, feature, parent):
    """
    Calculates the sum of the two parameters value1 and value2.
    <h2>Example usage:</h2>
    <ul>
      <li>my_sum(5, 8) -> 13</li>
      <li>my_sum("field1", "field2") -> 42</li>
    </ul>
    """
    return value1 + value2

Декоратор @qgsfunction принимает следующие аргументы:

  • args: количество аргументов. При использовании аргумента args='auto' количество необходимых аргументов функции будет вычислено по количеству аргументов, с которыми функция была определена в Python (минус 2 - функция и родитель). При args = -1 принимается любое количество аргументов.

  • Аргумент группа указывает группу, в которой функция должна быть перечислена в диалоге Выражение.

  • usesgeometry=True, если выражение требует доступа к геометрии объекта. По умолчанию False.

  • handlesnull=True, если выражение имеет пользовательскую обработку для значений NULL. Если False (по умолчанию), то результат всегда будет NULL, как только любой параметр станет NULL.

  • referenced_columns=[list]: Массив имен атрибутов, которые требуются для функции. По умолчанию принимает значение [QgsFeatureRequest.ALL_ATTRIBUTES].

Сама функция допускает следующие аргументы:

  • любое количество и тип параметров, которые вы хотите передать в функцию, устанавливаемые перед следующими аргументами.

  • функция: текущая функция

  • parent: объект QgsExpression

  • контекст: Если в последней позиции найден аргумент контекст, то эта переменная будет содержать объект QgsExpressionContext, который предоставляет доступ к различной дополнительной информации, например, к переменным выражения. Например, context.variable( 'layer_id' )

Предыдущий пример функции можно использовать в выражениях:

../../../_images/customFunction.png

Рис. 9.3 Пользовательская функция добавлена на вкладку Выражение

Дополнительную информацию о создании кода на Python можно найти в Поваренная книга разработчика PyQGIS.