flutter_hypertext 0.0.1+10

A highly extensible rich text widget that can automatically parse styles.

Language: English | 中文

Hypertext is a highly extensible rich text widget that automatically parses styles.

Preview

View online demo

EN	ZH

Features

1. Built-in support for common HTML-like tags, such as:

   • Links (with tap and long-press events)
   • Images
   • Text styles: italic, bold, strikethrough, underline, text color, gradients, etc.
   • ...

2. Event handling support

3. Custom markup support

4. Customizable color name mapping to easily support multi-theme scenarios

5. Text style inheritance for WidgetSpan's inner child

Table of contents

• Preview
• Features
• Table of contents
• Getting Started
  • Supported Parameters
  • Custom Markups
• Use Cases
• Predefined Markup Tags
  • 1) LinkMarkup
  • 2) StyleMarkup
    • 1. FontWeightMarkup
    • 2. BoldMarkup
    • 3. FontStyleMarkup
    • 4. ItalicMarkup
    • 5. TextDecorationMarkup
    • 6. DelMarkup
    • 7. UnderlineMarkup
    • 8. ColorMarkup
    • 9. SizeMarkup
  • 4) GradientMarkup
  • 5) ImageMarkup
  • 6) GapMarkup
  • 7) PaddingMarkup
• 6) PatternMarkup
• Special Notes
  • Color Names
  • Hex Colors
  • Margin Values
• Things to Keep in Mind
• TODO

Getting Started

dependencies:
  flutter_hypertext: ^0.0.1+10

import 'package:flutter_hypertext/markup.dart';

Hypertext("Hello <color=red>Hypertext</color>")

Supported Parameters

Parameter	Default	Description
onMarkupEvent		Receive events like a
lowercaseAttrName	true	Convert attribute names to lowercase
lowercaseElementName	true	Convert element names to lowercase
ignoreErrorMarkup	false	Ignore erroneous tags
colorMapper	kBasicCSSColors	Color name mapping (default is CSS basic colors)
markups	kDefaultMarkups	Supported markup tags

Global default configuration can be set via HypertextThemeExtension

Custom Markups

Defining a Custom Markup:

class CustomMarkup extends TagMarkup {
  const CustomMarkup() : super('your-tag');

  @override
  HypertextSpan onMarkup(List<HypertextSpan>? children, MarkupContext ctx) {
    return HypertextTextSpan(children: children, style: TextStyle());
    return HypertextWidgetSpan(child: child);
  }
}

Setting Custom Markup:

Hypertext(
    text,
    markups: [...kDefaultMarkups, CustomMarkup()],
)

Or

ThemeData(
  extensions: [HypertextThemeExtension(markups: [...kDefaultMarkups, CustomMarkup()])],
)

Use Cases

1. Rich text in multiple languages
2. Rich text with multiple themes
3. Highlighting keywords (search, mentions, topics...)

Predefined Markup Tags

1) LinkMarkup

Marks a range as a hyperlink, specifically for adding click events.

Tag Name: a

Parameters:

Parameter	Value	Required	Description
href	URI string	✅	URI
tap	-	☑️	Handle click (can also specify long-press)
long-press	-	☑️	Handle long press (can also specify tap)
title	String	☑️	Tooltip content
cursor	basic click text defer...	☑️	See [SystemMouseCursors]
alignment	baseline middle top bottom...	☑️	See [PlaceholderAlignment]
baseline	alphabetic ideographic	☑️	See [TextBaseline]

Example:

<a href="https://example.com">go</a>
<a href="app://op" custom-attr=foo title="User Foo" long-press tap>foo</a> <!-- Supports both tap and long-press -->

Hypertext(
    text,
    onMarkupEvent: (MarkupEvent event){
      // event.tag
      // event.data
    },
);

2) StyleMarkup

Sets text styles for a specified range, such as text color, background color, font size, font family, font weight, italic, text decorations (underline, overline, strikethrough)...

Tag: style

Parameters:

