✨ feat!(ui): 重构图表组件架构，实现数据与样式分离 (#2035)

* ✨ feat!(ui): 重构图表组件架构，实现数据与样式分离

🏗️ **架构重构**
- 移除charts.py中所有硬编码样式参数(grid、tooltip、legend等)
- 将样式配置迁移至主题层style.json文件
- 统一图表模板消费样式文件的能力

📊 **图表组件优化**
- bar_chart: 移除grid和坐标轴show参数
- pie_chart: 移除tooltip、legend样式和series视觉参数
- line_chart: 移除tooltip、grid和坐标轴配置
- radar_chart: 移除tooltip硬编码

🎨 **主题系统增强**
- 新增pie_chart、line_chart、radar_chart的style.json配置
- 更新bar_chart/style.json，添加grid、xAxis、yAxis样式
- 所有图表模板支持deepMerge样式合并逻辑

🔧 **Breaking Changes**
- 图表工厂函数不再接受样式参数
- 主题开发者现可通过style.json完全定制图表外观
- 提升组件可维护性和主题灵活性

* 📦️ build(pyinstaller): 引入 resources.spec 并更新 .gitignore 规则

* 🚨 auto fix by pre-commit hooks

---------

Co-authored-by: webjoin111 <455457521@qq.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

zhenxun/ui/__init__.py

@@ -1,8 +1,9 @@
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any
 
 from zhenxun.services.renderer.protocols import Renderable
 
+from . import builders
 from .builders.core.layout import LayoutBuilder
 from .models.core.base import RenderableComponent
 from .models.core.markdown import MarkdownData
@@ -12,6 +13,14 @@ from .models.core.template import TemplateComponent
 def template(path: str | Path, data: dict[str, Any]) -> TemplateComponent:
     """
     创建一个基于独立模板文件的UI组件。
+    适用于不希望遵循标准主题结构，而是直接渲染单个HTML文件的场景。
+
+    参数:
+        path: 指向HTML模板文件的绝对或相对路径。
+        data: 传递给模板的上下文数据字典。
+
+    返回:
+        TemplateComponent: 一个可被 `render()` 函数处理的组件实例。
     """
     if isinstance(path, str):
         path = Path(path)
@@ -22,15 +31,35 @@ def template(path: str | Path, data: dict[str, Any]) -> TemplateComponent:
 def markdown(content: str, style: str | Path | None = "default") -> MarkdownData:
     """
     创建一个基于Markdown内容的UI组件。
+
+    参数:
+        content: 要渲染的Markdown字符串。
+        style: (可选) Markdown的样式名称（如 'github-light'）或一个指向
+               自定义CSS文件的路径。
+
+    返回:
+        MarkdownData: 一个可被 `render()` 函数处理的组件实例。
     """
+    builder = builders.MarkdownBuilder().text(content)
+    component = builder.build()
     if isinstance(style, Path):
-        return MarkdownData(markdown=content, css_path=str(style.absolute()))
-    return MarkdownData(markdown=content, style_name=style)
+        component.css_path = str(style.absolute())
+    else:
+        component.style_name = style
+    return component
 
 
 def vstack(children: list[RenderableComponent], **layout_options) -> "LayoutBuilder":
     """
     创建一个垂直布局组件。
+    便捷函数，用于将多个组件垂直堆叠。
+
+    参数:
+        children: 一个包含 `RenderableComponent` 实例的列表。
+        **layout_options: 传递给布局模板的额外选项，如 `padding`, `gap`。
+
+    返回:
+        LayoutBuilder: 一个配置好的垂直布局构建器。
     """
     builder = LayoutBuilder.column(**layout_options)
     for child in children:
@@ -41,6 +70,14 @@ def vstack(children: list[RenderableComponent], **layout_options) -> "LayoutBuil
 def hstack(children: list[RenderableComponent], **layout_options) -> "LayoutBuilder":
     """
     创建一个水平布局组件。
+    便捷函数，用于将多个组件水平排列。
+
+    参数:
+        children: 一个包含 `RenderableComponent` 实例的列表。
+        **layout_options: 传递给布局模板的额外选项，如 `padding`, `gap`。
+
+    返回:
+        LayoutBuilder: 一个配置好的水平布局构建器。
     """
     builder = LayoutBuilder.row(**layout_options)
     for child in children:
@@ -53,15 +90,25 @@ async def render(
     data: dict | None = None,
     *,
     use_cache: bool = False,
-    debug_mode: Literal["none", "log"] = "none",
     **kwargs,
 ) -> bytes:
     """
     统一的UI渲染入口。
+    这是第三方开发者最常用的函数，用于将任何可渲染对象转换为图片。
 
     用法:
-    1. 渲染一个已构建的UI组件: `render(my_builder.build())`
-    2. 直接渲染一个模板文件: `render("path/to/template", data={...})`
+        1. 渲染一个已构建的UI组件: `render(my_builder.build())`
+        2. 直接渲染一个模板文件: `render("path/to/template", data={...})`
+
+    参数:
+        component_or_path: 一个 `Renderable` 实例，或一个指向模板文件的
+                           `str` 或 `Path` 对象。
+        data: (可选) 当 `component_or_path` 是路径时，必须提供此数据字典。
+        use_cache: (可选) 是否为此渲染启用文件缓存，默认为 `False`。
+        **kwargs: 传递给底层截图引擎的额外参数，例如 `viewport`。
+
+    返回:
+        bytes: 渲染后的PNG图片字节数据。
     """
     from zhenxun.services import renderer_service
 
@@ -73,9 +120,7 @@ async def render(
     else:
         component = component_or_path
 
-    return await renderer_service.render(
-        component, use_cache=use_cache, debug_mode=debug_mode, **kwargs
-    )
+    return await renderer_service.render(component, use_cache=use_cache, **kwargs)
 
 
 async def render_template(
@@ -94,6 +139,9 @@ async def render_template(
 
     返回:
         bytes: 渲染后的图片数据。
+
+    异常:
+        RenderingError: 渲染失败时抛出。
     """
     return await render(path, data, use_cache=use_cache, **kwargs)
 
@@ -114,12 +162,16 @@ async def render_markdown(
 
     返回:
         bytes: 渲染后的图片数据。
+
+    异常:
+        RenderingError: 渲染失败时抛出。
     """
-    component: MarkdownData
+    builder = builders.MarkdownBuilder().text(md)
+    component = builder.build()
     if isinstance(style, Path):
-        component = MarkdownData(markdown=md, css_path=str(style.absolute()))
+        component.css_path = str(style.absolute())
     else:
-        component = MarkdownData(markdown=md, style_name=style)
+        component.style_name = style
 
     return await render(component, use_cache=use_cache, **kwargs)
 
@@ -131,10 +183,44 @@ async def render_full_result(
     component: Renderable, use_cache: bool = False, **kwargs
 ) -> RenderResult:
     """
-    渲染组件并返回包含图片和HTML的完整结果对象，用于调试和高级用途。
+    渲染组件并返回包含图片和HTML的完整结果对象。
+    主要用于调试或需要同时访问图片和其源HTML的场景。
+
+    参数:
+        component: 一个 `Renderable` 实例。
+        use_cache: (可选) 是否为此渲染启用文件缓存，默认为 `False`。
+        **kwargs: 传递给底层截图引擎的额外参数。
+
+    返回:
+        RenderResult: 一个包含 `image_bytes` 和 `html_content` 的Pydantic模型。
     """
     from zhenxun.services import renderer_service
+    from zhenxun.services.renderer.service import RenderContext
 
-    return await renderer_service._render_component(
-        component, use_cache=use_cache, **kwargs
+    if not renderer_service._initialized:
+        await renderer_service.initialize()
+    assert renderer_service._theme_manager is not None, "ThemeManager 未初始化"
+    assert renderer_service._screenshot_engine is not None, "ScreenshotEngine 未初始化"
+
+    context = RenderContext(
+        renderer=renderer_service,
+        theme_manager=renderer_service._theme_manager,
+        screenshot_engine=renderer_service._screenshot_engine,
+        component=component,
+        use_cache=use_cache,
+        render_options=kwargs,
     )
+    return await renderer_service._render_component(context)
+
+
+__all__ = [
+    "builders",
+    "hstack",
+    "markdown",
+    "render",
+    "render_full_result",
+    "render_markdown",
+    "render_template",
+    "template",
+    "vstack",
+]

zhenxun/ui/builders/__init__.py

@@ -1,19 +1,49 @@
-from . import widgets
-from .core.layout import LayoutBuilder
-from .core.markdown import MarkdownBuilder
-from .core.notebook import NotebookBuilder
-from .core.table import TableBuilder
-from .presets.help_page import PluginHelpPageBuilder
-from .presets.info_card import InfoCardBuilder
-from .presets.plugin_menu import PluginMenuBuilder
+from .charts import EChartsBuilder
+from .components import (
+    AlertBuilder,
+    AvatarBuilder,
+    AvatarGroupBuilder,
+    BadgeBuilder,
+    DividerBuilder,
+    KpiCardBuilder,
+    ProgressBarBuilder,
+    TimelineBuilder,
+    UserInfoBlockBuilder,
+)
+from .core import (
+    CardBuilder,
+    DetailsBuilder,
+    LayoutBuilder,
+    ListBuilder,
+    MarkdownBuilder,
+    NotebookBuilder,
+    TableBuilder,
+    TextBuilder,
+)
+from .presets import (
+    PluginHelpPageBuilder,
+    PluginMenuBuilder,
+)
 
 __all__ = [
-    "InfoCardBuilder",
+    "AlertBuilder",
+    "AvatarBuilder",
+    "AvatarGroupBuilder",
+    "BadgeBuilder",
+    "CardBuilder",
+    "DetailsBuilder",
+    "DividerBuilder",
+    "EChartsBuilder",
+    "KpiCardBuilder",
     "LayoutBuilder",
+    "ListBuilder",
     "MarkdownBuilder",
     "NotebookBuilder",
     "PluginHelpPageBuilder",
     "PluginMenuBuilder",
+    "ProgressBarBuilder",
     "TableBuilder",
-    "widgets",
+    "TextBuilder",
+    "TimelineBuilder",
+    "UserInfoBlockBuilder",
 ]

zhenxun/ui/builders/base.py

@@ -7,14 +7,24 @@ T_DataModel = TypeVar("T_DataModel", bound=BaseModel)
 
 
 class BaseBuilder(Generic[T_DataModel]):
-    """所有UI构建器的基类，提供通用的样式化和构建逻辑。"""
+    """
+    所有UI构建器的通用基类。
+
+    它实现了Builder设计模式，提供了一个流畅的、链式调用的API来创建和配置UI组件的数据模型。
+    同时，它也提供了通用的样式化方法，如 `with_style`, `with_inline_style` 等。
+
+    参数:
+        T_DataModel: 与此构建器关联的 Pydantic 数据模型类型。
+    """
 
     def __init__(self, data_model: T_DataModel, template_name: str):
         self._data: T_DataModel = data_model
         self._style_name: str | None = None
         self._template_name = template_name
         self._inline_style: dict | None = None
-        self._extra_css: str | None = None
+        self._component_css: str | None = None
+        self._variant: str | None = None
+        self._extra_classes: list[str] = []
 
     @property
     def data(self) -> T_DataModel:
@@ -23,6 +33,12 @@ class BaseBuilder(Generic[T_DataModel]):
     def with_style(self, style_name: str) -> Self:
         """
         为组件应用一个特定的样式。
+
+        参数:
+            style_name: 在主题的CSS中定义的样式类名。
+
+        返回:
+            Self: 当前构建器实例，以支持链式调用。
         """
         self._style_name = style_name
         return self
@@ -32,26 +48,70 @@ class BaseBuilder(Generic[T_DataModel]):
         为组件的根元素应用动态的内联样式。
 
         参数:
-            style: 一个CSS样式字典，例如 {"background-color":"#fff","font-size":"16px"}
+            style: 一个CSS样式字典，例如
+                   `{"background-color":"#fff","font-size":"16px"}`。
+
+        返回:
+            Self: 当前构建器实例，以支持链式调用。
         """
         self._inline_style = style
         return self
 
-    def with_extra_css(self, css: str) -> Self:
+    def with_variant(self, variant_name: str) -> Self:
+        """
+        为组件应用一个特定的变体/皮肤。
+
+        参数:
+            variant_name: 在组件的 `skins/` 目录下定义的变体名称。
+
+        返回:
+            Self: 当前构建器实例，以支持链式调用。
+        """
+        self._variant = variant_name
+        return self
+
+    def with_component_css(self, css: str) -> Self:
         """
         向页面注入一段自定义的CSS样式字符串。
 
         参数:
             css: 包含CSS规则的字符串。
+
+        返回:
+            Self: 当前构建器实例，以支持链式调用。
         """
-        self._extra_css = css
+        self._component_css = css
+        return self
+
+    def with_classes(self, *class_names: str) -> Self:
+        """
+        为组件的根元素添加一个或多个CSS工具类。
+        这些类来自主题预定义的工具集。
+
+        示例: .with_classes("p-4", "text-center", "font-bold")
+        """
+        self._extra_classes.extend(class_names)
         return self
 
     def build(self) -> T_DataModel:
         """
         构建并返回配置好的数据模型。
+        这是构建过程的最后一步，它会将所有配置应用到数据模型上。
+
+        返回:
+            T_DataModel: 最终配置好的、可被渲染服务使用的数据模型实例。
         """
         if self._style_name and hasattr(self._data, "style_name"):
             setattr(self._data, "style_name", self._style_name)
 
+        if self._inline_style and hasattr(self._data, "inline_style"):
+            setattr(self._data, "inline_style", self._inline_style)
+        if self._component_css and hasattr(self._data, "component_css"):
+            setattr(self._data, "component_css", self._component_css)
+        if self._variant and hasattr(self._data, "variant"):
+            setattr(self._data, "variant", self._variant)
+
+        if self._extra_classes and hasattr(self._data, "extra_classes"):
+            setattr(self._data, "extra_classes", self._extra_classes)
+
         return self._data

zhenxun/ui/builders/charts.py

@@ -2,87 +2,176 @@ from typing import Any, Generic, Literal, TypeVar
 from typing_extensions import Self
 
 from ..models.charts import (
-    BarChartData,
     BaseChartData,
-    LineChartData,
-    LineChartSeries,
-    PieChartData,
-    PieChartDataItem,
+    EChartsAxis,
+    EChartsData,
+    EChartsGrid,
+    EChartsSeries,
+    EChartsTitle,
+    EChartsTooltip,
 )
 from .base import BaseBuilder
 
 T_ChartData = TypeVar("T_ChartData", bound=BaseChartData)
 
 
-class BaseChartBuilder(BaseBuilder[T_ChartData], Generic[T_ChartData]):
-    """所有图表构建器的基类"""
+class EChartsBuilder(BaseBuilder[EChartsData], Generic[T_ChartData]):
+    """
+    一个统一的、泛型的 ECharts 图表构建器。
+    提供了设置 ECharts `option` 的核心方法，以及一些常用图表的便利方法。
+    """
 
-    def set_title(self, title: str) -> Self:
-        self._data.title = title
-        return self
-
-
-class BarChartBuilder(BaseChartBuilder[BarChartData]):
-    """链式构建柱状图的辅助类 (支持横向和竖向)"""
-
-    def __init__(
-        self, title: str, direction: Literal["horizontal", "vertical"] = "horizontal"
-    ):
-        data_model = BarChartData(
-            title=title, direction=direction, category_data=[], data=[]
+    def __init__(self, template_name: str, title: str):
+        model = EChartsData(
+            template_path=template_name,
+            title=EChartsTitle(text=title),
+            grid=None,
+            tooltip=None,
+            xAxis=None,
+            yAxis=None,
+            legend=None,
+            background_image=None,
         )
-        super().__init__(data_model, template_name="components/charts/bar_chart")
+        super().__init__(model, template_name=template_name)
 
-    def add_data(self, category: str, value: float) -> Self:
-        """添加一个数据点"""
-        self._data.category_data.append(category)
-        self._data.data.append(value)
-        return self
-
-    def add_data_items(
-        self, items: list[tuple[str, int | float]] | list[dict[str, Any]]
+    def set_title(
+        self, text: str, left: Literal["left", "center", "right"] = "center"
     ) -> Self:
-        for item in items:
-            if isinstance(item, tuple):
-                self.add_data(item[0], item[1])
-            elif isinstance(item, dict):
-                self.add_data(item.get("category", ""), item.get("value", 0))
+        self._data.title_model = EChartsTitle(text=text, left=left)
         return self
 
-    def set_background_image(self, background_image: str) -> Self:
-        """设置背景图片 (仅横向柱状图模板支持)"""
-        self._data.background_image = background_image
+    def set_grid(
+        self,
+        left: str | None = None,
+        right: str | None = None,
+        top: str | None = None,
+        bottom: str | None = None,
+        containLabel: bool = True,
+    ) -> Self:
+        self._data.grid_model = EChartsGrid(
+            left=left, right=right, top=top, bottom=bottom, containLabel=containLabel
+        )
         return self
 
-
-class PieChartBuilder(BaseChartBuilder[PieChartData]):
-    """链式构建饼图的辅助类"""
-
-    def __init__(self, title: str):
-        data_model = PieChartData(title=title, data=[])
-        super().__init__(data_model, template_name="components/charts/pie_chart")
-
-    def add_slice(self, name: str, value: float) -> Self:
-        """添加一个饼图扇区"""
-        self._data.data.append(PieChartDataItem(name=name, value=value))
+    def set_tooltip(self, trigger: Literal["item", "axis", "none"]) -> Self:
+        self._data.tooltip_model = EChartsTooltip(trigger=trigger)
         return self
 
+    def set_x_axis(
+        self,
+        type: Literal["category", "value", "time", "log"],
+        data: list[Any] | None = None,
+        show: bool = True,
+    ) -> Self:
+        self._data.x_axis_model = EChartsAxis(type=type, data=data, show=show)
+        return self
 
-class LineChartBuilder(BaseChartBuilder[LineChartData]):
-    """链式构建折线图的辅助类"""
-
-    def __init__(self, title: str):
-        data_model = LineChartData(title=title, category_data=[], series=[])
-        super().__init__(data_model, template_name="components/charts/line_chart")
-
-    def set_categories(self, categories: list[str]) -> Self:
-        """设置X轴的分类标签"""
-        self._data.category_data = categories
+    def set_y_axis(
+        self,
+        type: Literal["category", "value", "time", "log"],
+        data: list[Any] | None = None,
+        show: bool = True,
+    ) -> Self:
+        self._data.y_axis_model = EChartsAxis(type=type, data=data, show=show)
         return self
 
     def add_series(
-        self, name: str, data: list[int | float], smooth: bool = False
+        self, type: str, data: list[Any], name: str | None = None, **kwargs: Any
     ) -> Self:
-        """添加一条折线"""
-        self._data.series.append(LineChartSeries(name=name, data=data, smooth=smooth))
+        series = EChartsSeries(type=type, data=data, name=name, **kwargs)
+        self._data.series_models.append(series)
         return self
+
+    def set_legend(
+        self,
+        data: list[str],
+        orient: Literal["horizontal", "vertical"] = "horizontal",
+        left: str = "auto",
+    ) -> Self:
+        self._data.legend_model = {"data": data, "orient": orient, "left": left}
+        return self
+
+    def set_option(self, key: str, value: Any) -> Self:
+        """
+        [高级] 设置 ECharts `option` 中的一个原始键值对。
+        这会覆盖由其他流畅API方法设置的同名配置。
+        """
+        self._data.raw_options[key] = value
+        return self
+
+    def set_background_image(self, image_name: str) -> Self:
+        """【兼容】为横向柱状图设置背景图片。"""
+        self._data.background_image = image_name
+        return self
+
+
+def bar_chart(
+    title: str,
+    items: list[tuple[str, int | float]],
+    direction: Literal["horizontal", "vertical"] = "horizontal",
+) -> EChartsBuilder:
+    """便捷工厂函数：创建一个柱状图构建器。"""
+    builder = EChartsBuilder("components/charts/bar_chart", title)
+    categories = [item[0] for item in items]
+    values = [item[1] for item in items]
+
+    if direction == "horizontal":
+        builder.set_x_axis(type="value")
+        builder.set_y_axis(type="category", data=categories)
+        builder.add_series(
+            type="bar",
+            data=values,
+        )
+    else:
+        builder.set_x_axis(type="category", data=categories)
+        builder.set_y_axis(type="value")
+        builder.add_series(type="bar", data=values)
+
+    return builder
+
+
+def pie_chart(title: str, items: list[tuple[str, int | float]]) -> EChartsBuilder:
+    """便捷工厂函数：创建一个饼图构建器。"""
+    builder = EChartsBuilder("components/charts/pie_chart", title)
+    data = [{"name": name, "value": value} for name, value in items]
+    legend_data = [item[0] for item in items]
+
+    builder.set_legend(data=legend_data)
+    builder.add_series(
+        name=title,
+        type="pie",
+        data=data,
+    )
+    return builder
+
+
+def line_chart(
+    title: str, categories: list[str], series: list[dict[str, Any]]
+) -> EChartsBuilder:
+    """便捷工厂函数：创建一个折线图构建器。"""
+    builder = EChartsBuilder("components/charts/line_chart", title)
+
+    builder.set_x_axis(type="category", data=categories)
+    builder.set_y_axis(type="value")
+    for s in series:
+        builder.add_series(
+            type="line",
+            name=s.get("name", ""),
+            data=s.get("data", []),
+            smooth=s.get("smooth", False),
+        )
+    return builder
+
+
+def radar_chart(
+    title: str, indicators: list[tuple[str, int | float]], series: list[dict[str, Any]]
+) -> EChartsBuilder:
+    """便捷工厂函数：创建一个雷达图构建器。"""
+    builder = EChartsBuilder("components/charts/radar_chart", title)
+    legend_data = [s.get("name", "") for s in series]
+    radar_indicators = [{"name": name, "max": max_val} for name, max_val in indicators]
+
+    builder.set_legend(data=legend_data)
+    builder.set_option("radar", {"indicator": radar_indicators})
+    builder.add_series(type="radar", data=series)
+    return builder

zhenxun/ui/builders/components/__init__.py

@@ -0,0 +1,25 @@
+"""
+小组件构建器模块
+包含各种UI小组件的构建器
+"""
+
+from .alert import AlertBuilder
+from .avatar import AvatarBuilder, AvatarGroupBuilder
+from .badge import BadgeBuilder
+from .divider import DividerBuilder
+from .kpi_card import KpiCardBuilder
+from .progress_bar import ProgressBarBuilder
+from .timeline import TimelineBuilder
+from .user_info_block import UserInfoBlockBuilder
+
+__all__ = [
+    "AlertBuilder",
+    "AvatarBuilder",
+    "AvatarGroupBuilder",
+    "BadgeBuilder",
+    "DividerBuilder",
+    "KpiCardBuilder",
+    "ProgressBarBuilder",
+    "TimelineBuilder",
+    "UserInfoBlockBuilder",
+]

zhenxun/ui/builders/components/alert.py

@@ -0,0 +1,23 @@
+from typing import Literal
+from typing_extensions import Self
+
+from ...models.components.alert import Alert
+from ..base import BaseBuilder
+
+
+class AlertBuilder(BaseBuilder[Alert]):
+    """链式构建提示/标注框组件的辅助类"""
+
+    def __init__(
+        self,
+        title: str,
+        content: str,
+        type: Literal["info", "success", "warning", "error"] = "info",
+    ):
+        data_model = Alert(title=title, content=content, type=type)
+        super().__init__(data_model, template_name="components/widgets/alert")
+
+    def hide_icon(self) -> Self:
+        """隐藏提示框的默认图标"""
+        self._data.show_icon = False
+        return self

zhenxun/ui/builders/components/avatar.py

@@ -0,0 +1,38 @@
+from typing import Literal
+from typing_extensions import Self
+
+from ...models.components.avatar import Avatar, AvatarGroup
+from ..base import BaseBuilder
+
+
+class AvatarBuilder(BaseBuilder[Avatar]):
+    """链式构建单个头像的辅助类"""
+
+    def __init__(self, src: str):
+        data_model = Avatar(src=src, shape="circle", size=50)
+        super().__init__(data_model, template_name="components/widgets/avatar")
+
+    def set_shape(self, shape: Literal["circle", "square"]) -> Self:
+        self._data.shape = shape
+        return self
+
+    def set_size(self, size: int) -> Self:
+        self._data.size = size
+        return self
+
+
+class AvatarGroupBuilder(BaseBuilder[AvatarGroup]):
+    """链式构建头像组的辅助类"""
+
+    def __init__(self):
+        data_model = AvatarGroup(avatars=[], spacing=-15, max_count=None)
+        super().__init__(data_model, template_name="components/widgets/avatar_group")
+
+    def add_avatar(self, avatar: Avatar | AvatarBuilder | str) -> Self:
+        if isinstance(avatar, str):
+            self._data.avatars.append(Avatar(src=avatar, shape="circle", size=50))
+        elif isinstance(avatar, AvatarBuilder):
+            self._data.avatars.append(avatar.build())
+        else:
+            self._data.avatars.append(avatar)
+        return self

zhenxun/ui/builders/components/divider.py

@@ -0,0 +1,20 @@
+from typing import Literal
+
+from ...models.components.divider import Divider
+from ..base import BaseBuilder
+
+
+class DividerBuilder(BaseBuilder[Divider]):
+    """链式构建分割线组件的辅助类"""
+
+    def __init__(
+        self,
+        margin: str = "2em 0",
+        color: str = "#f7889c",
+        style: Literal["solid", "dashed", "dotted"] = "solid",
+        thickness: str = "1px",
+    ):
+        data_model = Divider(
+            margin=margin, color=color, style=style, thickness=thickness
+        )
+        super().__init__(data_model, template_name="components/widgets/divider")

zhenxun/ui/builders/components/kpi_card.py

@@ -0,0 +1,31 @@
+from typing import Any, Literal
+from typing_extensions import Self
+
+from ...models.components.kpi_card import KpiCard
+from ..base import BaseBuilder
+
+
+class KpiCardBuilder(BaseBuilder[KpiCard]):
+    """链式构建统计卡片（KPI Card）的辅助类"""
+
+    def __init__(self, label: str, value: Any):
+        data_model = KpiCard(label=label, value=value)
+        super().__init__(data_model, template_name="components/widgets/kpi_card")
+
+    def with_unit(self, unit: str) -> Self:
+        """设置数值的单位"""
+        self._data.unit = unit
+        return self
+
+    def with_change(
+        self, change: str, type: Literal["positive", "negative", "neutral"] = "neutral"
+    ) -> Self:
+        """设置与上一周期的变化率"""
+        self._data.change = change
+        self._data.change_type = type
+        return self
+
+    def with_icon(self, svg_path: str) -> Self:
+        """设置卡片图标 (提供SVG path data)"""
+        self._data.icon_svg = svg_path
+        return self

zhenxun/ui/builders/components/timeline.py

@@ -0,0 +1,28 @@
+from typing_extensions import Self
+
+from ...models.components.timeline import Timeline, TimelineItem
+from ..base import BaseBuilder
+
+
+class TimelineBuilder(BaseBuilder[Timeline]):
+    """链式构建时间轴组件的辅助类"""
+
+    def __init__(self):
+        data_model = Timeline(items=[])
+        super().__init__(data_model, template_name="components/widgets/timeline")
+
+    def add_item(
+        self,
+        timestamp: str,
+        title: str,
+        content: str,
+        *,
+        icon: str | None = None,
+        color: str | None = None,
+    ) -> Self:
+        """向时间轴中添加一个事件点"""
+        item = TimelineItem(
+            timestamp=timestamp, title=title, content=content, icon=icon, color=color
+        )
+        self._data.items.append(item)
+        return self

zhenxun/ui/builders/core/__init__.py

@@ -3,14 +3,22 @@
 包含基础的UI构建器类
 """
 
+from .card import CardBuilder
+from .details import DetailsBuilder
 from .layout import LayoutBuilder
+from .list import ListBuilder
 from .markdown import MarkdownBuilder
 from .notebook import NotebookBuilder
 from .table import TableBuilder
+from .text import TextBuilder
 
 __all__ = [
+    "CardBuilder",
+    "DetailsBuilder",
     "LayoutBuilder",
+    "ListBuilder",
     "MarkdownBuilder",
     "NotebookBuilder",
     "TableBuilder",
+    "TextBuilder",
 ]

zhenxun/ui/builders/core/card.py

@@ -0,0 +1,26 @@
+from typing_extensions import Self
+
+from ...models.core.base import RenderableComponent
+from ...models.core.card import CardData
+from ..base import BaseBuilder
+
+
+class CardBuilder(BaseBuilder[CardData]):
+    """链式构建通用卡片容器的辅助类"""
+
+    def __init__(self, content: "RenderableComponent | BaseBuilder"):
+        content_model = content.build() if isinstance(content, BaseBuilder) else content
+        data_model = CardData(content=content_model)
+        super().__init__(data_model, template_name="components/core/card")
+
+    def set_header(self, header: "RenderableComponent | BaseBuilder") -> Self:
+        """设置卡片的头部组件"""
+        header_model = header.build() if isinstance(header, BaseBuilder) else header
+        self._data.header = header_model
+        return self
+
+    def set_footer(self, footer: "RenderableComponent | BaseBuilder") -> Self:
+        """设置卡片的尾部组件"""
+        footer_model = footer.build() if isinstance(footer, BaseBuilder) else footer
+        self._data.footer = footer_model
+        return self

zhenxun/ui/builders/core/details.py

@@ -0,0 +1,19 @@
+from typing import Any
+from typing_extensions import Self
+
+from ...models.core.details import DetailsData, DetailsItem
+from ..base import BaseBuilder
+
+
+class DetailsBuilder(BaseBuilder[DetailsData]):
+    """链式构建描述列表（键值对）的辅助类"""
+
+    def __init__(self, title: str | None = None):
+        data_model = DetailsData(title=title, items=[])
+        super().__init__(data_model, template_name="components/core/details")
+
+    def add_item(self, label: str, value: Any) -> Self:
+        """向列表中添加一个键值对项目"""
+        value_str = str(value)
+        self._data.items.append(DetailsItem(label=label, value=value_str))
+        return self

zhenxun/ui/builders/core/layout.py

@@ -19,16 +19,32 @@ class LayoutBuilder(BaseBuilder[LayoutData]):
         self._options: dict[str, Any] = {}
 
     @classmethod
-    def column(cls, **options: Any) -> Self:
+    def column(
+        cls, *, gap: str = "20px", align_items: str = "stretch", **options: Any
+    ) -> Self:
         builder = cls()
-        builder._template_name = "layouts/column"
+        builder._template_name = "components/core/layouts/column"
+        builder._options["gap"] = gap
+        builder._options["align_items"] = align_items
         builder._options.update(options)
         return builder
 
     @classmethod
-    def row(cls, **options: Any) -> Self:
+    def row(
+        cls, *, gap: str = "10px", align_items: str = "center", **options: Any
+    ) -> Self:
         builder = cls()
-        builder._template_name = "layouts/row"
+        builder._template_name = "components/core/layouts/row"
+        builder._options["gap"] = gap
+        builder._options["align_items"] = align_items
+        builder._options.update(options)
+        return builder
+
+    @classmethod
+    def grid(cls, columns: int = 2, **options: Any) -> Self:
+        builder = cls()
+        builder._template_name = "components/core/layouts/grid"
+        builder._options["columns"] = columns
         builder._options.update(options)
         return builder
 
@@ -56,15 +72,15 @@ class LayoutBuilder(BaseBuilder[LayoutData]):
         metadata: dict[str, Any] | None = None,
     ) -> Self:
         """
-        向布局中添加一个组件，支持多种组件类型的添加。
+        向布局中添加一个组件项。
 
         参数:
-            component: 一个 Builder 实例 (如 TableBuilder) 或一个 RenderableComponent
-                      数据模型。
-            metadata: (可选) 与此项目关联的元数据，可用于模板。
+            component: 一个 `BaseBuilder` 实例 (如 `TableBuilder()`) 或一个已构建的
+                       `RenderableComponent` 数据模型。
+            metadata: (可选) 与此项目关联的元数据，可在布局模板中访问。
 
         返回:
-            Self: 返回当前布局构建器实例，支持链式调用。
+            Self: 当前构建器实例，以支持链式调用。
         """
         component_data = (
             component.data if isinstance(component, BaseBuilder) else component
@@ -76,28 +92,24 @@ class LayoutBuilder(BaseBuilder[LayoutData]):
 
     def add_option(self, key: str, value: Any) -> Self:
         """
-        为布局添加一个自定义选项，该选项会传递给模板。
+        为布局模板添加一个自定义选项。
+
+        例如，`add_option("padding", "30px")` 会在模板的 `data.options`
+        字典中添加 `{"padding": "30px"}`。
 
         参数:
-            key: 选项的键名，用于在模板中引用。
-            value: 选项的值，可以是任意类型的数据。
+            key: 选项的键名。
+            value: 选项的值。
 
         返回:
-            Self: 返回当前布局构建器实例，支持链式调用。
+            Self: 当前构建器实例，以支持链式调用。
         """
         self._options[key] = value
         return self
 
     def build(self) -> LayoutData:
         """
-        [修改] 构建并返回 LayoutData 模型实例。
-        此方法现在是同步的，并且不执行渲染。
-
-        参数:
-            无
-
-        返回:
-            LayoutData: 配置好的布局数据模型。
+        构建并返回 LayoutData 模型实例。
         """
         if not self._template_name:
             raise ValueError(
@@ -106,4 +118,4 @@ class LayoutBuilder(BaseBuilder[LayoutData]):
 
         self._data.options = self._options
         self._data.layout_type = self._template_name.split("/")[-1]
-        return self._data
+        return super().build()

zhenxun/ui/builders/core/list.py

@@ -0,0 +1,31 @@
+from typing_extensions import Self
+
+from ...models.core.base import RenderableComponent
+from ...models.core.list import ListData, ListItem
+from ..base import BaseBuilder
+
+
+class ListBuilder(BaseBuilder[ListData]):
+    """链式构建通用列表的辅助类。"""
+
+    def __init__(self, ordered: bool = False):
+        data_model = ListData(ordered=ordered)
+        super().__init__(data_model, template_name="components/core/list")
+
+    def add_item(self, component: "BaseBuilder | RenderableComponent") -> Self:
+        """
+        向列表中添加一个项目。
+
+        参数:
+            component: 一个 Builder 实例或一个 RenderableComponent 数据模型。
+        """
+        component_data = (
+            component.build() if isinstance(component, BaseBuilder) else component
+        )
+        self._data.items.append(ListItem(component=component_data))
+        return self
+
+    def ordered(self, is_ordered: bool = True) -> Self:
+        """设置列表是否为有序列表（带数字编号）。"""
+        self._data.ordered = is_ordered
+        return self

zhenxun/ui/builders/core/markdown.py

@@ -4,6 +4,7 @@ from typing import Any
 
 from ...models.core.markdown import (
     CodeElement,
+    ComponentElement,
     HeadingElement,
     ImageElement,
     ListElement,
@@ -12,6 +13,7 @@ from ...models.core.markdown import (
     MarkdownElement,
     QuoteElement,
     RawHtmlElement,
+    RenderableComponent,
     TableElement,
     TextElement,
 )
@@ -24,7 +26,7 @@ class MarkdownBuilder(BaseBuilder[MarkdownData]):
     """链式构建Markdown图片的辅助类，支持上下文管理和组合。"""
 
     def __init__(self):
-        data_model = MarkdownData(markdown="", width=800, css_path=None)
+        data_model = MarkdownData(elements=[], width=800, css_path=None)
         super().__init__(data_model, template_name="components/core/markdown")
         self._parts: list[MarkdownElement] = []
         self._width: int = 800
@@ -78,6 +80,16 @@ class MarkdownBuilder(BaseBuilder[MarkdownData]):
         )
         return self
 
+    def add_component(
+        self, component: "BaseBuilder | RenderableComponent"
+    ) -> "MarkdownBuilder":
+        """添加一个UI组件（如图表、卡片等）。"""
+        component_data = (
+            component.build() if isinstance(component, BaseBuilder) else component
+        )
+        self._append_element(ComponentElement(component=component_data))
+        return self
+
     def add_builder(self, builder: "MarkdownBuilder") -> "MarkdownBuilder":
         """将另一个builder的内容组合进来。"""
         if self._context_stack:
@@ -144,8 +156,7 @@ class MarkdownBuilder(BaseBuilder[MarkdownData]):
         """
         构建并返回 MarkdownData 模型实例。
         """
-        final_markdown = "\n\n".join(part.to_markdown() for part in self._parts).strip()
-        self._data.markdown = final_markdown
+        self._data.elements = self._parts
         self._data.width = self._width
         self._data.css_path = self._css_path
         return super().build()

zhenxun/ui/builders/core/table.py

@@ -1,3 +1,5 @@
+from typing import Literal
+
 from ...models.core.table import TableCell, TableData
 from ..base import BaseBuilder
 
@@ -12,16 +14,61 @@ class TableBuilder(BaseBuilder[TableData]):
         super().__init__(data_model, template_name="components/core/table")
 
     def set_headers(self, headers: list[str]) -> "TableBuilder":
-        """设置表头"""
+        """
+        设置表格的表头。
+
+        参数:
+            headers: 一个包含表头文本的字符串列表。
+
+        返回:
+            TableBuilder: 当前构建器实例，以支持链式调用。
+        """
         self._data.headers = headers
         return self
 
+    def set_column_alignments(
+        self, alignments: list[Literal["left", "center", "right"]]
+    ) -> "TableBuilder":
+        """
+        设置表格每列的文本对齐方式。
+
+        参数:
+            alignments: 一个包含 'left', 'center', 'right' 的对齐方式列表。
+
+        返回:
+            TableBuilder: 当前构建器实例，以支持链式调用。
+        """
+        self._data.column_alignments = alignments
+        return self
+
+    def set_column_widths(self, widths: list[str | int]) -> "TableBuilder":
+        """设置每列的宽度"""
+        self._data.column_widths = widths
+        return self
+
     def add_row(self, row: list[TableCell]) -> "TableBuilder":
-        """添加单行数据"""
+        """
+        向表格中添加一行数据。
+
+        参数:
+            row: 一个包含单元格数据的列表。单元格可以是字符串、数字或
+                 `TextCell`, `ImageCell` 等模型实例。
+
+        返回:
+            TableBuilder: 当前构建器实例，以支持链式调用。
+        """
         self._data.rows.append(row)
         return self
 
     def add_rows(self, rows: list[list[TableCell]]) -> "TableBuilder":
-        """批量添加多行数据"""
+        """
+        向表格中批量添加多行数据。
+
+        参数:
+            rows: 一个包含多行数据的列表。
+
+        返回:
+            TableBuilder: 当前构建器实例，以支持链式调用。
+        """
         self._data.rows.extend(rows)
         return self

zhenxun/ui/builders/core/text.py

@@ -0,0 +1,62 @@
+from typing import Literal
+from typing_extensions import Self
+
+from ...models.core.text import TextData, TextSpan
+from ..base import BaseBuilder
+
+
+class TextBuilder(BaseBuilder[TextData]):
+    """链式构建轻量级富文本组件的辅助类"""
+
+    def __init__(self, text: str = ""):
+        data_model = TextData(spans=[], align="left")
+        super().__init__(data_model, template_name="components/core/text")
+        if text:
+            self.add_span(text)
+
+    def set_alignment(self, align: Literal["left", "right", "center"]) -> Self:
+        """设置整个文本块的对齐方式"""
+        self._data.align = align
+        return self
+
+    def add_span(
+        self,
+        text: str,
+        *,
+        bold: bool = False,
+        italic: bool = False,
+        underline: bool = False,
+        strikethrough: bool = False,
+        code: bool = False,
+        color: str | None = None,
+        font_size: str | int | None = None,
+        font_family: str | None = None,
+    ) -> Self:
+        """
+        添加一个带有样式的文本片段。
+
+        参数:
+            text: 文本内容。
+            bold: 是否加粗。
+            italic: 是否斜体。
+            underline: 是否有下划线。
+            strikethrough: 是否有删除线。
+            code: 是否渲染为代码样式。
+            color: 文本颜色 (e.g., '#ff0000', 'red')。
+            font_size: 字体大小 (e.g., 16, '1.2em', '12px')。
+            font_family: 字体族。
+        """
+        font_size_str = f"{font_size}px" if isinstance(font_size, int) else font_size
+        span = TextSpan(
+            text=text,
+            bold=bold,
+            italic=italic,
+            underline=underline,
+            strikethrough=strikethrough,
+            code=code,
+            color=color,
+            font_size=font_size_str,
+            font_family=font_family,
+        )
+        self._data.spans.append(span)
+        return self

zhenxun/ui/builders/presets/__init__.py

@@ -3,12 +3,10 @@
 包含预定义的UI组件构建器
 """
 
-from .help_page import PluginHelpPageBuilder
-from .info_card import InfoCardBuilder
+from .plugin_help_page import PluginHelpPageBuilder
 from .plugin_menu import PluginMenuBuilder
 
 __all__ = [
-    "InfoCardBuilder",
     "PluginHelpPageBuilder",
     "PluginMenuBuilder",
 ]

zhenxun/ui/builders/presets/info_card.py

@@ -1,46 +0,0 @@
-from typing import Any
-
-from ...models.presets.card import (
-    InfoCardData,
-    InfoCardMetadataItem,
-    InfoCardSection,
-)
-from ..base import BaseBuilder
-
-__all__ = ["InfoCardBuilder"]
-
-
-class InfoCardBuilder(BaseBuilder[InfoCardData]):
-    def __init__(self, title: str):
-        self._data = InfoCardData(title=title)
-
-        super().__init__(self._data, template_name="components/presets/info_card")
-
-    def add_metadata(self, label: str, value: str | int) -> "InfoCardBuilder":
-        self._data.metadata.append(InfoCardMetadataItem(label=label, value=value))
-        return self
-
-    def add_metadata_items(
-        self, items: list[tuple[str, Any]] | list[dict[str, Any]]
-    ) -> "InfoCardBuilder":
-        for item in items:
-            if isinstance(item, tuple):
-                self.add_metadata(item[0], item[1])
-            elif isinstance(item, dict):
-                self.add_metadata(item.get("label", ""), item.get("value", ""))
-        return self
-
-    def add_section(self, title: str, content: str | list[str]) -> "InfoCardBuilder":
-        content_list = [content] if isinstance(content, str) else content
-        self._data.sections.append(InfoCardSection(title=title, content=content_list))
-        return self
-
-    def add_sections(
-        self, sections: list[tuple[str, str | list[str]]] | list[dict[str, Any]]
-    ) -> "InfoCardBuilder":
-        for section in sections:
-            if isinstance(section, tuple):
-                self.add_section(section[0], section[1])
-            elif isinstance(section, dict):
-                self.add_section(section.get("title", ""), section.get("content", []))
-        return self

zhenxun/ui/builders/presets/plugin_help_page.py

@@ -1,4 +1,4 @@
-from ...models.presets.help_page import (
+from ...models.presets.plugin_help_page import (
     HelpCategory,
     PluginHelpPageData,
 )
@@ -13,7 +13,7 @@ class PluginHelpPageBuilder(BaseBuilder[PluginHelpPageData]):
             bot_nickname=bot_nickname, page_title=page_title, categories=[]
         )
 
-        super().__init__(self._data, template_name="pages/core/help_page")
+        super().__init__(self._data, template_name="pages/core/plugin_help_page")
 
     def add_category(self, category: HelpCategory) -> "PluginHelpPageBuilder":
         """添加一个帮助分类"""

zhenxun/ui/builders/widgets/__init__.py

@@ -1,14 +0,0 @@
-"""
-小组件构建器模块
-包含各种UI小组件的构建器
-"""
-
-from .badge import BadgeBuilder
-from .progress_bar import ProgressBarBuilder
-from .user_info_block import UserInfoBlockBuilder
-
-__all__ = [
-    "BadgeBuilder",
-    "ProgressBarBuilder",
-    "UserInfoBlockBuilder",
-]

zhenxun/ui/models/__init__.py

@@ -1,70 +1,67 @@
 from .charts import (
-    BarChartData,
     BaseChartData,
-    LineChartData,
-    LineChartSeries,
-    PieChartData,
-    PieChartDataItem,
+    EChartsData,
 )
-from .components.badge import Badge
-from .components.divider import Divider, Rectangle
-from .components.progress_bar import ProgressBar
-from .components.user_info_block import UserInfoBlock
-from .core.base import RenderableComponent
-from .core.layout import LayoutData, LayoutItem
-from .core.markdown import (
+from .components import (
+    Badge,
+    Divider,
+    ProgressBar,
+    Rectangle,
+    UserInfoBlock,
+)
+from .core import (
+    BaseCell,
     CodeElement,
     HeadingElement,
+    ImageCell,
     ImageElement,
+    LayoutData,
+    LayoutItem,
     ListElement,
     ListItemElement,
     MarkdownData,
     MarkdownElement,
+    NotebookData,
+    NotebookElement,
     QuoteElement,
     RawHtmlElement,
-    TableElement,
-    TextElement,
-)
-from .core.notebook import NotebookData, NotebookElement
-from .core.table import (
-    BaseCell,
-    ImageCell,
+    RenderableComponent,
     StatusBadgeCell,
     TableCell,
     TableData,
+    TableElement,
     TextCell,
+    TextElement,
+)
+from .presets import (
+    HelpCategory,
+    HelpItem,
+    PluginHelpPageData,
+    PluginMenuCategory,
+    PluginMenuData,
+    PluginMenuItem,
 )
-from .presets.card import InfoCardData, InfoCardMetadataItem, InfoCardSection
-from .presets.help_page import HelpCategory, HelpItem, PluginHelpPageData
-from .presets.plugin_menu import PluginMenuCategory, PluginMenuData, PluginMenuItem
 
 __all__ = [
     "Badge",
-    "BarChartData",
     "BaseCell",
     "BaseChartData",
     "CodeElement",
     "Divider",
+    "EChartsData",
     "HeadingElement",
     "HelpCategory",
     "HelpItem",
     "ImageCell",
     "ImageElement",
-    "InfoCardData",
-    "InfoCardMetadataItem",
-    "InfoCardSection",
     "LayoutData",
     "LayoutItem",
-    "LineChartData",
-    "LineChartSeries",
     "ListElement",
     "ListItemElement",
     "MarkdownData",
     "MarkdownElement",
     "NotebookData",
     "NotebookElement",
-    "PieChartData",
-    "PieChartDataItem",
     "PluginHelpPageData",
     "PluginMenuCategory",
     "PluginMenuData",

zhenxun/ui/models/charts.py

@@ -1,63 +1,122 @@
-from typing import Literal
+from abc import ABC, abstractmethod
+from typing import Any, Literal
 import uuid
 
 from pydantic import BaseModel, Field
 
+from zhenxun.utils.pydantic_compat import model_dump
+
 from .core.base import RenderableComponent
 
 
-class BaseChartData(RenderableComponent):
+class EChartsTitle(BaseModel):
+    text: str
+    left: Literal["left", "center", "right"] = "center"
+
+
+class EChartsAxis(BaseModel):
+    type: Literal["category", "value", "time", "log"]
+    data: list[Any] | None = None
+    show: bool = True
+
+
+class EChartsSeries(BaseModel):
+    type: str
+    data: list[Any]
+    name: str | None = None
+    label: dict[str, Any] | None = None
+    itemStyle: dict[str, Any] | None = None
+    barMaxWidth: int | None = None
+    smooth: bool | None = None
+
+
+class EChartsTooltip(BaseModel):
+    trigger: Literal["item", "axis", "none"] = "item"
+
+
+class EChartsGrid(BaseModel):
+    left: str | None = None
+    right: str | None = None
+    top: str | None = None
+    bottom: str | None = None
+    containLabel: bool = True
+
+
+class BaseChartData(RenderableComponent, ABC):
     """所有图表数据模型的基类"""
 
     style_name: str | None = None
-    title: str
     chart_id: str = Field(default_factory=lambda: f"chart-{uuid.uuid4().hex}")
 
+    echarts_options: dict[str, Any] | None = None
+
+    @abstractmethod
+    def build_option(self) -> dict[str, Any]:
+        """将 Pydantic 模型序列化为 ECharts 的 option 字典。"""
+        raise NotImplementedError
+
+    def get_render_data(self) -> dict[str, Any]:
+        """为图表组件定制渲染数据，动态构建最终的 option 对象。"""
+        dumped_data = model_dump(self, exclude={"template_path"})
+        if hasattr(self, "build_option"):
+            dumped_data["option"] = self.build_option()
+        return dumped_data
+
     def get_required_scripts(self) -> list[str]:
         """声明此组件需要 ECharts 库。"""
         return ["js/echarts.min.js"]
 
 
-class BarChartData(BaseChartData):
-    """柱状图（支持横向和竖向）的数据模型"""
+class EChartsData(BaseChartData):
+    """统一的 ECharts 图表数据模型"""
 
-    category_data: list[str]
-    data: list[int | float]
-    direction: Literal["horizontal", "vertical"] = "horizontal"
-    background_image: str | None = None
+    template_path: str = Field(..., exclude=True)
+    title_model: EChartsTitle | None = Field(None, alias="title")
+    grid_model: EChartsGrid | None = Field(None, alias="grid")
+    tooltip_model: EChartsTooltip | None = Field(None, alias="tooltip")
+    x_axis_model: EChartsAxis | None = Field(None, alias="xAxis")
+    y_axis_model: EChartsAxis | None = Field(None, alias="yAxis")
+    series_models: list[EChartsSeries] = Field(default_factory=list, alias="series")
+    legend_model: dict[str, Any] | None = Field(default_factory=dict, alias="legend")
+    raw_options: dict[str, Any] = Field(
+        default_factory=dict, description="用于 set_option 的原始覆盖选项"
+    )
+
+    background_image: str | None = Field(
+        None, description="【兼容】用于横向柱状图的背景图片"
+    )
+
+    def build_option(self) -> dict[str, Any]:
+        """将 Pydantic 模型序列化为 ECharts 的 option 字典。"""
+        option: dict[str, Any] = {}
+        key_map = {
+            "title": "title_model",
+            "grid": "grid_model",
+            "tooltip": "tooltip_model",
+            "xAxis": "x_axis_model",
+            "yAxis": "y_axis_model",
+            "series": "series_models",
+            "legend": "legend_model",
+        }
+        for echarts_key, model_attr in key_map.items():
+            model_instance = getattr(self, model_attr, None)
+            if model_instance:
+                if isinstance(model_instance, list):
+                    option[echarts_key] = [
+                        model_dump(m, exclude_none=True) for m in model_instance
+                    ]
+                elif isinstance(model_instance, BaseModel):
+                    option[echarts_key] = model_dump(model_instance, exclude_none=True)
+                else:
+                    option[echarts_key] = model_instance
+        option.update(self.raw_options)
+        return option
+
+    @property
+    def title(self) -> str:
+        """为模板提供一个简单的字符串标题，保持向后兼容性。"""
+        return self.title_model.text if self.title_model else ""
 
     @property
     def template_name(self) -> str:
-        return "components/charts/bar_chart"
-
-
-class PieChartDataItem(BaseModel):
-    name: str
-    value: int | float
-
-
-class PieChartData(BaseChartData):
-    """饼图的数据模型"""
-
-    data: list[PieChartDataItem]
-
-    @property
-    def template_name(self) -> str:
-        return "components/charts/pie_chart"
-
-
-class LineChartSeries(BaseModel):
-    name: str
-    data: list[int | float]
-    smooth: bool = False
-
-
-class LineChartData(BaseChartData):
-    """折线图的数据模型"""
-
-    category_data: list[str]
-    series: list[LineChartSeries]
-
-    @property
-    def template_name(self) -> str:
-        return "components/charts/line_chart"
+        return self.template_path

zhenxun/ui/models/components/__init__.py

@@ -3,15 +3,22 @@
 包含各种UI组件的数据模型
 """
 
+from .alert import Alert
 from .badge import Badge
 from .divider import Divider, Rectangle
+from .kpi_card import KpiCard
 from .progress_bar import ProgressBar
+from .timeline import Timeline, TimelineItem
 from .user_info_block import UserInfoBlock
 
 __all__ = [
+    "Alert",
     "Badge",
     "Divider",
+    "KpiCard",
     "ProgressBar",
     "Rectangle",
+    "Timeline",
+    "TimelineItem",
     "UserInfoBlock",
 ]

zhenxun/ui/models/components/alert.py

@@ -0,0 +1,23 @@
+from typing import Literal
+
+from pydantic import Field
+
+from ..core.base import RenderableComponent
+
+__all__ = ["Alert"]
+
+
+class Alert(RenderableComponent):
+    """一个带样式的提示框组件，用于显示重要信息。"""
+
+    component_type: Literal["alert"] = "alert"
+    type: Literal["info", "success", "warning", "error"] = Field(
+        default="info", description="提示框的类型，决定了颜色和图标"
+    )
+    title: str = Field(..., description="提示框的标题")
+    content: str = Field(..., description="提示框的主要内容")
+    show_icon: bool = Field(default=True, description="是否显示与类型匹配的图标")
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/alert"

zhenxun/ui/models/components/avatar.py

@@ -0,0 +1,35 @@
+from typing import Literal
+
+from pydantic import Field
+
+from ..core.base import RenderableComponent
+
+__all__ = ["Avatar", "AvatarGroup"]
+
+
+class Avatar(RenderableComponent):
+    """单个头像组件。"""
+
+    component_type: Literal["avatar"] = "avatar"
+    src: str = Field(..., description="头像的URL或Base64数据URI")
+    shape: Literal["circle", "square"] = Field("circle", description="头像形状")
+    size: int = Field(50, description="头像尺寸（像素）")
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/avatar"
+
+
+class AvatarGroup(RenderableComponent):
+    """一组堆叠的头像组件。"""
+
+    component_type: Literal["avatar_group"] = "avatar_group"
+    avatars: list[Avatar] = Field(default_factory=list, description="头像列表")
+    spacing: int = Field(-15, description="头像间的间距（负数表示重叠）")
+    max_count: int | None = Field(
+        None, description="最多显示的头像数量，超出部分会显示为'+N'"
+    )
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/avatar"

zhenxun/ui/models/components/kpi_card.py

@@ -0,0 +1,29 @@
+from typing import Any, Literal
+
+from pydantic import Field
+
+from ..core.base import RenderableComponent
+
+__all__ = ["KpiCard"]
+
+
+class KpiCard(RenderableComponent):
+    """一个用于展示关键性能指标（KPI）的统计卡片。"""
+
+    component_type: Literal["kpi_card"] = "kpi_card"
+    label: str = Field(..., description="指标的标签或名称")
+    value: Any = Field(..., description="指标的主要数值")
+    unit: str | None = Field(default=None, description="数值的单位，可选")
+    change: str | None = Field(
+        default=None, description="与上一周期的变化，例如 '+15%' 或 '-100'"
+    )
+    change_type: Literal["positive", "negative", "neutral"] = Field(
+        default="neutral", description="变化的类型，用于决定颜色"
+    )
+    icon_svg: str | None = Field(
+        default=None, description="卡片中显示的可选图标 (SVG path data)"
+    )
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/kpi_card"

zhenxun/ui/models/components/timeline.py

@@ -0,0 +1,30 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ..core.base import RenderableComponent
+
+__all__ = ["Timeline", "TimelineItem"]
+
+
+class TimelineItem(BaseModel):
+    """时间轴中的单个事件点。"""
+
+    timestamp: str = Field(..., description="显示在时间点旁边的时间或标签")
+    title: str = Field(..., description="事件的标题")
+    content: str = Field(..., description="事件的详细描述")
+    icon: str | None = Field(default=None, description="可选的自定义图标SVG路径")
+    color: str | None = Field(default=None, description="可选的自定义颜色，覆盖默认")
+
+
+class Timeline(RenderableComponent):
+    """一个垂直时间轴组件，用于按顺序展示事件。"""
+
+    component_type: Literal["timeline"] = "timeline"
+    items: list[TimelineItem] = Field(
+        default_factory=list, description="时间轴项目列表"
+    )
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/timeline"

zhenxun/ui/models/core/__init__.py

@@ -4,7 +4,10 @@
 """
 
 from .base import RenderableComponent
+from .card import CardData
+from .details import DetailsData, DetailsItem
 from .layout import LayoutData, LayoutItem
+from .list import ListData, ListItem
 from .markdown import (
     CodeElement,
     HeadingElement,
@@ -21,16 +24,22 @@ from .markdown import (
 from .notebook import NotebookData, NotebookElement
 from .table import BaseCell, ImageCell, StatusBadgeCell, TableCell, TableData, TextCell
 from .template import TemplateComponent
+from .text import TextData, TextSpan
 
 __all__ = [
     "BaseCell",
+    "CardData",
     "CodeElement",
+    "DetailsData",
+    "DetailsItem",
     "HeadingElement",
     "ImageCell",
     "ImageElement",
     "LayoutData",
     "LayoutItem",
+    "ListData",
     "ListElement",
+    "ListItem",
     "ListItemElement",
     "MarkdownData",
     "MarkdownElement",
@@ -45,5 +54,7 @@ __all__ = [
     "TableElement",
     "TemplateComponent",
     "TextCell",
+    "TextData",
     "TextElement",
+    "TextSpan",
 ]

zhenxun/ui/models/core/base.py

@@ -1,20 +1,29 @@
 from abc import ABC, abstractmethod
-import asyncio
-from collections.abc import Awaitable, Iterator
+from collections.abc import Awaitable, Iterable
 from typing import Any
 
-from nonebot.compat import model_dump
 from pydantic import BaseModel
 
 from zhenxun.services.renderer.protocols import Renderable
+from zhenxun.utils.pydantic_compat import compat_computed_field, model_dump
 
 __all__ = ["ContainerComponent", "RenderableComponent"]
 
 
 class RenderableComponent(BaseModel, Renderable):
-    """所有可渲染UI组件的抽象基类。"""
+    """
+    所有可渲染UI组件的数据模型基类。
+
+    它继承自 Pydantic 的 `BaseModel` 用于数据校验和结构化，同时实现了 `Renderable`
+    协议，确保其能够被 `RendererService` 正确处理。
+    它还提供了一些所有组件通用的样式属性，如 `inline_style`, `variant` 等。
+    """
 
     _is_standalone_template: bool = False
+    inline_style: dict[str, str] | None = None
+    component_css: str | None = None
+    extra_classes: list[str] | None = None
+    variant: str | None = None
 
     @property
     def template_name(self) -> str:
@@ -30,6 +39,10 @@ class RenderableComponent(BaseModel, Renderable):
         """[可选] 生命周期钩子，默认无操作。"""
         pass
 
+    def get_children(self) -> Iterable["RenderableComponent"]:
+        """默认实现：非容器组件没有子组件。"""
+        return []
+
     def get_required_scripts(self) -> list[str]:
         """[可选] 返回此组件所需的JS脚本路径列表 (相对于assets目录)。"""
         return []
@@ -40,9 +53,18 @@ class RenderableComponent(BaseModel, Renderable):
 
     def get_render_data(self) -> dict[str, Any | Awaitable[Any]]:
         """默认实现，返回模型自身的数据字典。"""
-        return model_dump(self)
+        return model_dump(
+            self, exclude={"inline_style", "component_css", "inline_style_str"}
+        )
 
-    def get_extra_css(self, theme_manager: Any) -> str | Awaitable[str]:
+    @compat_computed_field
+    def inline_style_str(self) -> str:
+        """[新增] 一个辅助属性，将内联样式字典转换为CSS字符串"""
+        if not self.inline_style:
+            return ""
+        return "; ".join(f"{k}: {v}" for k, v in self.inline_style.items())
+
+    def get_extra_css(self, context: Any) -> str | Awaitable[str]:
         return ""
 
 
@@ -52,37 +74,24 @@ class ContainerComponent(RenderableComponent, ABC):
     """
 
     @abstractmethod
-    def _get_renderable_child_items(self) -> Iterator[Any]:
+    def get_children(self) -> Iterable[RenderableComponent]:
         """
-        一个抽象方法，子类必须实现它来返回一个可迭代的对象。
-        迭代器中的每个项目都必须具有 'component' 和 'html_content' 属性。
+        一个抽象方法，子类必须实现它来返回一个可迭代的子组件。
         """
         raise NotImplementedError
 
-    async def prepare(self) -> None:
-        """
-        通用的 prepare 方法，负责预渲染所有子组件。
-        """
-        from zhenxun.services import renderer_service
+    def get_required_scripts(self) -> list[str]:
+        """[新增] 聚合所有子组件的脚本依赖。"""
+        scripts = set(super().get_required_scripts())
+        for child in self.get_children():
+            if child:
+                scripts.update(child.get_required_scripts())
+        return list(scripts)
 
-        child_items = list(self._get_renderable_child_items())
-        if not child_items:
-            return
-
-        components_to_render = [
-            item.component for item in child_items if item.component
-        ]
-
-        prepare_tasks = [
-            comp.prepare() for comp in components_to_render if hasattr(comp, "prepare")
-        ]
-        if prepare_tasks:
-            await asyncio.gather(*prepare_tasks)
-
-        render_tasks = [
-            renderer_service.render_to_html(comp) for comp in components_to_render
-        ]
-        rendered_htmls = await asyncio.gather(*render_tasks)
-
-        for item, html in zip(child_items, rendered_htmls):
-            item.html_content = html
+    def get_required_styles(self) -> list[str]:
+        """[新增] 聚合所有子组件的样式依赖。"""
+        styles = set(super().get_required_styles())
+        for child in self.get_children():
+            if child:
+                styles.update(child.get_required_styles())
+        return list(styles)

zhenxun/ui/models/core/card.py

@@ -0,0 +1,24 @@
+from collections.abc import Iterable
+
+from .base import ContainerComponent, RenderableComponent
+
+
+class CardData(ContainerComponent):
+    """通用卡片的数据模型，可以包含头部、内容和尾部"""
+
+    header: RenderableComponent | None = None
+    content: RenderableComponent
+    footer: RenderableComponent | None = None
+
+    @property
+    def template_name(self) -> str:
+        return "components/core/card"
+
+    def get_children(self) -> Iterable[RenderableComponent]:
+        """让CSS收集器能够遍历卡片的子组件"""
+        if self.header:
+            yield self.header
+        if self.content:
+            yield self.content
+        if self.footer:
+            yield self.footer

zhenxun/ui/models/core/details.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .base import RenderableComponent
+
+
+class DetailsItem(BaseModel):
+    """描述列表中的单个项目"""
+
+    label: str = Field(..., description="项目的标签/键")
+    value: Any = Field(..., description="项目的值")
+
+
+class DetailsData(RenderableComponent):
+    """描述列表（键值对）的数据模型"""
+
+    title: str | None = Field(None, description="列表的可选标题")
+    items: list[DetailsItem] = Field(default_factory=list, description="键值对项目列表")
+
+    @property
+    def template_name(self) -> str:
+        return "components/core/details"

zhenxun/ui/models/core/layout.py

@@ -1,3 +1,4 @@
+from collections.abc import Iterable
 from typing import Any
 
 from pydantic import BaseModel, Field
@@ -12,7 +13,6 @@ class LayoutItem(BaseModel):
 
     component: RenderableComponent = Field(..., description="要渲染的组件的数据模型")
     metadata: dict[str, Any] | None = Field(None, description="传递给模板的额外元数据")
-    html_content: str | None = None
 
 
 class LayoutData(ContainerComponent):
@@ -27,23 +27,26 @@ class LayoutData(ContainerComponent):
         default_factory=dict, description="传递给模板的选项"
     )
 
-    def get_required_scripts(self) -> list[str]:
-        """[新增] 聚合所有子组件的脚本依赖。"""
-        scripts = set()
-        for item in self.children:
-            scripts.update(item.component.get_required_scripts())
-        return list(scripts)
-
-    def get_required_styles(self) -> list[str]:
-        """[新增] 聚合所有子组件的样式依赖。"""
-        styles = set()
-        for item in self.children:
-            styles.update(item.component.get_required_styles())
-        return list(styles)
-
     @property
     def template_name(self) -> str:
-        return f"layouts/{self.layout_type}"
+        return f"components/core/layouts/{self.layout_type}"
 
-    def _get_renderable_child_items(self):
-        yield from self.children
+    def get_extra_css(self, context: Any) -> str:
+        """聚合所有子组件的 extra_css。"""
+        all_css = []
+        if self.component_css:
+            all_css.append(self.component_css)
+
+        for item in self.children:
+            if (
+                item.component
+                and hasattr(item.component, "component_css")
+                and item.component.component_css
+            ):
+                all_css.append(item.component.component_css)
+
+        return "\n".join(all_css)
+
+    def get_children(self) -> Iterable[RenderableComponent]:
+        for item in self.children:
+            yield item.component

zhenxun/ui/models/core/list.py

@@ -0,0 +1,30 @@
+from collections.abc import Iterable
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from .base import ContainerComponent, RenderableComponent
+
+__all__ = ["ListData", "ListItem"]
+
+
+class ListItem(BaseModel):
+    """列表中的单个项目，其内容可以是任何可渲染组件。"""
+
+    component: RenderableComponent = Field(..., description="要渲染的组件的数据模型")
+
+
+class ListData(ContainerComponent):
+    """通用列表的数据模型，支持有序和无序列表。"""
+
+    component_type: Literal["list"] = "list"
+    items: list[ListItem] = Field(default_factory=list, description="列表项目")
+    ordered: bool = Field(default=False, description="是否为有序列表")
+
+    @property
+    def template_name(self) -> str:
+        return "components/core/list"
+
+    def get_children(self) -> Iterable[RenderableComponent]:
+        for item in self.items:
+            yield item.component

zhenxun/ui/models/core/markdown.py

@@ -1,16 +1,18 @@
 from abc import ABC, abstractmethod
+from collections.abc import Iterable
 from pathlib import Path
-from typing import Literal
+from typing import Any, Literal
 
 import aiofiles
 from pydantic import BaseModel, Field
 
 from zhenxun.services.log import logger
 
-from .base import RenderableComponent
+from .base import ContainerComponent, RenderableComponent
 
 __all__ = [
     "CodeElement",
+    "ComponentElement",
     "HeadingElement",
     "ImageElement",
     "ListElement",
@@ -32,6 +34,7 @@ class MarkdownElement(BaseModel, ABC):
 
 
 class TextElement(MarkdownElement):
+    type: Literal["text"] = "text"
     text: str
 
     def to_markdown(self) -> str:
@@ -39,6 +42,7 @@ class TextElement(MarkdownElement):
 
 
 class HeadingElement(MarkdownElement):
+    type: Literal["heading"] = "heading"
     text: str
     level: int = Field(..., ge=1, le=6)
 
@@ -47,6 +51,7 @@ class HeadingElement(MarkdownElement):
 
 
 class ImageElement(MarkdownElement):
+    type: Literal["image"] = "image"
     src: str
     alt: str = "image"
 
@@ -55,6 +60,7 @@ class ImageElement(MarkdownElement):
 
 
 class CodeElement(MarkdownElement):
+    type: Literal["code"] = "code"
     code: str
     language: str = ""
 
@@ -63,6 +69,7 @@ class CodeElement(MarkdownElement):
 
 
 class RawHtmlElement(MarkdownElement):
+    type: Literal["raw_html"] = "raw_html"
     html: str
 
     def to_markdown(self) -> str:
@@ -70,6 +77,7 @@ class RawHtmlElement(MarkdownElement):
 
 
 class TableElement(MarkdownElement):
+    type: Literal["table"] = "table"
     headers: list[str]
     rows: list[list[str]]
     alignments: list[Literal["left", "center", "right"]] | None = None
@@ -98,6 +106,8 @@ class ContainerElement(MarkdownElement):
 
 
 class QuoteElement(ContainerElement):
+    type: Literal["quote"] = "quote"
+
     def to_markdown(self) -> str:
         inner_md = "\n".join(part.to_markdown() for part in self.content)
         return "\n".join([f"> {line}" for line in inner_md.split("\n")])
@@ -109,6 +119,7 @@ class ListItemElement(ContainerElement):
 
 
 class ListElement(ContainerElement):
+    type: Literal["list"] = "list"
     ordered: bool = False
 
     def to_markdown(self) -> str:
@@ -121,11 +132,21 @@ class ListElement(ContainerElement):
         return "\n".join(lines)
 
 
-class MarkdownData(RenderableComponent):
+class ComponentElement(MarkdownElement):
+    """一个特殊的元素，用于在Markdown流中持有另一个可渲染组件。"""
+
+    type: Literal["component"] = "component"
+    component: RenderableComponent
+
+    def to_markdown(self) -> str:
+        return ""
+
+
+class MarkdownData(ContainerComponent):
     """Markdown转图片的数据模型"""
 
     style_name: str | None = None
-    markdown: str
+    elements: list[MarkdownElement] = Field(default_factory=list)
     width: int = 800
     css_path: str | None = None
 
@@ -133,7 +154,23 @@ class MarkdownData(RenderableComponent):
     def template_name(self) -> str:
         return "components/core/markdown"
 
-    async def get_extra_css(self, theme_manager) -> str:
+    def get_children(self) -> Iterable[RenderableComponent]:
+        """让CSS/JS依赖收集器能够递归地找到所有嵌入的组件。"""
+
+        def find_components_recursive(
+            elements: list[MarkdownElement],
+        ) -> Iterable[RenderableComponent]:
+            for element in elements:
+                if isinstance(element, ComponentElement):
+                    yield element.component
+                    if hasattr(element.component, "get_children"):
+                        yield from element.component.get_children()
+                elif isinstance(element, ContainerElement):
+                    yield from find_components_recursive(element.content)
+
+        yield from find_components_recursive(self.elements)
+
+    async def get_extra_css(self, context: Any) -> str:
         if self.css_path:
             css_file = Path(self.css_path)
             if css_file.is_file():
@@ -142,14 +179,12 @@ class MarkdownData(RenderableComponent):
             else:
                 logger.warning(f"Markdown自定义CSS文件不存在: {self.css_path}")
         else:
-            style_name = self.style_name or "github-light"
-            css_path = (
-                theme_manager.current_theme.default_assets_dir
-                / "css"
-                / "markdown"
-                / f"{style_name}.css"
+            style_name = self.style_name or "light"
+            # 使用上下文对象来解析路径
+            css_path = await context.theme_manager.resolve_markdown_style_path(
+                style_name, context
             )
-            if css_path.exists():
+            if css_path and css_path.exists():
                 async with aiofiles.open(css_path, encoding="utf-8") as f:
                     return await f.read()
         return ""

zhenxun/ui/models/core/notebook.py

@@ -1,3 +1,4 @@
+from collections.abc import Iterable
 from typing import Literal
 
 from pydantic import BaseModel
@@ -29,7 +30,6 @@ class NotebookElement(BaseModel):
     data: list[str] | None = None
     ordered: bool | None = None
     component: RenderableComponent | None = None
-    html_content: str | None = None
 
 
 class NotebookData(ContainerComponent):
@@ -42,7 +42,7 @@ class NotebookData(ContainerComponent):
     def template_name(self) -> str:
         return "components/core/notebook"
 
-    def _get_renderable_child_items(self):
+    def get_children(self) -> Iterable[RenderableComponent]:
         for element in self.elements:
             if element.type == "component" and element.component:
-                yield element
+                yield element.component

zhenxun/ui/models/core/table.py

@@ -2,11 +2,13 @@ from typing import Literal
 
 from pydantic import BaseModel, Field
 
+from ...models.components.progress_bar import ProgressBar
 from .base import RenderableComponent
 
 __all__ = [
     "BaseCell",
     "ImageCell",
+    "ProgressBarCell",
     "StatusBadgeCell",
     "TableCell",
     "TableData",
@@ -48,7 +50,15 @@ class StatusBadgeCell(BaseCell):
     status_type: Literal["ok", "error", "warning", "info"] = "info"
 
 
-TableCell = TextCell | ImageCell | StatusBadgeCell | str | int | float | None
+class ProgressBarCell(BaseCell, ProgressBar):
+    """进度条单元格，继承ProgressBar模型以复用其字段"""
+
+    type: Literal["progress_bar"] = "progress_bar"  # type: ignore
+
+
+TableCell = (
+    TextCell | ImageCell | StatusBadgeCell | ProgressBarCell | str | int | float | None
+)
 
 
 class TableData(RenderableComponent):
@@ -59,6 +69,12 @@ class TableData(RenderableComponent):
     tip: str | None = Field(None, description="表格下方的提示信息")
     headers: list[str] = Field(default_factory=list, description="表头列表")
     rows: list[list[TableCell]] = Field(default_factory=list, description="数据行列表")
+    column_alignments: list[Literal["left", "center", "right"]] | None = Field(
+        default=None, description="每列的对齐方式"
+    )
+    column_widths: list[str | int] | None = Field(
+        default=None, description="每列的宽度 (e.g., ['50px', 'auto', 100])"
+    )
 
     @property
     def template_name(self) -> str:

zhenxun/ui/models/core/template.py

@@ -23,3 +23,12 @@ class TemplateComponent(RenderableComponent):
     def get_render_data(self) -> dict[str, Any]:
         """返回传递给模板的数据"""
         return self.data
+
+    def __getattr__(self, name: str) -> Any:
+        """允许直接访问 `data` 字典中的属性。"""
+        try:
+            return self.data[name]
+        except KeyError:
+            raise AttributeError(
+                f"'{type(self).__name__}' 对象没有属性 '{name}'"
+            ) from None

zhenxun/ui/models/core/text.py

@@ -0,0 +1,32 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from .base import RenderableComponent
+
+
+class TextSpan(BaseModel):
+    """单个富文本片段的数据模型"""
+
+    text: str
+    bold: bool = False
+    italic: bool = False
+    underline: bool = False
+    strikethrough: bool = False
+    code: bool = False
+    color: str | None = None
+    font_size: str | None = None
+    font_family: str | None = None
+
+
+class TextData(RenderableComponent):
+    """轻量级富文本组件的数据模型"""
+
+    spans: list[TextSpan] = Field(default_factory=list, description="文本片段列表")
+    align: Literal["left", "right", "center"] = Field(
+        "left", description="整体文本对齐方式"
+    )
+
+    @property
+    def template_name(self) -> str:
+        return "components/core/text"

zhenxun/ui/models/presets/__init__.py

@@ -3,16 +3,12 @@
 包含预定义的复合组件数据模型
 """
 
-from .card import InfoCardData, InfoCardMetadataItem, InfoCardSection
-from .help_page import HelpCategory, HelpItem, PluginHelpPageData
+from .plugin_help_page import HelpCategory, HelpItem, PluginHelpPageData
 from .plugin_menu import PluginMenuCategory, PluginMenuData, PluginMenuItem
 
 __all__ = [
     "HelpCategory",
     "HelpItem",
-    "InfoCardData",
-    "InfoCardMetadataItem",
-    "InfoCardSection",
     "PluginHelpPageData",
     "PluginMenuCategory",
     "PluginMenuData",

zhenxun/ui/models/presets/card.py

@@ -1,36 +0,0 @@
-from pydantic import BaseModel, Field
-
-from ..core.base import RenderableComponent
-
-__all__ = [
-    "InfoCardData",
-    "InfoCardMetadataItem",
-    "InfoCardSection",
-]
-
-
-class InfoCardMetadataItem(BaseModel):
-    """信息卡片元数据项"""
-
-    label: str
-    value: str | int
-
-
-class InfoCardSection(BaseModel):
-    """信息卡片内容区块"""
-
-    title: str
-    content: list[str] = Field(..., description="内容段落列表")
-
-
-class InfoCardData(RenderableComponent):
-    """通用信息卡片的数据模型"""
-
-    style_name: str | None = None
-    title: str = Field(..., description="卡片主标题")
-    metadata: list[InfoCardMetadataItem] = Field(default_factory=list)
-    sections: list[InfoCardSection] = Field(default_factory=list)
-
-    @property
-    def template_name(self) -> str:
-        return "components/presets/info_card"

zhenxun/ui/models/presets/plugin_help_page.py

@@ -35,4 +35,4 @@ class PluginHelpPageData(RenderableComponent):
 
     @property
     def template_name(self) -> str:
-        return "pages/core/help_page"
+        return "pages/core/plugin_help_page"