3.12. RenderObject: первое погружение

Автор: Дмитрий Золотов

В этой статье мы обсудим внутреннюю организацию RenderObject — механизма, который добавляет визуальное представление и оживляет наше приложение, создавая из пикселей стилизацию в Material Design или Human Interface Guidelines.

Но прежде чем уходить в детали, давайте в общих чертах вспомним, как Flutter собирает интерфейс.

Коротко о том, как Flutter собирает интерфейс

Итак, представим, что мы можем создать уникальный автомобиль, комбинируя его из частей и задавая характеристики для каждой части — например, цвет или мощность отдельных элементов. Детали создаются по нашему описанию на фабрике и поступают на сборочный конвейер, где объединяются в более крупные части и в конечном счёте — в готовый автомобиль.

Вы уже знакомы со «сборочным конвейером» — способами описания конфигурации и композиции деталей (дерево виджетов), определением их структуры и взаимоотношений в итоговом продукте (дерево элементов, доступное через BuildContext). А с «фабрикой» — пока нет.

Как вы наверняка догадались, RenderObject и есть та самая «фабрика». Этот механизм реализует физику и визуальное представление элементов, их поведение при взаимодействии с окружающей средой, определение ограничений их размеров (чтобы они поместились внутрь более крупных объектов) и многое другое.

Разберём его подробнее.

Что делает RenderObject

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

Коротко вспомним уже знакомую вам иллюстрацию, чтобы быть в контексте:

flutter_3_12.1

В зоне ответственности RenderObject находятся такие действия, как:

  • Создание визуального представления на предоставленном контексте для рисования (фаза paint). Например, через графические библиотеки Skia/Impeller на экране мобильного телефона. RenderObject использует множество оптимизаций и может переиспользовать ранее полученное изображение, сохранённое в растровом кэше.
  • Размещение дочерних RenderObject (фаза layout). Например, в случае расположения нескольких объектов под управлением родительского в виджетах Flex/Stack и других.
  • Определение собственного размера (метод performLayout). При измерении используются ограничения от родителя, доступные в аргументе constraints, плюс могут также учитываться размеры дочерних объектов. После измерения размер может быть извлечён из свойства size.
  • Реакция на события. Например, прикосновения к экрану или перемещения курсора мыши. Исходное событие обрабатывается в hitTest и создаёт список событий, который обрабатывается в handleEvents.
  • Передача информации о содержании и возможных операциях над RenderObject (describeSemanticsConfiguration) для использования с альтернативными устройствами ввода-вывода.
  • Управление деревом RenderObject — связь с родительским объектом ссылкой через parent, передача информации в родительский объект через parentData, добавление и удаление новых дочерних объектов.
  • Регистрация диагностической информации о свойствах объекта для отображения в DevTools через переопределение метода debugFillProperties.
  • Предоставление доступа к растровому изображению дерева виджетов. Например, это можно использовать для применения пиксельных фильтров к визуальному представлению виджета или создания скриншотов. Реализация методов растеризации представлена в RenderRepaintBoundary.

С точки зрения фреймворка RenderObject — это абстрактный класс, который не привязан к определённой системе координат и не ограничивает возможные способы компоновки объектов на экране. В большинстве практических задач вместо класса RenderObject используется один из расширяющих его классов:

flutter_3_12.2

  • RenderBox — ориентирован на работу с плоскими двумерными поверхностями (например, в области для рисования на экране мобильного устройства или окна приложения) и двумерную компоновку объектов на экране. Этот класс реализует модель иерархического размещения, где объекты-контейнеры позиционируют внутри себя дочерние объекты с использованием информации об их размерах и об ограничениях от родительских объектов.
  • RenderSliver — использует модель одномерного размещения в прокручиваемых по горизонтали или вертикали объектах. Применяется для создания элементов списков, зависящих от положения прокрутки. Например, для заголовков, изменяющихся в процессе прокрутки, или заголовков, которые присоединяются к верхнему краю и остаются неподвижными при дальнейшей прокрутке.
  • RenderView — основной контейнер для размещения всех остальных RenderObject, в большинстве случаев соответствует экрану телефона или окну приложения для Web/Desktop. Доступ к RenderView из любого RenderObject может быть получен через обращение к свойству pipelineOwner.rootNode (более подробно про pipelineOwner можно прочитать в статье про сервисы связи). RenderView создаётся в методе initRenderView в RendererBinding на основе конфигурации экрана и указателя на платформенную поверхность для рисования.
  • Вы можете создать собственный RenderObject, использующий другую модель ограничений, например для позиционирования в полярной системе координат или для размещения виджетов в трёхмерном пространстве.

Ниже мы последовательно разберёмся с каждым аспектом RenderObject и покажем, как их использовать для решения реальных задач. Все классы, которые понадобятся нам в примерах, могут быть импортированы через import 'package:flutter/rendering.dart'.

Пример использования RenderObject

Чтобы разобраться с механизмом работы RenderObject, рассмотрим простой пример — изображение аналоговых часов.

Оно состоит из двух линий разной длины и толщины, которые обозначают часовую и минутную стрелку. В этом примере мы расширим RenderObject с помощью RenderBox, причём этот класс не управляет никакими другими вложенными объектами.

Для минимально возможного определения такого RenderObject нам нужно будет решить следующие задачи:

  1. Определить размер RenderBox. Для простоты размер в первом примере будет фиксированный, впоследствии добавим поддержку внешних ограничений.
  2. Нарисовать аналоговые часы для указанного времени, предусмотреть возможность изменения значения времени через конфигурацию связанного виджета.

RenderObject обычно не создаются вручную, а управляются фреймворком с тем же жизненным циклом, что и у элемента. В действительности за создание и обновление RenderObject отвечает базовый класс RenderObjectElement, экземпляр объекта которого непосредственно создаётся в RenderObjectWidget.

RenderObject создаётся при добавлении RenderObjectElement в дерево элементов в методе виджета createRenderObject. Созданный RenderObject присоединяется к родительскому объекту, который обнаруживается при поиске RenderObjectElement по дереву элементов вверх. Изменение конфигурации виджета приводит к вызову метода updateRenderObject, в котором реализуется обновление свойств RenderObject для соответствия новой конфигурации.

Дерево RenderObject — подмножество дерева виджетов, поскольку некоторые виджеты собираются из других виджетов, при этом сами не содержат связанных RenderObject. Кроме того, в самом фреймворке и в библиотеках представлено множество виджетов, у которых нет визуального представления: они обеспечивают передачу данных, реализацию управления состоянием и многое другое. Для таких виджетов тоже не создаётся связанный RenderObject.

Так, например, для дерева виджетов с изображения ниже создаётся соответствующее дерево элементов, которое преобразуется в дерево RenderObject. Обратите внимание, что изначальное дерево виджетов было меньше: Image — это StatefulWidget и раскрывается в дополнительные виджеты Semantics и RawImage после вызова метода build.

Кроме того, дерево RenderObject содержит меньше объектов, чем дерево элементов (поскольку не все элементы имеют визуальное представление).

flutter_3_12.3