Parameter	Value	Required	Description
color	Hex Color or Color Name	☑️	Text color, default supports CSS Basic Colors[kBasicCSSColors]
background	Hex Color or Color Name	☑️	Text background color
size	double	☑️	Text size
font-family	font family name	☑️	Font family
weight	100~900、bold、normal	☑️	See [FontWeight]
font-style	normal italic	☑️	Font style [FontStyle]
decor	none underline overline lineThrough	☑️	Text decoration [TextDecoration]
decor-style	double dashed dotted solid wavy	☑️	Decoration style [TextDecorationStyle]
decor-color	Hex Color or Color Name	☑️	Decoration color
thickness	double	☑️	Decoration line thickness

Example:

<style color=red background=white size=20 weight=900>hypertext</style>
<style decor=underline decor-color=#F00 thickness=2>hypertext</style>

StyleMarkup is a superset of the following tags:

1. FontWeightMarkup

Tag: weight

Parameter	Value	Required	Description
weight (simplify)	100~900、bold、normal	✅️	See [FontWeight]

Example:

<weight=500>foo</weight>
<weight weight=100>bar</weight>

2. BoldMarkup

Tags: b bold strong

Parameter	Value	Required	Description
weight (simplify)	100~900、bold、normal	✅️	See [FontWeight]

<b>Hypertext</b>
<bold=900>Hypertext</bold>
<strong weight=100>Hypertext</strong>

3. FontStyleMarkup

Tag: font-style

Parameter	Value	Required	Description
font-style (simplify)	normal italic	✅	See [FontWeight]

Example:

<font-style=italic>foo</font-style>
<font-style font-style=normal>bar</font-style>

4. ItalicMarkup

Tag: i

Example:

<i>bar</i>

5. TextDecorationMarkup

Tag: text-decor

Parameter	Value	Required	Description
decor (simplify)	none underline overline lineThrough	✅	Text decoration [TextDecoration]
style	double dashed dotted solid wavy	☑️	Decoration style [TextDecorationStyle]
color	Hex Color or Color Name	☑️	Decoration color
thickness	double	☑️	Decoration line thickness

Example:

<text-decor=underline style=dotted>foo</text-decor>
<text-decor decor=lineThrough color=red thickness=2>bar</text-decor>

6. DelMarkup

Tag: del

Parameter	Value	Required	Description
style	double dashed dotted solid wavy	☑️	Decoration style [TextDecorationStyle]
color	Hex Color or Color Name	☑️	Decoration color
thickness	double	☑️	Decoration line thickness

Example:

<del color=red>bar</del>

7. UnderlineMarkup

Tag: u ins

Parameter	Value	Required	Description
style	double dashed dotted solid wavy	☑️	Decoration style [TextDecorationStyle]
color	Hex Color or Color Name	☑️	Decoration color
thickness	double	☑️	Decoration line thickness

Example:

<u style=wavy>bar</u>

8. ColorMarkup

Tag: color

Parameters:

Parameter	Value	Required	Description
color (simplify)	Hex Color or Color Name	✅	Text color

Example:

<color=red>bar</color>
<color color=#FF0>bar</color>

9. SizeMarkup

Tag: size

Parameters:

Parameter	Value	Required	Description
size (simplify)	double	✅	Text size

Example:

<size=red>bar</size>
<size color=#FF0>bar</size>

4) GradientMarkup

Sets a linear gradient for the specified range of text.

Tag: gradient

Parameters:

Parameter	Value	Required	Description
colors	Hex Color or Color Name	✅	Gradient colors
stops	List	☑️	Values between 0.0 and 1.0 for gradient stops [LinearGradient]
rotation	Angle (0~360)	☑️	Rotation angle for gradient
tile-mode	clamp (default) repeated mirror decal	☑️	Tiling mode
alignment	baseline middle top bottom...	☑️	See [PlaceholderAlignment]
baseline	alphabetic ideographic	☑️	See [TextBaseline]

Example:

<gradient colors="red, green" rotation=45>bar</gradient>
<gradient colors="#F00,#00F" rotation=45>bar</gradient>

5) ImageMarkup

Add image, support custom parsing src and creating image widgets through imageBuilder.

[Note] The default implementation of network image is NetworkImage, which does not support disk caching. If necessary, please use ImageMarkup.imagebuilder.

Tag: img image

Parameters:

