Skip to Content
文档概念元件系统

声明式元件系统

声明式元件系统是 PSUIP 的核心组成部分，将 UI 的最小单元（按钮、输入框、图标等）以”声明式数据”形式定义，并通过八要素描述其各种状态和形态。

元件概念与设计原则

声明式元件定义

声明式元件是将 UI 最小单元以”声明式数据”形式定义的组件，具备以下特性：

  • 数据驱动：元件的所有属性通过 JSON 数据声明
  • 状态完备：支持所有可能的交互状态和视觉变体
  • Token 绑定：所有样式属性通过 Design Token 引用

核心设计原则

1. 高内聚、低耦合

  • 每个元件自包含所有样式和事件定义
  • 避免外部依赖，确保元件的独立性
  • 复杂布局由容器（底板）和多个元件组合实现

2. 通用性与可塑性

  • 支持跨平台、跨场景复用
  • 对样式可由 AI 动态调节，具备”可塑”属性
  • 通过变体和状态组合支持多样化需求

3. 最小化原则

以尽可能少的元件类型，覆盖尽可能多的现有和潜在交互模式。

元件状态与形态

状态定义

元件根据使用场景支持以下状态：

type ElementState = 
  | 'default'           // 默认状态
  | 'hover'            // 悬停状态
  | 'active'           // 激活状态
  | 'pressed'          // 按下状态
  | 'disabled'         // 禁用状态
  | 'loading'          // 加载状态

元件状态对照表

元件类型DefaultHoverActivePressedDisabledLoading
按钮✅✅✅✅✅✅
文本输入✅✅✅❌✅❌
文字✅✅❌❌✅❌
图标✅✅✅❌✅❌
头像✅✅❌❌✅✅
进度条✅❌❌❌✅✅
文本提示✅❌❌❌❌❌
徽标✅✅❌❌✅❌
图像✅✅❌❌✅✅

形态变体

每个元件支持多种形态变体，通过命名规范进行区分：

{元件名_变体名}

按钮元件示例：

  • button_normal - 标准按钮
  • button_icontextbutton - 图标文字按钮
  • button_iconbutton - 纯图标按钮

设计表达工具链

Figma + Token Studio 工作流

声明式元件的设计和创建在 Figma 的 Token Studio 插件中进行：

1. 导入样式字典

// 导入 basic 样式字典（系统默认主题）
{
  "dimension": {
    "borderradius": {
      "small": { "value": "4px", "type": "borderRadius" },
      "medium": { "value": "8px", "type": "borderRadius" },
      "large": { "value": "16px", "type": "borderRadius" }
    }
  },
  "color": {
    "primary": {
      "brand3": { "value": "#0ea5e9", "type": "color" },
      "brand5": { "value": "#0284c7", "type": "color" }
    }
  }
}

2. 创建新元件

  1. 右键点击样式字典名
  2. 选择 “Treat as Source” 设为数据源
  3. 点击 ”+ New Set” 按钮
  4. 输入元件名称完成创建

3. 声明元件形态

  • 每个元件使用专用 Section
  • Section 中包含多个 Frame，每个 Frame 是一个变体
  • Frame 命名格式：{元件名_变体名}
Section: Button
├── Frame: button_normal
├── Frame: button_icontextbutton  
└── Frame: button_iconbutton

4. 声明元件状态

所有 token 命名遵循规范：

{通用属性.八要素_子属性/图元.分隔符.事件类型_状态}

示例：

color-bg-state-default
color-bg-state-hover
color-bg-state-active
scale-padding-state-default

数据表示格式

组件描述符结构

组件资产采用声明式 JSON表示，由组件描述符和若干属性域构成：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "button",
  "name-zh": "按钮",
  "file-type": "cell-element",
  "layout": { ... },
  "color": { ... },
  "shape": { ... },
  "scale": { ... },
  "font": { ... },
  "material": { ... },
  "sound": { ... }
}

属性域结构

Layout 域 - 形态变体