RenderObject объединяются в дерево через сохранение родительского объекта в своём свойстве parent и накопление списка дочерних объектов на этапе монтирования в дерево. Ссылка на родительский объект может использоваться для поиска объекта определённого типа по дереву вверх.

Например, для нахождения ближайшего RenderRepaintBoundary с собственным композиционным слоем для ограничения зоны обновления. Список дочерних объектов используется в методах visitChildren и visitChildrenForSemantics для выполнения действий с обходом дерева.

Также в родительском объекте сохраняется информация от дочерних объектов через свойство parentData, которое первоначально инициализируется при присоединении объекта в дерево в методе setupParentData.

На первом этапе мы будем встраивать новый RenderObject через специальный виджет WidgetToRenderBoxAdapter, который будет использовать наш объект для создания собственного визуального отображения.

Для определения последовательности операций отрисовки RenderBox переопределим реализацию двух методов — performLayout для определения размера RenderObject и paint для создания визуального представления. Метод paint принимает два аргумента — PaintingContext и offset.

PaintingContext обеспечивает возможность создания многослойного изображения с применением визуальных эффектов и кэширования и предоставляет canvas для создания изображения. Более подробно про Canvas можно почитать в этом статье.

Offset определяет смещение в пространстве экрана, на которое дополнительно могут накладываться трансформации, применённые ранее. Значение смещения определяется родительским объектом при вызове метода paintChild из PaintingContext.

Код
        import 'package:flutter/material.dart';
        import 'dart:math';

        void main() {
          runApp(MyApp());
        }

        class MyApp extends StatelessWidget {
          @override
          Widget build(BuildContext context) {
            return MaterialApp(
              theme: ThemeData.dark(),
              debugShowCheckedModeBanner: false,
              home: const Scaffold(
                body: Center(
                  child: MyClockApp(),
                ),
              ),
            );
          }
        }

        class ClockRenderBox extends RenderBox {
          final Size _ownSize;  //размер области отрисовки
          final Offset _offset; //дополнительное смещение
          final double _hour;   //значение часов (в 12-ти часовом формате)
          final double _minute; //значение минут (0-59)

          ClockRenderBox(
            this._ownSize,
            this._offset,
            this._hour,
            this._minute,
          );

          @override
          void performLayout() => size = _ownSize;

          @override
          void paint(PaintingContext context, Offset offset) {
            final center = _ownSize.center(offset);
            final radius = _ownSize.shortestSide / 2;
            final hourToRads = _hour / 12 * 2 * pi;
            final minsToRads = _minute / 60 * 2 * pi;
            final paintHours = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 5
              ..color = Colors.white;
            final paintMins = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 2
              ..color = Colors.grey;
            context.canvas.drawLine(
              _offset + center,
              _offset +
                  center +
                  Offset(
                    radius / 2 * cos(pi / 2 - hourToRads),
                    -radius / 2 * sin(pi / 2 - hourToRads),
                  ),
              paintHours,
            );
            context.canvas.drawLine(
              _offset + center,
              _offset +
                  center +
                  Offset(
                    radius * cos(pi / 2 - minsToRads),
                    -radius * sin(pi / 2 - minsToRads),
                  ),
              paintMins,
            );
          }
        }

        class MyClockApp extends StatelessWidget {
          const MyClockApp({super.key});

          @override
          Widget build(BuildContext context) {
            return WidgetToRenderBoxAdapter(
              renderBox: ClockRenderBox(
                const Size.square(256),
                const Offset(64, 64),
                13.0,
                39.0,
              ),
            );
          }
        }

Эта реализация работает корректно, но после создания у нас не будет возможности внести изменения в свойства отображаемого объекта. Для любого RenderObject можно вручную выполнять управление его дочерними объектами, и мы можем только пересоздать новый экземпляр объекта и заменить его через dropChild/adoptChild.

Но при этом фреймворк не сможет оптимизировать обновление, поскольку будет рассматривать RenderObject как новый и повторно запускать все этапы измерения, размещения и отрисовки объекта. Это негативно повлияет на производительность приложения. Более правильным решением будет использование методов RenderObject для отправки уведомлений о необходимости выполнения одного или нескольких этапов обновления при обнаружении изменения свойств.

Давайте посмотрим, какие шаги выполняются фреймворком для каждого RenderObject при первом запуске. Для этого изучим исходный код метода drawFrame в RendererBinding (комментарии автора кода):

pipelineOwner.flushLayout();
pipelineOwner.flushCompositingBits();
pipelineOwner.flushPaint();
if (sendFramesToEngine) {
  renderView.compositeFrame(); // this sends the bits to the GPU
  pipelineOwner.flushSemantics(); // this also sends the semantics to the OS.
  _firstFrameSent = true;
}
  • На первом этапе (flushLayout) все RenderObject измеряют вложенные объекты в соответствии с полученными от них размерами — или используя другой алгоритм, который не опирается на размеры, как, например, в Stack.
  • Второй этап (compositingBits) объединяет кэшированные изображения в пределах композиционного слоя, который создаётся в ближайшем RenderRepaintBoundary. Возможность переиспользования растрового изображения возникает достаточно часто, когда изменяется положение объекта, но не его содержание, или объект не изменяется.
  • На третьем этапе (paint) создаются новые изображения для всех RenderObject, которые запросили перерисовку. Этот шаг может быть пропущен, если кэшированная версия по-прежнему актуальна.
  • На четвертом этапе (compositeFrame) полученная сцена из кэшированных и отрисованных слоёв отправляется в Flutter Engine и преобразуется в растровое изображение на экране.
  • Ну и на последнем этапе (flushSemantics) в операционную систему отправляется информация о расположении объектов на экране и их назначении (подсказки для голосового помощника, возможные действия над объектами и так далее).

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

Как вы помните, у элементов есть флаг dirty — он сигнализирует о необходимости обновления. RenderObject вместо флага использует несколько методов — они подсказывают pipelineOwner, какие действия нужно выполнить на следующем кадре:

  • markNeedsLayout — добавляет объект в ожидающие переразметки. Используется, например, при изменении свойств, влияющих на относительное положение объекта или на измерение размера RenderObject, например при добавлении отступов. На следующем drawFrame будет вызван метод performLayout, если для RenderObject свойство sizedByParent принимает значение false. Обратите внимание, что в случае изменения размера и наличия родительского контейнера, который этот размер использует, также нужно вызвать метод markParentNeedsLayout, о нём ниже.
  • markNeedsCompositingBitsUpdate — помечает объект как требующий перекомпоновки составных частей. Чаще всего необходимо вызывать в случае, когда для вложенного объекта ожидается изменение визуального представления или применяется какой-либо эффект.
  • markNeedsPaint — добавляет объект в список требующих обновления визуального представления (на следующем drawFrame будет вызван метод paint).
  • markNeedsSemanticUpdate — вызывается при необходимости сообщения новой семантической информации. Например, при изменении надписи на кнопке нужно об этом уведомить операционную систему.
  • markParentNeedsLayout — сообщение родительскому объекту об изменении размера от дочернего объекта. Например, если родительский объект выполняет относительное позиционирование вложенных объектов — как RenderFlex, который соответствует виджетам Column/Row/Flex.
  • markNeedsLayoutForSizedByParentChange — вызывается в случае изменения значения флага sizedByParent, при этом объект измеряет себя самостоятельно или размер ему сообщает родительский объект.
  • reassemble — метод вызывает первые четыре метода из этого списка для себя и всего поддерева RenderObject, может быть использован при необходимости форсированного обновления части дерева целиком.

