MetricWidget API

MetricWidget()

Bases: BaseWidget

Metric component for displaying key data metrics.

MetricWidget is used to display important data metrics, including values, titles, trend changes, and other information. Suitable for dashboards, KPI displays, data monitoring, and other scenarios.

Attributes:

Name	Type	Description
metrics	List[Dict[str, Any]]	Metrics list
title	str	Metric group title
layout	str	Layout method (horizontal/vertical)
show_trend	bool	Whether to show trends

Examples:

Basic usage:

Python

metric = MetricWidget()
metric.add_metric("Total Users", "12,345", "people")
metric.add_metric("Monthly Active", "8,456", "people", "+15.6%", "success")
metric.add_metric("Conversion Rate", "3.2", "%", "-0.8%", "warning")

Using method chaining:

Python

metric = (MetricWidget()
    .set_title("Core Metrics")
    .add_metric("Sales", "¥1,250,000", "", "+12.3%", "success")
    .add_metric("Orders", "2,456", "units", "-3.2%", "error")
    .set_layout("horizontal"))

Multi-metric display:

Python

metric = MetricWidget()
metric.set_title("System Performance")
metric.add_metric("CPU Usage", "45.2", "%", "+2.1%", "warning")
metric.add_metric("Memory Usage", "78.5", "%", "-1.3%", "success")
metric.add_metric("Disk Space", "23.8", "GB", "+5.2GB", "info")

Initialize metric component.

Attributes

metrics property

获取所有指标。

Returns:

Type	Description
list[dict[str, Any]]	List[Dict[str, Any]]: 指标列表

title property

获取指标组标题。

Returns:

Name	Type	Description
str	str	指标组标题

metric_count property

获取指标总数。

Returns:

Name	Type	Description
int	int	指标总数

layout property

获取布局方式。

Returns:

Name	Type	Description
str	str	布局方式

Functions

add_metric(label, value, unit='', trend='', trend_type=None, description='')

添加指标。

Parameters:

Name	Type	Description	Default
label	str	指标标题	required
value	Union[str, int, float]	指标值	required
unit	str	单位，可选	''
trend	str	趋势变化，可选（如 "+12.3%", "-5.6%"）	''
trend_type	Union[str, StatusType, None]	趋势类型	None
description	str	描述信息，可选	''

Returns:

Name	Type	Description
MetricWidget	MetricWidget	返回self以支持链式调用

Examples:

Python

metric.add_metric("用户数", 12345, "人")
metric.add_metric("增长率", "15.6", "%", "+2.3%", "success", "环比增长")
metric.add_metric("收入", "¥1,250,000", "", "+12.3%", "success")

set_title(title)

设置指标组标题。

Parameters:

Name	Type	Description	Default
title	str	指标组标题	required

Returns:

Name	Type	Description
MetricWidget	MetricWidget	返回self以支持链式调用

set_layout(layout)

设置布局方式。

Parameters:

Name	Type	Description	Default
layout	str	布局方式，'horizontal' 或 'vertical'	required

Returns:

Name	Type	Description
MetricWidget	MetricWidget	返回self以支持链式调用

show_trends(show=True)

设置是否显示趋势。

Parameters:

Name	Type	Description	Default
show	bool	是否显示趋势信息	True

Returns:

Name	Type	Description
MetricWidget	MetricWidget	返回self以支持链式调用

clear_metrics()

清空所有指标。

Returns:

Name	Type	Description
MetricWidget	MetricWidget	返回self以支持链式调用

remove_metric(index)

根据索引移除指标。

Parameters:

Name	Type	Description	Default
index	int	要移除的指标索引	required

Returns:

Name	Type	Description
MetricWidget	MetricWidget	返回self以支持链式调用

Raises:

Type	Description
IndexError	当索引超出范围时