extractAnnotations method

Extracts all annotations from one or all pages of the document.

When pageIndex is null, the stream yields one PdfPageAnnotations per page in index order. Pages with no annotations emit an entry with an empty PdfPageAnnotations.annotations list, so callers can track page coverage without gaps.

When pageIndex is specified, the stream yields exactly one PdfPageAnnotations for that page.

Throws RangeError if pageIndex is out of range. Throws StateError if the document has been closed before or during extraction.

close terminates any active stream: the stream stops emitting events and all page-level annotation handles are released. Callers do not need to cancel streams manually before calling close.

Note: This method does not accept a page range — only a single optional page index. Range-based extraction is a known limitation to revisit in a future plan.

Platform support: Native (dart:ffi) only. Stubs on unsupported platforms throw UnsupportedError immediately.

Example — collect all highlights from every page:

await for (final page in doc.extractAnnotations()) {
  for (final annot in page.annotations) {
    if (annot case PdfMarkupAnnotation(:final subtype, :final quadPoints)
        when subtype == PdfAnnotationType.highlight) {
      print('Highlight on page ${page.pageIndex}: $quadPoints');
    }
  }
}