Для нашего случая необходимо при изменении любого свойства вызывать метод markNeedsPaint(), поскольку и значение времени, и положение/размер стрелок влияют на растровое отображение часов. При изменении размера также вызовем метод markNeedsLayout() для обновления сохранённого в поле size размера.

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

  • виджет с конфигурацией часов наследуется от базового класса LeafRenderObjectWidget;
  • в методе createRenderObject создаётся соответствующий RenderObject для отображения часов;
  • в RenderObject создаются set-методы для изменения значений свойств и вызова необходимых методов markNeeds* (в качестве побочного эффекта). Установка пометки необходимости обновления имеет смысл, только если значение действительно изменилось;
  • в методе updateRenderObject передаются изменения значений из конфигурации виджета в RenderObject.

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

Относительно измерения размера существует две тактики для RenderObject:

  • sizedByParent возвращает true, в этом случае размер может быть получен из свойства size в RenderBox (при изменении также вызывается performResize);
  • sizedByParent возвращает false, размер определяется виджетом самостоятельно в методе computeDryLayout с использованием ограничений от родителя и сохраняется в size внутри обязательно реализованного метода performLayout . Это значение возвращается по умолчанию.

Теперь, поскольку размер известен, мы можем добавлять виджет с этим RenderObject в любые контейнеры размещения, например в Column. Дополнительно создадим простой виджет, обновляющий значения свойств в связанном RenderObject.

Вот как это будет выглядеть в коде
        import 'package:flutter/material.dart';
        import 'dart:math';

        class Clock extends LeafRenderObjectWidget {
          final Size size;
          final Offset offset;
          final double hour;
          final double minute;

          const Clock({
            required this.size,
            required this.offset,
            required this.hour,
            required this.minute,
            super.key,
          });

          @override
          RenderObject createRenderObject(BuildContext context) =>
              ClockRenderBox(size, offset, hour, minute);

          @override
          void updateRenderObject(
              BuildContext context, covariant RenderObject renderObject) {
            final clockRenderObject = renderObject as ClockRenderBox;
            clockRenderObject
              ..ownSize = size
              ..offset = offset
              ..hour = hour
              ..minute = minute;
          }
        }

        class ClockRenderBox extends RenderBox {
          Size _size;
          Offset _offset;
          double _hour;
          double _minute;

          ClockRenderBox(
            this._size,
            this._offset,
            this._hour,
            this._minute,
          );

          @override
          get sizedByParent => false;

          @override
          void performLayout() => size = _size;

          set ownSize(Size newSize) {
            if (newSize != _size) {
              _size = newSize;
              markNeedsPaint();
              markNeedsLayout();
            }
          }

          set offset(Offset offset) {
            if (offset != _offset) {
              _offset = offset;
              markNeedsPaint();
            }
          }

          set hour(double hour) {
            if (hour != _hour) {
              _hour = hour;
              markNeedsPaint();
              markNeedsSemanticsUpdate();
            }
          }

          set minute(double minute) {
            if (minute != _minute) {
              _minute = minute;
              markNeedsPaint();
              markNeedsSemanticsUpdate();
            }
          }

          @override
          void paint(PaintingContext context, Offset offset) {
            final center = size.center(offset + _offset);
            final radius = size.shortestSide / 2;
            final hourToRads = _hour / 12 * 2 * pi;
            final minsToRads = _minute / 60 * 2 * pi;
            final paintHours = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 5
              ..color = Colors.white;
            final paintMins = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 2
              ..color = Colors.grey;
            context.canvas.drawLine(
              center,
              center +
                  Offset(
                    radius / 2 * cos(pi / 2 - hourToRads),
                    -radius / 2 * sin(pi / 2 - hourToRads),
                  ),
              paintHours,
            );
            context.canvas.drawLine(
              center,
              center +
                  Offset(
                    radius * cos(pi / 2 - minsToRads),
                    -radius * sin(pi / 2 - minsToRads),
                  ),
              paintMins,
            );
          }
        }

        class ClockData {
          Offset offset = Offset.zero;
          Size size = const Size.square(128);
          double hour = 0;
          double minute = 0;
        }

        class MyClockApp extends StatefulWidget {
          const MyClockApp({super.key});

          @override
          State<MyClockApp> createState() => _MyClockAppState();
        }

        class _MyClockAppState extends State<MyClockApp> {
          final clockData = ClockData();

          @override
          Widget build(BuildContext context) {
            return MaterialApp(
              theme: ThemeData.dark(useMaterial3: false),
              home: Scaffold(
                body: SafeArea(
                  child:
                      Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
                    ElevatedButton(
                      onPressed: () =>
                          setState(() => clockData.offset += const Offset(1, 1)),
                      child: const Text('Shift'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.size *= 1.1),
                      child: const Text('Resize'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.hour++),
                      child: const Text('Increment hour'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.minute++),
                      child: const Text('Increment min'),
                    ),
                    Clock(
                      size: clockData.size,
                      offset: clockData.offset,
                      hour: clockData.hour,
                      minute: clockData.minute,
                    ),
                  ]),
                ),
              ),
            );
          }
        }

        void main() {
          runApp(const MyClockApp());
        }

Теперь сделаем так, чтобы размер наших часов был не фиксированным, а зависел от размеров родителя.

Измерение, позиционирование и RenderBox-протокол

Изначально RenderObject не использует никакую систему координат и делегирует реализацию абстрактного измерения на дочерние объекты. Для определения размера RenderObject используется метод performLayout, который вызывается, если sizedByParent возвращает false.

В противном случае, если sizedByParent возвращает true, размер дочернего объекта определяется на этапе разметки родительского объекта. Результатом выполнения performLayout должно быть изменение поля size , в которое сохраняется расчётный размер RenderObject. Также на этом этапе могут быть переданы данные в родительский объект через свойство parentData для управления позиционированием дочерних объектов внутри родительского.

Для управления измерением и размещением мы будем использовать реализацию пустой абстракции Constraints.

RenderBox использует модель двумерной поверхности и соответствующий тип ограничений BoxConstraints, описывающий диапазон возможных размеров от минимального до максимального. В частном случае ограничение может быть:

  • строгим (граничные значения совпадают);
  • только сверху (минимальный размер — 0, 0);
  • только снизу (максимальный размер — бесконечность).

