✨ feat(ui): 增强表格构建器并完善组件模型文档 (#2048)

* ✨ feat(table): 添加 ComponentCell 以支持表格单元格中嵌入可渲染组件

* ✨ feat(ui): 增强表格构建器并完善组件模型文档

- 增强 `TableBuilder`，新增 `_normalize_cell` 辅助方法，支持自动将原生数据类型（如 `str`, `int`, `Path`）转换为 `TableCell` 模型，简化了表格行的创建。
- 完善 `zhenxun/ui/models` 目录下所有组件模型字段的 `description` 属性和文档字符串，显著提升了代码可读性和开发者体验。
- 优化 `shop/_data_source.py` 中 `gold_rank` 函数的平台路径判断格式，并统一 `my_props` 函数中图标路径的处理逻辑。

* 🚨 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/models/core/table.py

@@ -1,8 +1,6 @@
-from pathlib import Path
 from typing import Literal
 
-from nonebot.compat import field_validator
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from ...models.components.progress_bar import ProgressBar
 from .base import RenderableComponent
@@ -10,6 +8,7 @@ from .text import TextSpan
 
 __all__ = [
     "BaseCell",
+    "ComponentCell",
     "ImageCell",
     "ProgressBarCell",
     "RichTextCell",
@@ -30,7 +29,7 @@ class TextCell(BaseCell):
     """文本单元格"""
 
     type: Literal["text"] = "text"  # type: ignore
-    content: str | float
+    content: str
     bold: bool = False
     color: str | None = None
 
@@ -39,18 +38,12 @@ class ImageCell(BaseCell):
     """图片单元格"""
 
     type: Literal["image"] = "image"  # type: ignore
-    src: str | Path
+    src: str
     width: int = 40
     height: int = 40
     shape: Literal["square", "circle"] = "square"
     alt: str = "image"
 
-    @field_validator("src", mode="before")
-    def validate_src(cls, v: str) -> str:
-        if isinstance(v, Path):
-            v = v.resolve().as_uri()
-        return v
-
 
 class StatusBadgeCell(BaseCell):
     """状态徽章单元格"""
@@ -70,20 +63,28 @@ class RichTextCell(BaseCell):
     """富文本单元格，支持多个带样式的文本片段"""
 
     type: Literal["rich_text"] = "rich_text"  # type: ignore
-    spans: list[TextSpan] = []
+    spans: list[TextSpan] = Field(default_factory=list, description="文本片段列表")
     """文本片段列表"""
-    direction: Literal["column", "row"] = "column"
+    direction: Literal["column", "row"] = Field("column", description="片段排列方向")
     """片段排列方向"""
-    gap: str = "4px"
+    gap: str = Field("4px", description="片段之间的间距")
     """片段之间的间距"""
 
 
+class ComponentCell(BaseCell):
+    """一个通用的单元格，可以容纳任何可渲染的组件。"""
+
+    type: str = "component"
+    component: RenderableComponent
+
+
 TableCell = (
     TextCell
     | ImageCell
     | StatusBadgeCell
     | ProgressBarCell
     | RichTextCell
+    | ComponentCell
     | str
     | int
     | float
@@ -95,17 +96,22 @@ class TableData(RenderableComponent):
     """通用表格的数据模型"""
 
     style_name: str | None = None
-    title: str
+    """应用于表格容器的样式名称"""
+    title: str = Field(..., description="表格主标题")
     """表格主标题"""
-    tip: str | None = None
+    tip: str | None = Field(None, description="表格下方的提示信息")
     """表格下方的提示信息"""
-    headers: list[str] = []  # noqa: RUF012
+    headers: list[str] = Field(default_factory=list, description="表头列表")
     """表头列表"""
-    rows: list[list[TableCell]] = []  # noqa: RUF012
+    rows: list[list[TableCell]] = Field(default_factory=list, description="数据行列表")
     """数据行列表"""
-    column_alignments: list[Literal["left", "center", "right"]] | None = None
+    column_alignments: list[Literal["left", "center", "right"]] | None = Field(
+        default=None, description="每列的对齐方式"
+    )
     """每列的对齐方式"""
-    column_widths: list[str | int] | None = None
+    column_widths: list[str | int] | None = Field(
+        default=None, description="每列的宽度 (e.g., ['50px', 'auto', 100])"
+    )
     """每列的宽度 (e.g., ['50px', 'auto', 100])"""
 
     @property