dependencies:
flutter_html: ^3.0.0-alpha.5
// Or flutter_html_all: ^3.0.0-alpha.5 to include table, video, audio, iframe...
Currently Supported HTML Tags:
a
abbr
acronym
address
article
aside
audio
b
bdi
bdo
big
blockquote
body
br
caption
cite
code
data
dd
del
details
dfn
div
dl
dt
em
figcaption
figure
footer
font
h1
h2
h3
h4
h5
h6
header
hr
i
iframe
img
ins
kbd
li
main
mark
nav
noscript
ol
p
pre
q
rp
rt
ruby
s
samp
section
small
span
strike
strong
sub
sup
summary
svg
table
tbody
td
template
tfoot
th
thead
time
tr
tt
u
ul
var
video
math:
mrow
msup
msub
mover
munder
msubsup
moverunder
mfrac
mlongdiv
msqrt
mroot
mi
mn
mo
Currently Supported CSS Attributes:
background-color
color
direction
display
font-family
font-feature-settings
font-size
font-style
font-weight
height
letter-spacing
line-height
list-style-type
list-style-position
padding
margin
text-align
text-decoration
text-decoration-color
text-decoration-style
text-decoration-thickness
text-shadow
vertical-align
white-space
width
word-spacing
Currently Supported Inline CSS Attributes:
background-color
border (including specific directions)
color
direction
display
font-family
font-feature-settings
font-size
font-style
font-weight
line-height
list-style-type
list-style-position
padding (including specific directions)
margin (including specific directions)
text-align
text-decoration
text-decoration-color
text-decoration-style
text-shadow
Don't see a tag or attribute you need? File a feature request or contribute to the project!
Why this package?
This package is designed with simplicity in mind. Originally created to allow basic rendering of HTML content into the Flutter widget tree,
this project has expanded to include support for basic styling as well!
If you need something more robust and customizable, the package also provides a number of optional custom APIs for extremely granular control over widget rendering!
Below, you will find brief descriptions of the parameters theHtml widget accepts and some code snippets to help you use this package.
Constructors:
The package currently has two different constructors - Html() and Html.fromDom().
The Html() constructor is for those who would like to directly pass HTML from the source to the package to be rendered.
If you would like to modify or sanitize the HTML before rendering it, then Html.fromDom() is for you - you can convert the HTML string to a Document and use its methods to modify the HTML as you wish. Then, you can directly pass the modified Document to the package. This eliminates the need to parse the modified Document back to a string, pass to Html(), and convert back to a Document, thus cutting down on load times.
Selectable Text
The package also has two constructors for selectable text support - SelectableHtml() and SelectableHtml.fromDom().
The difference between the two is the same as noted above.
Please note: Due to Flutter #38474, selectable text support is significantly watered down compared to the standard non-selectable version of the widget. The changes are as follows:
The list of tags that can be rendered is significantly reduced. Key omissions include no support for images/video/audio, table, and ul/ol.
No support for customRender, customImageRender, onImageError, onImageTap, onMathError, and navigationDelegateForIframe. (Support for customRender may be added in the future).
Styling support is significantly reduced. Only text-related styling works (e.g. bold or italic), while container related styling (e.g. borders or padding/margin) do not work.
Once the above issue is resolved, the aforementioned compromises will go away. Currently the SelectableText.rich() constructor does not support WidgetSpans, resulting in the feature losses above.
Parameters:
Parameters
Description
data
The HTML data passed to the Html widget. This is required and cannot be null when using Html().
document
The DOM document passed to the Html widget. This is required and cannot be null when using Html.fromDom().
onLinkTap
A function that defines what the widget should do when a link is tapped. The function exposes the src of the link as a String to use in your implementation.
customRenders
A powerful API that allows you to customize everything when rendering a specific HTML tag.
onImageError
A function that defines what the widget should do when an image fails to load. The function exposes the exception Object and StackTrace to use in your implementation.
shrinkWrap
A bool used while rendering different widgets to specify whether they should be shrink-wrapped or not, like ContainerSpan
onImageTap
A function that defines what the widget should do when an image is tapped. The function exposes the src of the image as a String to use in your implementation.
tagsList
A list of elements the Html widget should render. The list should contain the tags of the HTML elements you wish to include.
style
A powerful API that allows you to customize the style that should be used when rendering a specific HTMl tag.
selectionControls
A custom text selection controls that allow you to override default toolbar and build toolbar with custom text selection options. See an example.
Methods:
Methods
Description
disposeAll()
Disposes all ChewieControllers, ChewieAudioControllers, and VideoPlayerControllers being used by every Html widget. (Note: Html widgets automatically dispose their controllers, this method is only provided in case you need other behavior)
Getters:
Html.tags. This provides a list of all the tags the package renders. The main use case is to assist in excluding elements using tagsList. See an example below.
SelectableHtml.tags. This provides a list of all the tags that can be rendered in selectable mode.
Html.chewieAudioControllers. This provides a list of all ChewieAudioControllers being used by Html widgets.
Html.chewieControllers. This provides a list of all ChewieControllers being used by Html widgets.
Html.videoPlayerControllers. This provides a list of all VideoPlayerControllers being used for video widgets by Html widgets.
Html.audioPlayerControllers. This provides a list of all VideoPlayerControllers being used for audio widgets by Html widgets.
Data:
The HTML data passed to the Html widget as a String. This is required and cannot be null when using Html.
Any HTML tags in the String that are not supported by the package will not be rendered.
Example Usage - Data:
Widget html =Html(
data:"""<div> <h1>Demo Page</h1> <p>This is a fantastic product that you should buy!</p> <h3>Features</h3> <ul> <li>It actually works</li> <li>It exists</li> <li>It doesn't cost much!</li> </ul> <!--You can pretty much put any html in here!--> </div>""",
);
Document:
The DOM document passed to the Html widget as a Document. This is required and cannot be null when using Html.fromDom().
Any HTML tags in the document that are not supported by the package will not be rendered.
Using the Html.fromDom() constructor can be useful when you would like to sanitize the HTML string yourself before passing it to the package.
Example Usage - Document:
import'package:html/parser.dart'as htmlparser;
import'package:html/dom.dart'as dom;
...
String htmlData ="""<div> <h1>Demo Page</h1> <p>This is a fantastic product that you should buy!</p> <h3>Features</h3> <ul> <li>It actually works</li> <li>It exists</li> <li>It doesn't cost much!</li> </ul> <!--You can pretty much put any html in here!--></div>""";
dom.Document document = htmlparser.parse(htmlData);
/// sanitize or query document hereWidget html =Html(
document: document,
);
onLinkTap:
A function that defines what the widget should do when a link is tapped.
Example Usage - onLinkTap:
Widget html =Html(
data:"""<p> Linking to <a href='https://github.com'>websites</a> has never been easier. </p>""",
onLinkTap: (String? url, RenderContext context, Map<String, String> attributes, dom.Element? element) {
//open URL in webview, or launch URL in browser, or any other logic here
}
);
Inner links (such as <a href="#top">Back to the top</a> will work out of the box by scrolling the viewport, as long as your Html widget is wrapped in a scroll container such as a SingleChildScrollView.
customRenders:
A powerful API that allows you to customize everything when rendering a specific HTML tag. This means you can change the default behaviour or add support for HTML elements that aren't supported natively. You can also make up your own custom tags in your HTML!
customRender accepts a Map<CustomRenderMatcher, CustomRender>.
CustomRenderMatcher is a function that requires a bool to be returned. It exposes the RenderContext which provides BuildContext and access to the HTML tree.
The CustomRender class has two constructors: CustomRender.widget() and CustomRender.inlineSpan(). Both require a <Widget/InlineSpan> Function(RenderContext, Function()). The Function() argument is a function that will provide you with the element's children when needed.
To use this API, create a matching function and an instance of CustomRender.
Example Usages - customRenders:
Note: If you add any custom tags, you must add these tags to the tagsList parameter, otherwise they will not be rendered. See below for an example.
请发表评论