Напомним основные идеи протокола RenderBox:

  • Родительские виджеты (на самом деле связанные с ними RenderObject) передают ограничения к дочерним RenderObject.
  • Дочерние RenderObject измеряют себя и корректируют размер с учётом ограничений. При этом размер может остаться неизменным, уменьшиться при превышении верхнего ограничения или увеличиться, если от родителя пришла более высокая нижняя граница, чем ожидал объект.
  • Родительские RenderObject размещают дочерние RenderObject исходя из полученных измерений и информации, сохранённой в parentData. Например, позиционируют по центру относительно максимального ограничения, как делает виджет Center и связанный с ним RenderPositionedBox.

Согласно протоколу RenderBox, каждый расширяющий его класс должен учитывать ограничения при определении собственного размера. В методе performLayout есть доступ к полю объекта constraints, которое поступает от родительского объекта, и оно должно использоваться для определения собственного размера RenderObject. В нашей реализации для учёта ограничений от родителей необходимо выполнить следующие изменения:

  @override
  Size computeDryLayout(BoxConstraints constraints) => constraints.constrain(_size);

  @override
  void performLayout() => size = constraints.constrain(_size);

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

Код
        import 'package:flutter/material.dart';
        import 'dart:math';

        class Clock extends LeafRenderObjectWidget {
          final Size size;
          final Offset offset;
          final double hour;
          final double minute;

          const Clock({
            required this.size,
            required this.offset,
            required this.hour,
            required this.minute,
            super.key,
          });

          @override
          RenderObject createRenderObject(BuildContext context) =>
              ClockRenderBox(size, offset, hour, minute);

          @override
          void updateRenderObject(
              BuildContext context, covariant RenderObject renderObject) {
            final clockRenderObject = renderObject as ClockRenderBox;
            clockRenderObject
              ..ownSize = size
              ..offset = offset
              ..hour = hour
              ..minute = minute;
          }
        }

        class ClockRenderBox extends RenderBox {
          Size _size;
          Offset _offset;
          double _hour;
          double _minute;

          ClockRenderBox(
            this._size,
            this._offset,
            this._hour,
            this._minute,
          );

          @override
          get sizedByParent => false;

          @override
          Size computeDryLayout(BoxConstraints constraints) =>
              constraints.constrain(_size);

          @override
          void performLayout() => size = constraints.constrain(_size);

          set ownSize(Size newSize) {
            if (newSize != _size) {
              _size = newSize;
              markNeedsPaint();
              markNeedsLayout();
            }
          }

          set offset(Offset offset) {
            if (offset != _offset) {
              _offset = offset;
              markNeedsPaint();
            }
          }

          set hour(double hour) {
            if (hour != _hour) {
              _hour = hour;
              markNeedsPaint();
              markNeedsSemanticsUpdate();
            }
          }

          set minute(double minute) {
            if (minute != _minute) {
              _minute = minute;
              markNeedsPaint();
              markNeedsSemanticsUpdate();
            }
          }

          @override
          void paint(PaintingContext context, Offset offset) {
            final center = size.center(offset + _offset);
            final radius = size.shortestSide / 2;
            final hourToRads = _hour / 12 * 2 * pi;
            final minsToRads = _minute / 60 * 2 * pi;
            final paintHours = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 5
              ..color = Colors.white;
            final paintMins = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 2
              ..color = Colors.grey;
            context.canvas.drawLine(
              center,
              center +
                  Offset(
                    radius / 2 * cos(pi / 2 - hourToRads),
                    -radius / 2 * sin(pi / 2 - hourToRads),
                  ),
              paintHours,
            );
            context.canvas.drawLine(
              center,
              center +
                  Offset(
                    radius * cos(pi / 2 - minsToRads),
                    -radius * sin(pi / 2 - minsToRads),
                  ),
              paintMins,
            );
          }
        }

        class ClockData {
          Offset offset = Offset.zero;
          Size size = const Size.square(128);
          double hour = 0;
          double minute = 0;
        }

        class MyClockApp extends StatefulWidget {
          const MyClockApp({super.key});

          @override
          State<MyClockApp> createState() => _MyClockAppState();
        }

        class _MyClockAppState extends State<MyClockApp> {
          final clockData = ClockData();

          @override
          Widget build(BuildContext context) {
            return MaterialApp(
              theme: ThemeData.dark(useMaterial3: false),
              home: Scaffold(
                body: SafeArea(
                  child:
                      Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
                    ElevatedButton(
                      onPressed: () =>
                          setState(() => clockData.offset += const Offset(1, 1)),
                      child: const Text('Shift'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.size *= 1.1),
                      child: const Text('Resize'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.hour++),
                      child: const Text('Increment hour'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.minute++),
                      child: const Text('Increment min'),
                    ),
                    //добавили constraints, ограничивающие изменение размера до квадрата со стороной 200
                    LimitedBox(
                      maxWidth: 200,
                      maxHeight: 200,
                      child: Clock(
                        size: clockData.size,
                        offset: clockData.offset,
                        hour: clockData.hour,
                        minute: clockData.minute,
                      ),
                    ),
                  ]),
                ),
              ),
            );
          }
        }

        void main() {
          runApp(const MyClockApp());
        }

Модель Constraints допускает создание альтернативной системы ограничений, которая отличается от размещения двумерных объектов в пространстве экрана, и ниже мы рассмотрим пример с SliverConstraints для позиционирования объектов в прокручиваемых списках.

А пока давайте расширим наш пример и добавим поддержку реакции на касания в области часов для управления минутной стрелкой. В этом нам поможет обратная связь и механизм реакции RenderObject на внешние события.

Реакция на действия пользователя

При возникновении событий дерево RenderObject получает сообщение через вызов метода hitTest. Событием может быть прикосновение к экрану на мобильных устройствах или перемещение курсора на десктопных. Далее мы будем говорить только о прикосновениях к экрану.

Итак, метод hitTest принимает позицию касания в относительных координатах основного слоя RenderObject. В результате выполнения hitTest может быть возвращено true, если нужно остановить обработку события прикосновения, или false, чтобы передать это сообщение другим RenderObject, расположенным в той же области экрана.

Обработка начинается с вершины дерева, в котором расположен RenderView, занимающий доступное пространство экрана для приложения, при этом каждый RenderObject передаёт сообщение своим дочерним объектам, логика которых реализуется в методе hitTestChildren.

Если RenderObject размещён в каком-либо контейнере, например в Column, сообщение будет отправлено последовательно всем дочерним объектам независимо от координаты точки касания. Обработка сообщения завершится на первом объекте, который вернёт true, поэтому важно делать дополнительную проверку принадлежности координат точки касания прямоугольнику, включающему наш объект. С точки зрения проверки координаты точка касания должна находиться в интервале от (0, 0) до size.

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

Код
class ClockRenderBox extends RenderBox {
  Size _size;
  Offset _offset;
  double _hour;
  double _minute;
  ValueSetter<double> onUpdateMinutes;

  ClockRenderBox(
    this._size,
    this._offset,
    this._hour,
    this._minute,
    this.onUpdateMinutes,
  );

  @override
  bool hitTest(BoxHitTestResult result, {required Offset position}) {
    // проверка, что точка касания находится внутри прямоугольника RenderObject
    if (!(Offset.zero & size).contains(position)) return false;
    //регистрация события касания (будет передано в handleEvent)
    result.add(BoxHitTestEntry(this, position));
    return true;
  }

