p-hatan/ mirror

pub repository

mirror.p-hatan.ir

web

0.5.1

Lightweight browser API bindings built around JS static interop.

Download archive

Readme

Dart CI pub package package publisher

Lightweight browser API bindings built around JS static interop.

What's this?

This package exposes browser APIs. It's generated from the Web IDL definitions and uses recent Dart language features for zero-overhead bindings.

This package is intended to replace dart:html and similar Dart SDK libraries. It will support access to browser APIs from Dart code compiled to either JavaScript or WebAssembly.

Usage

import 'package:web/web.dart';

void main() {
  final div = document.querySelector('div')!;
  div.text = 'Text set at ${DateTime.now()}';
}

Migrating to package:web

package:web is replacing dart:html and other web libraries as Dart's long-term web interop solution. To learn how to migrate from dart:html APIs to package:web, see our migration guide.

Generation conventions

The generator scripts use a number of conventions to consistently handle Web IDL definitions:

Interfaces

  • Interfaces are emitted as extension types that wrap and implement JSObject.
  • Interface inheritance is maintained using implements between extension types.
  • Members of partial interfaces, partial mixins, and mixins are added to the interfaces that include them, and therefore do not have separate declarations.

Types

  • Generic types include the generic in the case of JSArray and JSPromise.
  • Enums are typedef'd to String.
  • Callbacks and callback interfaces are typedef'd to JSFunction.
  • In general, we prefer the Dart primitive over the JS type equivalent wherever possible. For example, APIs use String instead of JSString.
  • If a type appears in a generic position and it was typedef'd to a Dart primitive type, it is replaced with the JS type equivalent to respect the type bound of JSAny?.
  • Union types are computed by picking the least upper bound of the types in the JS type hierarchy, where every interface is equivalent to JSObject.

Compatibility

  • The generator uses the MDN compatibility data to determine what members and interfaces to emit. Currently, we only emit code that is standards track and supported on Chrome, Firefox, and Safari to reduce the number of breaking changes. This is currently WIP and some members may be added or removed.

Generation and updating the package

Most of the APIs in this package are generated from public assets. See tool/README.md for information on the spec and IDL versions the package was generated from, and for the process for updating the package.

Changelog

0.5.1

  • Add TrustedTypes members.
  • Include MDN API documentation as class and member dartdoc comments. Docs sourced from the MDN Web Docs project; attributions and copyright licensing by Mozilla Contributors is licensed under CC-BY-SA 2.5.
  • Add a constructor for each Element tag onto their respective Element interfaces.
  • Remove external Element constructors that would result in a runtime error.
  • Deprecate createAudioElement in favor of the HTMLAudioElement constructor.

0.5.0

  • Redeprecate APIs that were deprecated in 0.4.1 but undeprecated in 0.4.2.

  • Add support for dart fix migrations from dart:html classes to package:web classes.

  • Contribute a markdown file for the renamed classes from dart:html to package:web (see renames.md).

  • Migrate classes to use interop extension types that implement JSObject.

  • Add generics to APIs that use JSArray and JSPromise. Typedefs of a Dart primitive type are instead replaced with their JS type equivalent if they appear as a type parameter in order to conform with the type bounds of JSArray and JSPromise.

  • Changed record types to be JSObject instead of JSAny.

  • Reduce the number of DOM APIs we generate code for. Currently, the API needs to be standards-track, and be supported by Safari, Chrome, and Firefox.

  • Updated the source IDL version to 3.43.1.

  • Deprecate a few type aliases in favor of their standardized versions:

    Deprecated Preferred
    AudioElement HTMLAudioElement
    HtmlElement HTMLElement
    CanvasElement HTMLCanvasElement
    ImageElement HTMLImageElement
    VideoElement HTMLVideoElement
    CssStyleDeclaration CSSStyleDeclaration
    ContextEvent WebGLContextEvent
    WebGL WebGLRenderingContext

  • Deprecate the top-level createElementTag, createCanvasElement, createIFrameElement, and querySelector functions. Instead, use the standard creation and query methods on document.

  • Deprecate the client extension methods on MouseEvent and Touch. Instead, directly use the clientX and clientY properties.

  • Deprecate the HttpRequest API borrowed from dart:html. Consider migrating to package:http instead.

0.4.2

  • Undeprecate some APIs and helpers library that were deprecated in 0.4.1. Because deprecations are breaking in Flutter, they should be done in a breaking change.

0.4.1

  • Exported the helper libraries from web.dart.
  • Deprecated the helpers.dart library in favor of web.dart.
  • Updated the readme to include usage info and package status.
  • Added an example.
  • Added event extensions for WebSocket
  • Fixes to the return types of the append() and clone() extension methods on Node.
  • Deprecated NodeGlue.append in favor of Node.appendChild.
  • Deprecated NodeGlue.clone in favor of Node.cloneNode.
  • Updated @webref/css to 6.10.0.

0.4.0

  • Remove implements JSObject from all types. This is needed to move the JS types exposed in dart:js_interop to extension types. This subtyping will be added back in a future version when we move all package:web types to extension types.
  • Add onMessage getter to WindowEventGetters extension methods.
  • helpers.dart: expose the EventStreamProviders class.
  • Add createIFrameElement method to helpers.dart.
  • Updated types to account for union types.
  • Fixed issue where all JSAnys were treated as nullable.
  • Changed JSVoid to void.
  • interface mixins are no longer emitted as interfaces. Their members are instead added to the interface that mixes them in.