"layout": {
  "style": {
    // 形态无关的基线样式集合
    "display": { "value": "flex", "type": "other" },
    "align-items": { "value": "center", "type": "other" }
  },
  "button_normal": {
    // 标准按钮变体特定样式
    "min-width": { "value": "80px", "type": "sizing" }
  },
  "button_iconbutton": {
    // 图标按钮变体特定样式
    "width": { "value": "40px", "type": "sizing" },
    "height": { "value": "40px", "type": "sizing" }
  }
}

其他属性域 - 状态驱动

"color": {
  "bg": {
    "default": {
      "data-key": "color-bg-state-default",
      "style": {
        "background-color": { 
          "value": "{color.primary.brand5}", 
          "type": "color",
          "key": "color-bg" 
        }
      },
      "resource": "{color.primary.brand5}"
    },
    "hover": {
      "data-key": "color-bg-state-hover",
      "style": {
        "background-color": { 
          "value": "{color.primary.brand3}", 
          "type": "color",
          "key": "color-bg" 
        }
      },
      "resource": "{color.primary.brand3}"
    },
    "active": {
      "data-key": "color-bg-state-active", 
      "style": {
        "background-color": { 
          "value": "{color.primary.brand6}", 
          "type": "color",
          "key": "color-bg" 
        }
      },
      "resource": "{color.primary.brand6}"
    }
  }
}

完整按钮元件示例

{
  "id": "button-component-uuid",
  "name": "button",
  "name-zh": "按钮",
  "file-type": "cell-element",
  "layout": {
    "style": {
      "display": { "value": "inline-flex", "type": "other" },
      "align-items": { "value": "center", "type": "other" },
      "justify-content": { "value": "center", "type": "other" },
      "cursor": { "value": "pointer", "type": "other" }
    },
    "button_normal": {
      "min-width": { "value": "80px", "type": "sizing" },
      "padding": { "value": "8px 16px", "type": "spacing" }
    }
  },
  "color": {
    "bg": {
      "default": {
        "style": {
          "background-color": { "value": "{color.primary.brand5}", "type": "color" }
        }
      },
      "hover": {
        "style": {
          "background-color": { "value": "{color.primary.brand4}", "type": "color" }
        }
      },
      "disabled": {
        "style": {
          "background-color": { "value": "{color.neutral.gray3}", "type": "color" }
        }
      }
    },
    "text": {
      "default": {
        "style": {
          "color": { "value": "{color.neutral.white}", "type": "color" }
        }
      },
      "disabled": {
        "style": {
          "color": { "value": "{color.neutral.gray6}", "type": "color" }
        }
      }
    }
  },
  "shape": {
    "border-radius": {
      "default": {
        "style": {
          "border-radius": { "value": "{shape.borderradius.medium}", "type": "borderRadius" }
        }
      }
    }
  },
  "font": {
    "size": {
      "default": {
        "style": {
          "font-size": { "value": "{font.size.base}", "type": "fontSizes" }
        }
      }
    },
    "weight": {
      "default": {
        "style": {
          "font-weight": { "value": "{font.weight.medium}", "type": "fontWeights" }
        }
      }
    }
  }
}

元件管理平台

平台功能

元件管理平台提供完整的元件生命周期管理：

  1. 元件上传：支持从 Figma 插件导出的标准格式
  2. 版本控制：管理元件的版本历史和变更记录
  3. 预览测试：提供实时预览和交互测试环境
  4. 发布分发：将元件分发到不同的使用环境

平台界面

元件在管理平台中的展示包括：

  • 元件基本信息（名称、描述、版本）
  • 变体预览（所有形态的可视化展示）
  • 状态演示（交互状态的动态预览）
  • Token 引用（关联的 Design Token 列表）
  • 使用文档（API 文档和使用示例）

声明式元件系统为 PSUIP 提供了强大而灵活的 UI 构建基础，通过科学的抽象和标准化的数据格式，实现了高效的 AI 驱动界面生成能力。

Last updated on
八要素模型通用 Markdown 语法