  @override
  void handleEvent(PointerEvent event, covariant BoxHitTestEntry entry) {
   // entry.localPosition здесь получит значение position из hitTest
    final center = size / 2;
    final position = entry.localPosition;
    double angle =
        atan2(position.dx - center.width, position.dy - center.height) + pi;
    if (angle > 2 * pi) {
      angle = angle - 2 * pi;
    }
    final minutes = (2 * pi - angle) / (2 * pi) * 60;
    onUpdateMinutes(minutes);
  }

...
}

class Clock extends LeafRenderObjectWidget {
  final Size size;
  final Offset offset;
  final double hour;
  final double minute;
  final ValueSetter<double> onUpdateMinutes;

  const Clock({
    required this.size,
    required this.offset,
    required this.hour,
    required this.minute,
    required this.onUpdateMinutes,
    super.key,
  });
//...
}

При вызове виджета также передаём коллбек:

Код
            Clock(
              size: clockData.size,
              offset: clockData.offset,
              hour: clockData.hour,
              minute: clockData.minute,
              onUpdateMinutes: (minutes) {
                setState(() => clockData.minute = minutes);
              },
            ),

Информация об обработке события может быть сохранена в объект HitTestResult. Он собирает информацию о событиях взаимодействия с RenderObject, а также о применённых трансформациях для трансляции экранной системы координат в координаты внутри виджета.

Полученные HitTestResult в дальнейшем передаются в метод-обработчик handleEvents, который также получает более подробную информацию о событии в PointerEvent и значение относительных координат точки касания, полученное через BoxHitTestEntry.

Вот как будет выглядеть наш код
        import 'package:flutter/material.dart';
        import 'dart:math';

        import 'package:flutter/rendering.dart';

        class Clock extends LeafRenderObjectWidget {
          final Size size;     //размер области отрисовки
          final Offset offset; //дополнительное смещение
          final double hour;   //часы
          final double minute; //минуты
          final ValueSetter<double> onUpdateMinutes;  //действие при изменении минут

          const Clock({
            required this.size,
            required this.offset,
            required this.hour,
            required this.minute,
            required this.onUpdateMinutes,
            super.key,
          });

          @override
          RenderObject createRenderObject(BuildContext context) =>
              ClockRenderBox(size, offset, hour, minute, onUpdateMinutes);

          @override
          void updateRenderObject(
              BuildContext context, covariant RenderObject renderObject) {
            final clockRenderObject = renderObject as ClockRenderBox;
            clockRenderObject
              ..ownSize = size
              ..offset = offset
              ..hour = hour
              ..minute = minute;
          }
        }

        class ClockRenderBox extends RenderBox {
          Size _size;
          Offset _offset;
          double _hour;
          double _minute;
          ValueSetter<double> onUpdateMinutes;

          ClockRenderBox(
            this._size,
            this._offset,
            this._hour,
            this._minute,
            this.onUpdateMinutes,
          );

          @override
          bool hitTest(BoxHitTestResult result, {required Offset position}) {
            //проверка, что касание экрана произошло в прямоугольнике часов
            if (!(Offset.zero & size).contains(position)) return false;
            //если да, добавляем событие
            result.add(BoxHitTestEntry(this, position));
            return true;
          }

          @override
          void handleEvent(PointerEvent event, covariant BoxHitTestEntry entry) {
            //entry.localPosition здесь получит значение position из hitTest
            final center = size / 2;
            //переводим координаты точки касания в соответствующее значение угла
            final position = entry.localPosition;
            double angle =
                atan2(position.dx - center.width, position.dy - center.height) + pi;
            if (angle > 2 * pi) {
              angle = angle - 2 * pi;
            }
            final minutes = (2 * pi - angle) / (2 * pi) * 60;
            onUpdateMinutes(minutes);
          }

          @override
          get sizedByParent => false;

          @override
          Size computeDryLayout(BoxConstraints constraints) =>
              constraints.constrain(_size);

          @override
          void performLayout() => size = constraints.constrain(_size);

          set ownSize(Size newSize) {
            if (newSize != _size) {
              _size = newSize;
              markNeedsPaint();
              markNeedsLayout();
            }
          }

          set offset(Offset offset) {
            if (offset != _offset) {
              _offset = offset;
              markNeedsPaint();
            }
          }

          set hour(double hour) {
            if (hour != _hour) {
              _hour = hour;
              markNeedsPaint();
              markNeedsSemanticsUpdate();
            }
          }

          set minute(double minute) {
            if (minute != _minute) {
              _minute = minute;
              markNeedsPaint();
              markNeedsSemanticsUpdate();
            }
          }

          @override
          void paint(PaintingContext context, Offset offset) {
            final center = size.center(offset + _offset);
            final radius = size.shortestSide / 2;
            final hourToRads = _hour / 12 * 2 * pi;
            final minsToRads = _minute / 60 * 2 * pi;
            final paintHours = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 5
              ..color = Colors.white;
            final paintMins = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 2
              ..color = Colors.grey;
            context.canvas.drawLine(
              center,
              center +
                  Offset(
                    radius / 2 * cos(pi / 2 - hourToRads),
                    -radius / 2 * sin(pi / 2 - hourToRads),
                  ),
              paintHours,
            );
            context.canvas.drawLine(
              center,
              center +
                  Offset(
                    radius * cos(pi / 2 - minsToRads),
                    -radius * sin(pi / 2 - minsToRads),
                  ),
              paintMins,
            );
          }
        }

        class ClockData {
          Offset offset = Offset.zero;
          Size size = const Size.square(128);
          double hour = 0;
          double minute = 0;
        }

        class MyClockApp extends StatefulWidget {
          const MyClockApp({super.key});

          @override
          State<MyClockApp> createState() => _MyClockAppState();
        }

        class _MyClockAppState extends State<MyClockApp> {
          final clockData = ClockData();

          @override
          Widget build(BuildContext context) {
            return MaterialApp(
              theme: ThemeData.dark(useMaterial3: false),
              home: Scaffold(
                body: SafeArea(
                  child:
                      Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
                    ElevatedButton(
                      onPressed: () =>
                          setState(() => clockData.offset += const Offset(1, 1)),
                      child: const Text('Shift'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.size *= 1.1),
                      child: const Text('Resize'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.hour++),
                      child: const Text('Increment hour'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.minute++),
                      child: const Text('Increment min'),
                    ),
                    //ограничитель размера области отрисовки
                    LimitedBox(
                      maxWidth: 200,
                      maxHeight: 200,
                      child: Clock(
                        size: clockData.size,
                        offset: clockData.offset,
                        hour: clockData.hour,
                        minute: clockData.minute,
                        onUpdateMinutes: (minutes) {
                          setState(() => clockData.minute = minutes);
                        },
                      ),
                    ),
                  ]),
                ),
              ),
            );
          }
        }

        void main() {
          runApp(const MyClockApp());
        }

При обработке касаний также могут быть полезны методы из RenderBox.

Метод

Назначение

localToGlobal(Offset)