0.3.0

  • Updated source IDL to v3.39.1.
  • Fixed a bug where typedefs were not declared with the IDL type's nullability.
  • Types that were aliased to double are now aliased to num. This is to make it easier for users to pass integer values without going through a cast and to make migration from dart:html easier.

0.2.2-beta

  • Updates SDK version minimum to 3.2.0-194.0.dev.
  • Removes isInstanceOfDomType as dart:js_interop now exposes instanceOfString.

0.2.1-beta

  • helpers.dart
    • Expose EventStreamProvider

0.2.0-beta

  • Added helpers.dart top-level library.
  • Require Dart 3.2 pre-release.
  • Update to IDL 3.38.2

0.1.4-beta

  • Support bool, int, double, String in APIs.

0.1.3-beta

  • CSS properties can now be accessed directly.

0.1.2-beta

  • JSAny as an IDL type now includes null.

0.1.1-beta

  • Objects now inherit from JSObject.

0.1.0-beta

  • First release.

Installing

export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add web
pubspec.yaml
name: web
version: 0.5.1
description: Lightweight browser API bindings built around JS static interop.
repository: https://github.com/dart-lang/web

environment:
  sdk: ^3.3.0

dev_dependencies:
  analyzer: ^6.3.0
  args: ^2.4.0
  build_runner: ^2.4.0
  build_web_compilers: ^4.0.7
  code_builder: ^4.10.0
  collection: ^1.18.0
  dart_flutter_team_lints: ^2.0.0
  dart_style: ^2.3.4
  io: ^1.0.4
  path: ^1.8.3
  test: ^1.22.2

Version history

VersionPublishedArchiveSHA-256
0.0.12015-07-31T00:10:03.379ZDownloaded511c92013b89f55926e92cbf5a33e2a47e1d2226925d48d8aed78f7b8fa209
0.1.0-beta2023-05-02T17:10:36.390652ZDownload4682cbe455e394c8dcacf1c1e53917eeea446737884ce0983e738a7e2f446761
0.1.1-beta2023-05-15T19:38:58.731494ZDownloadad8dae821733dd5b425cd98d707084956c9bfece337c8374e17072c6e54af5a7
0.1.2-beta2023-05-15T22:28:04.455621ZDownloadabf85421e1f06c6bb2fe6d81b544e0c1c86437aa4e2fab57153ff6829a8d084d
0.1.3-beta2023-05-22T17:34:48.550847ZDownload47e396fadea4d65295c81f06f482c8bf6bc804f46f8caf11df160806c4a53785
0.1.4-beta2023-06-14T17:43:18.439747ZDownloaddc8ccd225a2005c1be616fe02951e2e342092edf968cf0844220383757ef8f10
0.2.0-beta2023-09-19T18:03:28.888791ZDownload6106a51fd43fe8f82749994ec6f4f8a18025c2bff3651170bebf1f63d420bebc
0.2.1-beta2023-09-19T23:14:49.313295ZDownload14f1f70c51119012600c5f1f60ca68efda5a9b6077748163c6af2893ec5df8fc
0.2.2-beta2023-09-27T21:13:00.893497ZDownloadccbbfbf29732ee1b391c4c6d13e7032d851f675f47365e81904e4c6fd669c854
0.3.02023-10-11T21:50:44.833239ZDownloadafe077240a270dcfd2aafe77602b4113645af95d0ad31128cc02bce5ac5d5152
0.3.1-dev2023-11-10T23:33:09.415823ZDownload03ce602c4639f0b483d22fdfc2dab35d2766912fa76dc2ebe82a8e8fd952dfe0
0.4.02023-11-14T20:19:48.904397ZDownloadedc8a9573dd8c5a83a183dae1af2b6fd4131377404706ca4e5420474784906fa
0.4.12024-01-11T19:52:10.711418ZDownloada4fcead029d8cbde2df1674cdc4585640a28bddd1e46878b9ceebeaf9d7a5913
0.4.22024-01-12T01:31:50.952455ZDownload4188706108906f002b3a293509234588823c8c979dc83304e229ff400c996b05
0.5.02024-02-13T20:25:54.210715ZDownload1d9158c616048c38f712a6646e317a3426da10e884447626167240d45209cbad
0.5.12024-03-05T19:22:22.757953ZDownload97da13628db363c635202ad97068d47c5b8aa555808e7a9411963c533b449b27
1.0.02024-07-16T01:34:24.237084ZDownloadd43c1d6b787bf0afad444700ae7f4db8827f701bc61c255ac8d328c6f4d52062
1.1.02024-09-24T22:36:58.026862ZDownloadcd3543bd5798f6ad290ea73d210f423502e71900302dde696f8bff84bf89a1cb
1.1.12025-02-26T21:23:27.138850ZDownload868d88a33d8a87b18ffc05f9f030ba328ffefba92d6c127917a2ba740f9cfe4a
1.1.22026-10-23T00:25:24.742112ZDownloade119e82ac4795c7925103b7cf3768191f33941b99e7ccffbd6c645201d9f606b

Dependencies

No direct dependencies declared.