UI-DSL数据格式详解

1. 概述

UI-DSL（User Interface Domain Specific Language）是本系统的核心数据格式，用于描述UI界面的结构和样式。它是一种基于JSON的结构化数据格式，能够精确描述页面的布局、组件、主题等信息。

2. DSL整体结构

2.1 顶层结构

{
  "page": {
    "name": "页面名称",
    "theme": "主题名称",
    "layout": { /* 布局配置 */ },
    "sections": [ /* 页面区块列表 */ ]
  }
}

2.2 字段说明

字段	类型	必需	说明
`page`	Object	是	页面根对象
`page.name`	String	是	页面名称，用于标识页面类型
`page.theme`	String	是	主题名称，决定整体视觉风格
`page.layout`	Object	是	页面布局配置
`page.sections`	Array	是	页面区块列表，定义页面内容

3. 布局配置（Layout）

3.1 布局结构

{
  "layout": {
    "grid": 12,           // 网格系统列数
    "gutter": 16,         // 网格间距（像素）
    "padding": 16,        // 页面内边距（像素）
    "bg": "#0E0E0E"       // 页面背景色（十六进制）
  }
}

3.2 布局参数详解

参数	类型	默认值	说明
`grid`	Integer	12	网格系统列数，用于响应式布局
`gutter`	Integer	16	网格间距，控制组件间的水平间距
`padding`	Integer	16	页面内边距，控制页面边缘留白
`bg`	String	"#FFFFFF"	页面背景色，支持十六进制颜色值

4. 页面区块（Sections）

4.1 区块结构

每个区块包含以下字段：

{
  "type": "区块类型",
  "props": {
    // 区块特定的属性配置
  }
}

4.2 支持的区块类型

系统支持13种不同类型的页面区块：

4.2.1 导航类组件

1. TopBar（顶部栏）

{
  "type": "topbar",
  "props": {
    "title": "页面标题",           // 页面标题文本
    "logo": "品牌名称",           // 品牌Logo文本
    "actions": ["search", "bell"] // 操作按钮列表
  }
}

2. Tabs（标签页）

{
  "type": "tabs",
  "props": {
    "items": ["出货", "求货"],     // 标签页文本列表
    "active": 0                   // 当前激活的标签索引
  }
}

3. TabBar（底部导航栏）

{
  "type": "tabbar",
  "props": {
    "items": ["home", "search", "plus", "message", "user"]
  }
}

4.2.2 内容展示类组件

4. CardList（卡片列表）

{
  "type": "card-list",
  "props": {
    "columns": 2,                 // 列数（1或2）
    "card": {
      "type": "product-card"      // 卡片类型
    }
  }
}

5. Carousel（轮播图）

{
  "type": "carousel",
  "props": {
    "images": 3                   // 图片数量
  }
}

6. Price（价格展示）

{
  "type": "price",
  "props": {
    "value": "￥1999",            // 当前价格
    "original": "￥2999"          // 原价（可选）
  }
}

7. Seller（卖家信息）

{
  "type": "seller",
  "props": {
    "name": "优质卖家",           // 卖家名称
    "trust": "KYC已认证"         // 信任标识
  }
}

8. Proof（凭证信息）

{
  "type": "proof",
  "props": {
    "items": ["发票", "订单截图", "序列号"]  // 凭证项目列表
  }
}

4.2.3 交互类组件

9. CTA（行动按钮）

{
  "type": "cta",
  "props": {
    "buttons": ["联系卖家", "立即下单"]  // 按钮文本列表
  }
}

10. Form（表单）

{
  "type": "form",
  "props": {
    "fields": ["title", "price", "description", "images"]  // 表单字段列表
  }
}

11. Filters（筛选器）

{
  "type": "filters",
  "props": {
    "items": ["价格", "品牌", "地区"]  // 筛选项列表
  }
}

4.2.4 用户信息类组件

12. UserInfo（用户信息）

{
  "type": "user-info",
  "props": {
    "name": "用户名",             // 用户名称
    "level": "VIP",              // 用户等级
    "avatar": true               // 是否显示头像
  }
}

13. MenuList（菜单列表）

{
  "type": "menu-list",
  "props": {
    "items": ["我的订单", "我的收藏", "设置", "帮助"]  // 菜单项列表
  }
}

5. 主题系统

5.1 支持的主题

系统内置三种主题：

obsidian-gold（黑金主题）
silver-white（白银主题）
minimal（简约主题）

5.2 主题配置结构

主题配置存储在 config/ui_tokens.json 中，包含以下部分：