переход от локальных координат к экранным (координата 0,0 соответствует левому верхнему углу экрана, на мобильных устройствах находится под областью уведомлений)

globalToLocal(Offset)

для преобразований экранных координат в локальные для RenderObject

getTransforTo(otherRenderObject)

определение Matrix4-преобразования координат точки из локальной системы координат нашего RenderObject в систему координат другого RenderObject (например, для вывода визуальных отметок в родительский объект при касании дочернего)

Также для использования стандартного поведения для RenderObject с одним дочерним объектом (нажатие считается успешным при попадании точки касания в paintBounds для RenderObject) можно использовать базовый класс RenderProxyBoxWithHitBehavior.

Теперь сделаем стрелки полупрозрачными. В этом нам поможет PaintingContext.

Связь RenderObject и PaintingContext

Об этом у нас будет целый отдельный статья, пока пройдёмся по верхам.

PaintingContext — это класс, который расширяет возможности Canvas: позволяет создавать произвольные слои и добавлять визуальные эффекты. Например, прозрачность, различные преобразования растрового изображения — размытие, аффинные преобразования для масштабирования/сдвига/поворота и любых их комбинаций. Использование Canvas не отличается от рассмотренного ранее в статье про CustomPainter.

Углубляться в PaintingContext мы сейчас не будем — боимся вас запутать. Но если вам любопытно, то вот ссылка на документацию. Пока что коротко отметим пару нюансов, которые имеют отношение к RenderObject.

Итак, PaintingContext использует модель слоёв. Если вы хоть раз работали в Photoshop или любом другом редакторе изображений — вы имеете представление о том, что это такое.

Если нет — представьте что вы смотрите сверху на стопку прозрачной бумаги, где на каждом листе нарисовано какое-то изображение. Все вместе они создают цельную картину, а по отдельности каждый их них — слой. Причём верхние слои перекрывают нижние.

Само собой, слои во Flutter устроены сложнее. Например, смещение изображения или добавление прозрачности — это тоже слои.

Для смещения изображения мы применяем OffsetLayer (контейнерный слой). Он всегда создаётся автоматически для RenderObject, у которого isRepaintBoundary возвращает true — тогда область перерисовки ограничивается областью экрана, занимаемой этим объектом.

Созданный OffsetLayer доступен через свойство layer. Если слой не был создан автоматически, будет использоваться ближайший контейнерный слой, который был найден выше по дереву, а значение layer будет null. Даже в этом случае слой может быть создан программно и записан в свойство layer, тогда и canvas будет использовать указанный слой для рисования.

Зная это, мы можем добавить эффект полупрозрачного отображения для стрелок наших часов и сдвинуть их в нужное место. Используем метод PaintingContext.pushOpacity(), который создаёт новый слой прозрачности.

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

Код
    context.pushOpacity(
      center + offset,
      64,    // прозрачность (0—255, 0 — полностью прозрачный)
      (context, offset) {
        context.canvas.drawLine(
          offset,
          offset +
              Offset(
                radius / 2 * cos(pi / 2 - hourToRads),
                -radius / 2 * sin(pi / 2 - hourToRads),
              ),
          paintHours,
        );
        context.canvas.drawLine(
          offset,
          offset +
              Offset(
                radius * cos(pi / 2 - minsToRads),
                -radius * sin(pi / 2 - minsToRads),
              ),
          paintMins,
        );
      },
    );

Теперь добавим анимацию прозрачности для нашего RenderObject. Для этого разберёмся с моделью жизненного цикла и возможными состояниями объекта.

Жизненный цикл RenderObject

RenderObject создаётся без привязки к дереву (поля owner и parent равны null) и затем подключается в дерево в позицию, которая соответствует родительскому элементу в процессе встраивания нового элемента в своё дерево. Для этого в методе mount для RenderObjectElement создается экземпляр RenderObject через вызов createRenderObject из виджета.

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

Аналогично при исключении RenderObject из дерева, если создавший его виджет был перемещён или удалён, у RenderObject вызывается метод detach, который также должен выполнить обращение к detach для всех дочерних объектов.

При этом RenderObject может быть возвращён в другое место дерева — например, при использовании Hero-анимации (более подробно про анимации можно почитать в этом статье) или перемещении виджетов с глобальными ключами. В случае если RenderObject более не будет использоваться, вызывается метод dispose.

В нашем примере мы можем использовать методы жизненного цикла для создания анимации прозрачности. Здесь мы получим Ticker непосредственно в нашем классе, но более правильным будет решение создавать его в State виджета и передавать в конструктор при создании.

