universal_html 1.0.2

Supports a subset of 'dart:html' in all platforms (browser, VM, and Flutter).

Introduction

This package implements dart:html in all platforms (Flutter, VM, Node.JS, browser, etc.).

In browser, 'package:universal_html' exports 'dart:html'. In other words, using the package has almost no downsides. Your dart2js build sizes won't grow.

The project is licensed under the MIT license.

Issues?

• Please report issues at the Github issue tracker.
• Have a fix? Just create a pull request in Github.
  • Frequent contributors will be invited to become project administrators.

Similar projects

• universal_io (cross-platform implementation of dart:io)
• jsdom (DOM implementation in Javascript).

Getting started

In pubspec.yaml:

name: example
dependencies:
  universal_html: ^1.0.0

Now you can replace usage of "dart:html" with "package:universal_html/html.dart".

import "package:universal_html/html.dart";

void main() {
  // Create a DOM tree
  final divElement = new DivElement();
  divElement.append(new Element.tag("h1")
    ..classes.add("greeting")
    ..appendText("Hello world!"));

  // Print outer HTML
  print(divElement.outerHtml);
  // --> <div><h1>Hello world</h1></div>

  // Do a CSS query
  print(divElement.querySelector("div > .greeting").text);
  // --> Hello world
}

Controlling "browser instance"

• Library "package:universal_html/driver.dart" lets you control the "browser instance".
• You can manipulate global variables like document, navigator and window:
  • Want to have zone-local values? Use HtmlIsolate.zoneLocal.
  • Want to reset the values to defaults (after a test)? Use HtmlIsolate.current.setDocument(null).

Example

import 'package:universal_html/driver.dart';
import 'package:universal_html/html.dart';

main() async {
  // Construct a driver
  final driver = new HtmlDriver(userAgent:"My scraper");
  
  // Load a document.
  // Content type will be determined using HTTP headers or content sniffing.
  await driver.setDocumentFromUri(Uri.parse("https://example.com/"));
  
  // Set as default instance
  HtmlDriver.zoneLocal.freezeDefault(driver);
  
  // Print some node
  print(querySelector(".results:first").text);
}

Implemented APIs

Principles

• Our goal is that the implemented APIs behave identically to dart:html code running in Chrome.
• Non-implemented APIs either throw UnimplementedError or fail silently.
• We accept pull requests for more API implementations!

Incomplete list of implemented APIs

• Document nodes
  • All the core classes (Node, Element, etc.)
  • Much of the element subclasses (CheckboxInputElement, ResetButtonElement, etc.)
  • Much of the CSS classes (CssStyleDeclaration, etc.)
• DOM parsing
  • DomParser, innerHtml/outerHtml setters
  • Uses package:html and package:csslib
• DOM printing
  • element.innerHtml
  • element.outerHtml
• DOM events
  • For example, element.onClick.listen(...) would receive invocation of element.click().
• CSS selectors
  • Methods element.querySelector(..), element.querySelectorAll(..), element.matchesSelector(..)
  • Element name (table)
  • Element ID (#id)
  • Element class (.classA.classB)
  • Combinators:
    • element.class#id
    • s0 s1 s2
    • s0 s1 s2
    • s0 > s1 > s2
    • s0 ~ s1 ~ s2
    • s0 + s1 + s2
  • Pseudoselectors:
    • :disabled
    • :first-child
    • :last-child
    • :not(x)
    • :nth-child(5)
    • :nth-child(even)
    • :nth-child(3n+1)
    • :only-child
    • :root
  • Attribute selectors:
    • [name]
    • [name=value]
    • [name~=value]
    • [name|=value]
    • [name^=value]
    • [name$=value]
    • [name*=value]
• Navigator
  • locale, userAgent, etc.
• Window
  • console
  • history
    • back(...), pushState(...), etc.
  • location
    • origin, href, etc.
  • localStorage / sessionStorage
    • Stores values in the heap.
• HttpRequest
  • Does not implement same-origin security policies that browsers have.
• Related libraries (dart:js, dart:svg, etc.).
  • Just API declarations. Any attempt to use APIs will throw UnimplementedException.
  • Available in:
    • "package:universal_html/indexed_db.dart"
    • "package:universal_html/js.dart"
    • "package:universal_html/js_util.dart"
    • "package:universal_html/svg.dart"