{
  "themes": {
    "obsidian-gold": {
      "name": "黑金主题",
      "colors": {
        "primary": "#FFD700",        // 主色调
        "secondary": "#B8860B",      // 辅助色
        "background": "#0E0E0E",     // 背景色
        "surface": "#1A1A1A",        // 表面色
        "text": "#FFFFFF",           // 文本色
        "text_secondary": "#CCCCCC", // 次要文本色
        "border": "#333333",         // 边框色
        "accent": "#FF6B35",         // 强调色
        "success": "#4CAF50",        // 成功色
        "warning": "#FF9800",        // 警告色
        "error": "#F44336"           // 错误色
      },
      "typography": {
        "font_family": "PingFang SC, -apple-system, BlinkMacSystemFont, sans-serif",
        "font_size": {
          "xs": "12px",
          "sm": "14px",
          "base": "16px",
          "lg": "18px",
          "xl": "20px",
          "2xl": "24px",
          "3xl": "30px"
        },
        "font_weight": {
          "normal": "400",
          "medium": "500",
          "semibold": "600",
          "bold": "700"
        }
      },
      "spacing": {
        "xs": "4px",
        "sm": "8px",
        "md": "16px",
        "lg": "24px",
        "xl": "32px",
        "2xl": "48px"
      },
      "border_radius": {
        "sm": "4px",
        "md": "8px",
        "lg": "12px",
        "xl": "16px",
        "full": "50%"
      },
      "shadows": {
        "sm": "0 1px 2px rgba(0, 0, 0, 0.1)",
        "md": "0 4px 6px rgba(0, 0, 0, 0.1)",
        "lg": "0 10px 15px rgba(0, 0, 0, 0.1)",
        "xl": "0 20px 25px rgba(0, 0, 0, 0.1)"
      }
    }
  }
}

6. 完整示例

6.1 电商首页示例

{
  "page": {
    "name": "home_page",
    "theme": "obsidian-gold",
    "layout": {
      "grid": 12,
      "gutter": 16,
      "padding": 16,
      "bg": "#0E0E0E"
    },
    "sections": [
      {
        "type": "topbar",
        "props": {
          "logo": "品牌",
          "actions": ["search", "bell"]
        }
      },
      {
        "type": "tabs",
        "props": {
          "items": ["出货", "求货"],
          "active": 0
        }
      },
      {
        "type": "card-list",
        "props": {
          "columns": 2,
          "card": {
            "type": "product-card"
          }
        }
      },
      {
        "type": "tabbar",
        "props": {
          "items": ["home", "search", "plus", "message", "user"]
        }
      }
    ]
  }
}

6.2 商品详情页示例

{
  "page": {
    "name": "detail_page",
    "theme": "obsidian-gold",
    "layout": {
      "grid": 12,
      "gutter": 16,
      "padding": 16,
      "bg": "#0E0E0E"
    },
    "sections": [
      {
        "type": "topbar",
        "props": {
          "title": "商品详情",
          "actions": ["share", "favorite"]
        }
      },
      {
        "type": "carousel",
        "props": {
          "images": 3
        }
      },
      {
        "type": "price",
        "props": {
          "value": "￥1999",
          "original": "￥2999"
        }
      },
      {
        "type": "seller",
        "props": {
          "name": "优质卖家",
          "trust": "KYC已认证"
        }
      },
      {
        "type": "proof",
        "props": {
          "items": ["发票", "订单截图", "序列号"]
        }
      },
      {
        "type": "cta",
        "props": {
          "buttons": ["联系卖家", "立即下单"]
        }
      }
    ]
  }
}

7. 数据验证规则

7.1 必需字段验证

page 对象必须存在
page.name 必须是非空字符串
page.theme 必须是有效的主题名称
page.layout 必须包含所有必需字段
page.sections 必须是非空数组

7.2 类型验证

所有数值字段必须是正整数
颜色值必须是有效的十六进制格式
数组字段必须包含指定类型的元素
字符串字段不能为空

7.3 业务逻辑验证

columns 字段只能是 1 或 2
active 字段不能超过对应数组的长度
主题名称必须在支持的主题列表中
组件类型必须在支持的组件列表中

8. 扩展指南

8.1 添加新组件类型

在数据生成器中添加新组件的模板
在渲染器中实现新组件的渲染逻辑
更新组件类型验证规则
添加相应的文档说明

8.2 添加新主题

在 ui_tokens.json 中添加新主题配置
实现新主题的渲染逻辑
更新主题验证规则
提供主题预览和文档

8.3 自定义属性

每个组件都支持通过 props 字段添加自定义属性，系统会将这些属性传递给渲染器进行处理。

9. 最佳实践

9.1 命名规范

页面名称使用下划线分隔：home_page、detail_page
组件类型使用连字符分隔：card-list、user-info
属性名称使用驼峰命名：activeTab、productCards

9.2 结构设计

保持区块顺序的逻辑性：导航 → 内容 → 操作
合理使用嵌套结构，避免过深层级
保持配置的一致性，使用统一的命名规范

9.3 性能优化

避免不必要的重复配置
使用合理的默认值减少配置量
保持JSON结构的简洁性

10. 工具支持

10.1 数据生成工具

系统提供 UIDataGenerator 类用于自动生成DSL数据：

# 使用示例
generator = UIDataGenerator()
dataset = generator.generate_dataset(num_samples=1000)

10.2 数据验证工具

# 验证DSL数据
def validate_dsl(dsl_data):
    # 实现验证逻辑
    pass

10.3 数据转换工具

# 转换DSL到其他格式
def dsl_to_vue(dsl_data):
    # 转换为Vue组件
    pass

def dsl_to_image(dsl_data):
    # 转换为图片
    pass

通过理解UI-DSL数据格式，您可以更好地使用和扩展AI UI生成系统。这种结构化的数据格式为系统的灵活性和可扩展性提供了坚实的基础。