Код
        import 'package:flutter/material.dart';
        import 'dart:math';

        import 'package:flutter/rendering.dart';
        import 'package:flutter/scheduler.dart';

        class Clock extends LeafRenderObjectWidget {
          final Size size;
          final Offset offset;
          final double hour;
          final double minute;
          final ValueSetter<double> onUpdateMinutes;
          final ValueSetter<double> onUpdateHours;

          const Clock({
            required this.size,
            required this.offset,
            required this.hour,
            required this.minute,
            required this.onUpdateMinutes,
            required this.onUpdateHours,
            super.key,
          });

          @override
          RenderObject createRenderObject(BuildContext context) => ClockRenderBox(
                size,
                offset,
                hour,
                minute,
                onUpdateMinutes,
                onUpdateHours,
              );

          @override
          void updateRenderObject(
              BuildContext context, covariant RenderObject renderObject) {
            final clockRenderObject = renderObject as ClockRenderBox;
            clockRenderObject
              ..ownSize = size
              ..offset = offset
              ..hour = hour
              ..minute = minute;
          }
        }

        class ClockRenderBox extends RenderBox implements TickerProvider {
          Size _size;
          Offset _offset;
          double _hour;
          double _minute;
          ValueSetter<double> onUpdateMinutes;
          ValueSetter<double> onUpdateHours;
          AnimationController? _animationController;

          ClockRenderBox(
            this._size,
            this._offset,
            this._hour,
            this._minute,
            this.onUpdateMinutes,
            this.onUpdateHours,
          );

          @override
          get sizedByParent => false;

          @override
          Size computeDryLayout(BoxConstraints constraints) =>
              constraints.constrain(_size);

          @override
          void performLayout() => size = constraints.constrain(_size);

          @override
          void attach(PipelineOwner owner) {
            super.attach(owner);
            _animationController = AnimationController(
              vsync: this,
              lowerBound: 63,
              upperBound: 255,
              duration: const Duration(seconds: 1),
            );
            _animationController?.repeat();
            _animationController?.addListener(markNeedsPaint);
          }

          @override
          void detach() {
            _animationController?.stop();
            super.detach();
          }

          set ownSize(Size newSize) {
            if (newSize != _size) {
              _size = newSize;
              markNeedsPaint();
              markNeedsLayout();
            }
          }

          set offset(Offset offset) {
            if (offset != _offset) {
              _offset = offset;
              markNeedsPaint();
            }
          }

          set hour(double hour) {
            if (hour != _hour) {
              _hour = hour;
              markNeedsPaint();
              markNeedsSemanticsUpdate();
            }
          }

          set minute(double minute) {
            if (minute != _minute) {
              _minute = minute;
              markNeedsPaint();
              markNeedsSemanticsUpdate();
            }
          }

          @override
          void paint(PaintingContext context, Offset offset) {
            final center = size.center(offset + _offset);
            final radius = size.shortestSide / 2;
            final hourToRads = _hour / 12 * 2 * pi;
            final minsToRads = _minute / 60 * 2 * pi;
            final paintHours = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 5
              ..color = Colors.white;
            final paintMins = Paint()
              ..style = PaintingStyle.fill
              ..strokeWidth = 2
              ..color = Colors.grey;

            context.pushOpacity(center, _animationController?.value.toInt() ?? 255,
                (context, offset) {
              context.canvas.drawLine(
                offset,
                offset +
                    Offset(
                      radius / 2 * cos(pi / 2 - hourToRads),
                      -radius / 2 * sin(pi / 2 - hourToRads),
                    ),
                paintHours,
              );
              context.canvas.drawLine(
                offset,
                offset +
                    Offset(
                      radius * cos(pi / 2 - minsToRads),
                      -radius * sin(pi / 2 - minsToRads),
                    ),
                paintMins,
              );
            });
          }

          @override
          bool hitTest(BoxHitTestResult result, {required Offset position}) {
            if (!(Offset.zero & size).contains(position)) return false;
            result.add(BoxHitTestEntry(this, position));
            return true;
          }

          @override
          void handleEvent(PointerEvent event, covariant BoxHitTestEntry entry) {
            final center = size / 2;
            final position = entry.localPosition;
            double angle =
                atan2(position.dx - center.width, position.dy - center.height) + pi;
            if (angle > 2 * pi) {
              angle = angle - 2 * pi;
            }
            final minutes = (2 * pi - angle) / (2 * pi) * 60;
            onUpdateMinutes(minutes);
          }

          Ticker? _ticker;

          @override
          Ticker createTicker(TickerCallback onTick) {
            _ticker ??= Ticker(onTick);
            return _ticker!;
          }
        }

        class ClockData {
          Offset offset = Offset.zero;
          Size size = const Size.square(128);
          double hour = 0;
          double minute = 0;
        }

        class MyClockApp extends StatefulWidget {
          const MyClockApp({super.key});

          @override
          State<MyClockApp> createState() => _MyClockAppState();
        }

        class _MyClockAppState extends State<MyClockApp> {
          final clockData = ClockData();

          @override
          Widget build(BuildContext context) {
            return MaterialApp(
              theme: ThemeData.dark(useMaterial3: false),
              home: Scaffold(
                body: SafeArea(
                  child:
                      Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
                    ElevatedButton(
                      onPressed: () =>
                          setState(() => clockData.offset += const Offset(1, 1)),
                      child: const Text('Shift'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.size *= 1.1),
                      child: const Text('Resize'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.hour++),
                      child: const Text('Increment hour'),
                    ),
                    ElevatedButton(
                      onPressed: () => setState(() => clockData.minute++),
                      child: const Text('Increment min'),
                    ),
                    LimitedBox(
                      maxWidth: 200,
                      maxHeight: 200,
                      child: Clock(
                        size: clockData.size,
                        offset: clockData.offset,
                        hour: clockData.hour,
                        minute: clockData.minute,
                        onUpdateMinutes: (minutes) {
                          setState(() => clockData.minute = minutes);
                        },
                        onUpdateHours: (hours) {
                          setState(() => clockData.hour = hours);
                        },
                      ),
                    ),
                  ]),
                ),
              ),
            );
          }
        }

        void main() {
          runApp(const MyClockApp());
        }

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

Семантическая информация и обработка действий

Для мобильных и веб-приложений в операционной системе или браузере поддерживаются возможности Accessibility, в которую со стороны Flutter Engine необходимо отправить следующую информацию:

  • Передать размеры активного прямоугольника, который может подсвечиваться при использовании режима управления жестами для перемещения фокуса между элементами. Границы прямоугольника также используются некоторыми инструментами blackbox-тестирования, такими как Appium. В RenderObject семантические границы определяются get-методом semanticBounds и по умолчанию совпадают по размерам и положению с исходным объектом.
  • Определить через describeSemanticsConfiguration семантику RenderObject (информация из неё копируется в SemanticNode и собирается в дерево семантики, которое отправляется в операционную систему или браузер). Семантика содержит большое количество полей и атрибутов, например:

Общая информация об объекте

hint

текстовая подсказка о назначении элемента (например, смысл действия при нажатии кнопки)

label

текстовое описание элемента (может использоваться синтезатором речи TalkBack / VoiceOver)

increasedValue / decreasedValue

новое значение после выполнения семантического действия увеличения/уменьшения значения

currentValueLength / maxValueLength

текущее/максимальное количество символов в редактируемом текстовом поле

elevation

значение по оси z для RenderObject относительно родительского объекта

hintOverrides

переопределение подсказок по умолчанию для платформы (например, уведомления, что это кнопка)

indexInParent

порядковый номер в родительском контейнере

Флаги, показывающие состояние/возможности объекта

isButton

true, если это кнопка (может принимать фокус и выполнять действие «Нажать»)

isFocusable

может принимать фокус (используется при навигации жестами)

isFocused

сейчас находится в фокусе

isHeader

является заголовком страницы

isHidden

не отображается (обычно игнорируется при озвучивании и навигации)

isInMutuallyExclusiveGroup

является частью взаимоисключающей группы (например, radio-кнопки)

isLink

является ссылкой (может быть предложено действие «Выполнить переход»)

isMultiline

является многострочным полем

isObscured

значение поля должно быть скрыто (не должно быть произнесено вслух)

isReadOnly

поле доступно только для чтения

isSelected

текущий объект выбран (для checkbox/radio)

isSlider

является ли объект слайдером

isTextField

объект является текстовым полем (с возможностью ввода текста голосом или любыми устройствами ввода)

isToggled

объект включен (например, применяется для Switch)

isSemanticBoundary

необходимо создать собственный узел в дереве семантической информации для этого RenderObject

isMergingSemanticsOfDescendant

объединяет семантическую информацию дочерних элементов в общий объект

Функции для вызова при получении сообщений об ожидаемых действиях

onCopy

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

onCut, onPaste

аналогично для действий «Вырезать» и «Вставить»

onIncrease / onDecrease

действия со счётчиком, подразумевающие изменение значения (или выбор среди вариантов)

onTap, onLongPress

при обычном/долгом нажатии на объект

setText

замена текста (например, при голосовом вводе)

setSelection

изменение/расширение выделения текста

onScrollUp, onScrollDown, onScrollLeft, onScrollRight, onMoveCursorForwardByCharacter, onMoveCursorForwardByWord, onMoveCursorBackwardByCharacter, onMoveCursorBackwardByWord

перемещение с помощью курсора или комбинаций клавиш / специальных жестов

customSemanticsActions