Parameter	Value	Required	Description
src	URI string	✅	Image path (supports http[s]://, asset://, path)
size	List<double>	☑️	Image width and height (1~2 values)
width	double	☑️	Image width
height	double	☑️	Image height
fit	fill contain cover fitWidth fitHeight none scaleDown	☑️	BoxFit modes
align	topLeft center bottomLeft...	☑️	Alignment options
alignment	baseline middle top bottom...	☑️	See [PlaceholderAlignment]
baseline	alphabetic ideographic	☑️	See [TextBaseline]

Example:

<img src="https://example.com/avatar.png" size=50 fit=cover/>
<img src="asset://images/icon.png" size="50,100"/>
<img src="path/to/icon.png" width="50" height="50"/> <!--File path-->

6) GapMarkup

Adds space gaps.

Tag: gap

Parameters:

Parameter	Value	Required	Description
gap (simplify)	double	✅	Gap size

Example:

<gap=10 />
<gap gap="50"/>

7) PaddingMarkup

Adds padding inside an element.

Tag: padding

Parameters:

Parameter	Value	Required	Description
padding (simplify)	double	✅	Padding value (1~4 values)
hor	List<double>	☑️	Horizontal padding (1~2 values)
ver	List<double>	☑️	Vertical padding (1~2 values)
alignment	baseline middle top bottom...	☑️	See [PlaceholderAlignment]
baseline	alphabetic ideographic	☑️	See [TextBaseline]

Example:

<padding="10, 20">foo</padding> <!-- Set top/bottom padding to 10, left/right padding to 20 -->
<padding padding="50"/> <!-- Set all padding to 50 -->
<padding hor="10, 20"/> <!-- Set left padding to 10, right padding to 20 -->
<padding ver="20"/> <!-- Set vertical padding to 20 -->

6) PatternMarkup

A pattern-matching-based markup, used for recognizing and styling specific patterns such as user mentions (@foo), topics (#flutter), and email addresses ([e-mail]).

You can define custom pattern markups by extending PatternMarkup or DefaultPatternMarkup.

Public Constructor Parameters:

Parameter Name	Type	Required	Description
style	TextStyle	✅️	The text style to apply to the matched pattern.
pattern	String	✅️	The regular expression string used for pattern matching.
tag	String	✅️	The corresponding tag name in the lexical tree.
startCharacter	int	☑️	The starting matching character (used to reduce the number of regex matches).
enableLongPress	bool	☑️	Whether to enable the long-press event.
enableTap	bool	☑️	Whether to enable the tap (click) event.
cursor	MouseCursor	☑️	The mouse cursor style when hovering over the pattern.
tooltip	String	☑️	The tooltip text displayed on mouse hover.
alignment	PlaceholderAlignment	☑️	The alignment of the inline placeholder.
baseline	TextBaseline	☑️	The text baseline for the inline placeholder.

Predefined Pattern Markups:

Warning

Using pattern markups may result in slower performance compared to not using them. The default predefined markups are not automatically added to Hypertext and must be added manually (via Hypertext.markups or HypertextThemeExtension.markups).

Markup	Description	Usage Example
MentionMarkup	Mention Tag	@foo
EmailMarkup	Email Address Tag	[e-mail]
TopicMarkup	Topic Tag	#flutter

Special Notes

Color Names

By default, CSS Basic Colors[kBasicCSSColors] are supported. You can customize color name mappings via Hypertext.colorMapper and HypertextThemeExtension.colorMapper.

Hex Colors

Supports the following formats:

1. RGB, e.g., #0F0
2. RGBA, e.g., #0F0F
3. RRGGBB, e.g., #00FF00
4. RRGGBBAA, e.g., #00FF00FF

Margin Values

Supports the following formats:

1. 10 → left=10 top=10 right=10 bottom=10
2. 10, 20 → left=20 top=10 right=20 bottom=10
3. 10, 20, 30 → left=20 top=10 right=20 bottom=30
4. 10, 20, 30, 40 → left=10 top=20 right=30 bottom=40

Things to Keep in Mind

1. When customizing Markups, it is recommended to use HypertextTextSpan or HypertextWidgetSpan to help inherit styles from parent WidgetSpan for text within it.

TODO

• ☑️ Improve selectability: Add built-in selectability options and pass selectability to WidgetSpan.