From 41f59dda7226d284115d2353c25a5b98fcf6ef7a Mon Sep 17 00:00:00 2001
From: skycurtain <skycurtain@163.com>
Date: Fri, 8 May 2026 09:38:25 +0800
Subject: [PATCH] =?UTF-8?q?feat(schema):=20=E6=89=A9=E5=B1=95=20CSSPropert?=
 =?UTF-8?q?ies=20=E7=B1=BB=E5=9E=8B=E5=B9=B6=E5=AE=8C=E5=96=84=E7=BB=84?=
 =?UTF-8?q?=E4=BB=B6=E6=8E=A5=E5=8F=A3=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 将 CSSProperties 的值类型从 string 扩展为 string | number | undefined，以支持更灵活的样式定义
- 为 Component 接口的 style 和 props 字段添加详细注释，明确其设计意图和使用规范
- 移除已完成的 TODO 注释
---
 src/schema/component/component.ts   | 18 ++++++++++++++++++
 src/schema/shared/css-properties.ts |  3 +--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/src/schema/component/component.ts b/src/schema/component/component.ts
index 29f708b..18402ef 100644
--- a/src/schema/component/component.ts
+++ b/src/schema/component/component.ts
@@ -28,7 +28,25 @@ export interface Component extends Entity {
    */
   condition?: Condition;
   layout: ComponentLayout;
+  /**
+   * 组件通用样式
+   *
+   * 承载跨组件通用的、标准的 CSS 视觉属性，仅作用于组件的最外层 DOM 容器。
+   * 必须为静态键值对，不支持动态表达式（DynamicExpression），以保证渲染性能并斩断“无意义的 React 渲染瀑布”。
+   * 任何基于数据流或业务状态的动态视觉变化，应通过 props 或事件触发的 Action 来实现。
+   *
+   * @example { backgroundColor: '#fff', borderRadius: 4, boxShadow: '0 2px 4px rgba(0,0,0,0.1)' }
+   */
   style: CSSProperties;
+  /**
+   * 组件私有属性
+   *
+   * 承载与具体组件类型（type）强绑定的业务语义、内部结构和私有状态。
+   * 支持动态表达式（DynamicExpression），允许属性值随数据流或环境变量动态变化。
+   * 如果组件没有任何自定义属性，该值必须为空对象 `{}`，以消除空值检查成本。
+   *
+   * @example { text: '提交', disabled: false, size: 'large', type: 'primary' }
+   */
   props: Record<string, ComponentPropValue>;
   /**
    * 图层管理属性
diff --git a/src/schema/shared/css-properties.ts b/src/schema/shared/css-properties.ts
index 952bc9b..c012eab 100644
--- a/src/schema/shared/css-properties.ts
+++ b/src/schema/shared/css-properties.ts
@@ -1,4 +1,3 @@
-// TODO: 完善 CSSProperties 接口
 export interface CSSProperties {
-  [key: string]: string;
+  [key: string]: string | number | undefined;
 }