связь произвольных семантических действий, определяются через CustomSemanticsAction(label: 'keyword'), и соответствующих функций-обработчиков

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

  @override
  Rect get semanticBounds => Offset.zero & size;

  @override
  void describeSemanticsConfiguration(SemanticsConfiguration config) {
    // текущее время, которое показывают часы
    config.value = '$_hour hours and $_minute minutes';
    //значение минутной стрелки после действий increment-decrement
    config.decreasedValue = _minute.toInt().toString();
    config.increasedValue = _minute.toInt().toString();

  config.onDecrease = () {
   // изменение времени (перемещение минутной стрелки назад)
      _minute--;
      if (_minute < 0) {
        _minute = 60 + _minute;
        _hour--;
        if (_hour < 0) _hour = 24 + _hour;
      }
      onUpdateMinutes(_minute);
      onUpdateHours(_hour);
      markNeedsSemanticsUpdate();
   };
    config.onIncrease = () {
   // изменение времени (перемещение минутной стрелки вперёд)
      _minute++;
      if (_minute >= 60) {
    // также отслеживаем часовую стрелку
        _minute = _minute - 60;
        _hour = (_hour + 1) % 24;
      }
      onUpdateMinutes(_minute);
      onUpdateHours(_hour);
      markNeedsSemanticsUpdate();
    };
    config.onTap = () {
      // семантическое действие «Нажать» переводит часовую стрелку
      _hour = (_hour + 1) % 24;
      onUpdateHours(_hour);
      markNeedsSemanticsUpdate();
    };
    // голосовая подсказка для действия при нажатии на RenderObject часов
    config.hint = 'Tap me to increment hours';
  }

Более подробно использование виджетов семантической разметки и управления семантическим деревом будет рассмотрено в одном из следующих статей.

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

Отладка RenderObject с использованием DevTools

Один из наиболее важных способов отладки RenderObject — инструменты DevTools, в которых можно получить информацию об эффективном дереве виджетов (полученном после вызовов build для StatelessWidget / StatefulWidget), соответствующем дереве элементов и связанным с ним состоянием (если есть), а также о присоединённом объекте RenderObject.

Дополнительная информация для DevTools может быть добавлена как для RenderObject, так и для элементов и виджетов, а также для любых объектов, которые используются в конфигурации виджета.

Чтобы описать объект, необходимо добавить к нему миксин Diagnosticable и переопределить метод debugFillProperties, который возвращает список свойств из реализаций класса DiagnosticableNode (примеры — в таблице ниже). Для описания дочерних объектов контейнера нужно переопределить метод debugDescribeChildren и добавить миксин DiagnosticableTreeMixin.

Поле

Описание

DiagnosticsProperty

именованное значение произвольного типа (может также содержать описание и множество параметров для настройки отображения), также определяется уровень сообщения (константы из DiagnosticsLevel: hidden — не показывать, fine, debug, warning, info, hint, summary, error, off), который может быть использован для фильтрации сообщений через аргумент minLevel

IterableProperty

список значений произвольного типа

EnumProperty

значение перечисляемого типа

FlagProperty

логическое именованное значение

StringProperty, IntProperty, DoubleProperty, ColorProperty, PercentProperty

используются для представления соответствующих типов данных

DiagnosticsBlock

группировка значений (содержит список children для DiagnosticsProperty)

DiagnosticableTreeNode

подэлемент дерева объектов, связанных с виджетом

ErrorSummary, ErrorDescription, ErrorHint

разные уровни ошибок (используются уровни DiagnosticsLevel error, info и hint)

Также может быть переопределён метод toDiagnosticsNode — для создания собственного представления RenderObject в DevTools.

По умолчанию реализация debugFillProperties в RenderObject сохраняет информацию о parentData, полученных ограничениях и измеренном размере объекта, но метод может быть переопределён для добавления собственных значений, важных для описания состояния объекта, например:

  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    properties.add(DiagnosticsNode.message('This is a clock renderobject'));
    properties.add(DiagnosticsProperty('hour', _hour));
    properties.add(DiagnosticsProperty('minute', _minute));
    properties.add(DiagnosticsProperty('offset', _offset));
  }

Полученные значения в debugFillProperties используются при выводе RenderObject в DevTools или при вызове describeForError , который используется в стеке ошибки, связанном с некорректным поведением или разметкой в RenderObject.

Также список свойств можно получить через явный вызов toDiagnosticsNode().getProperties().

image_7d715b5f6c.webp

Кроме того, для отладки области отрисовки могут использоваться debug-флаги:

Поле

Описание

debugPaintSizeEnabled

показывать границы измеренных областей (с учётом полученных от RenderObject размеров)

debugPaintBaselinesEnabled

построить базовую линию (нижняя граница для текстовых виджетов, за исключением символов с «хвостиками»)

debugPaintLayerBordersEnabled

включить вокруг каждого слоя рамки для визуализации его границ

debugPaintPointersEnabled

подсвечивать RenderObject при возникновении события касания и получения от hitTest значения true (реализовано не во всех RenderObject, поддерживается в методе debugHandleEvent)

debugRepaintRainbowEnabled

изменять цвет рамки при каждом вызове paint от RenderObject

debugRepaintTextRainbowEnabled

изменять цвет текста при каждой перерисовке

debugPrintMarkNeedsLayoutStacks

отображать стек вызовов для каждого обращения к markNeedsLayout

debugPrintMarkNeedsPaintStacks

отображать стек вызовов для обращений к markNeedsPaint

debugProfileLayoutsEnabled

добавлять метки для вызова performLayout на линию времени в DevTools

debugProfilePaintsEnabled

добавлять метки для каждого обращения к paint на линию времени в DevTools

debugEnhanceLayoutTimelineArguments, debugEnhancePaintTimelineArguments

расширять информацию о событии вызова performLayout/paint с использованием диагностической информации из debugFillDiagnostics()

debugOnProfilePaint

определить функцию для вызова при каждой отрисовке RenderObject (принимает его как аргумент)

Также есть несколько флагов для отключения различных типов слоёв:

  • debugDisableClipLayers — отключить слои обрезки (Rect, RRect, Path);
  • debugDisablePhysicalShapeLayers — отключить создание слоёв PhysicalShape (поверхность Material с тенью);
  • debugDisableOpacityLayers — отключить создание слоёв с полупрозрачностью (для проверки их влияния на производительность).

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

  • debugDumpRenderTree() — отобразить дерево RenderObject (начиная с RenderView);
  • debugDumpSemanticsTree() — вывести дерево SemanticsNode (используется подсистемой accessibility);
  • debugDumpLayerTree() — показывать дерево слоёв (с указанием типа и характеристик слоя, границ в координатах экрана, а также связи с деревом виджетов);
  • debugDumpApp() — вывести дерево виджетов и связанных с ними RenderObject (как в DevTools, но в виде строки в консоли).

На этом с часами всё — мы создали, декорировали и анимировали наш виджет — а ещё сделали так, чтобы им было удобно пользоваться людям с ограниченными возможностями.

Дальше мы рассмотрим оставшиеся нюансы RenderObject, но уже на других примерах.

Предыдущая
3.11. CustomPainter: шейдеры
Следующая
3.13. RenderObject: продвинутые концепции