[QGIS-Developer] Grant report: Restore the print layout HTML item for QGIS 4
Nyall Dawson
nyall.dawson at gmail.com
Thu Nov 12 20:34:50 PST 2026
Hi PSC,
I'm happy to report that following the grant "Restore the print layout
HTML item for QGIS 4"
(https://github.com/qgis/QGIS-Enhancement-Proposals/pull/377), the
print layout HTML item has now been resurrected for QGIS 4.4!
This was a heavy undertaking, involving many different parts. The
upstream removal of the QtWebkit support and replacement by the
less-featured (but more modern and secure) webengine framework
completely removed the API we were relying on for rendering the HTML
print layout item.
No direct replacement API was available for rendering webengine
content in high quality, vector formats. To work around this, I've
implemented a complicated approach that uses webengine's print
capabilities to export vectorised HTML content to a PDF file, and then
the PDF4QT library to render this into the layout HTML item.
Via this approach I've been able to resurrect almost all the
functionality that the item had under QGIS 3, including support for
user stylesheets, and injection of atlas feature json into the HTML.
Additionally, I took the opportunity to fix a long-standing
performance issue relating to the HTML item. In QGIS 3, the HTML
content would always be loaded and rendered immediately, in the main
thread, when creating the item. This also occurred whenever a QGIS
project was loaded that contained a HTML item, resulting in very slow
load times for these projects! Furthermore, all the HTML rendering was
always done on the GUI thread, so navigating and interacting with
layouts containing HTML content was slow and would result in many QGIS
pauses.
Now, all the loading and rendering is done asynchronously. The HTML
fetching and rendering will only happen when required (no longer at
project load time!), and now happens in a background thread so that
the layout designer always remains responsive to work with.
That said, there remains some regressions which users should be aware
of when compared with the HTML item support in QGIS 3:
- The webengine backend uses its own independent networking library,
which is not integrated in any way with the networking library used by
the rest of QGIS. Accordingly, the HTML item will ignore the proxy,
SSL, cache, user agent, authentication and other QGIS network
settings. Requests won't be shown in the QGIS Network logger panel
either. QGIS administrators will need to be aware of this and adjust
their network's firewall settings accordingly.
- While the HTML content is always rendered as high-quality vectors,
text from the HTML will always be converted to paths. This looks
identical, but means that text from the HTML item in PDF or SVG
exported layouts won't be selectable, searchable, or editable. (It's
possible that this limitation may be fixable in follow-up work)
- HTML content will render slightly larger than in QGIS 3 (around 10%
larger). This is a feature, not a bug! The original webkit library
incorrectly sized the HTML content, as reported in
https://github.com/qgis/QGIS/issues/19901. Now, the font and css sizes
from the HTML content will be an exact match for font and other sizes
for non-HTML layout items. Users may need to adjust their HTML or CSS
to adjust for this sizing difference when loading older projects into
QGIS 4.
Thanks to the QGIS project and all donors for funding this work and
restoring this valuable capability!
(The final part of this work is currently waiting review at
https://github.com/qgis/QGIS/pull/68161)
Nyall
More information about the QGIS-Developer
mailing list