powerapps-yaml

Power Apps YAML — Vibe Coding 完整指南

适用场景

• 生成要粘贴到 Power Apps Studio 的 YAML 代码时
• 创建或修改 Power Apps 屏幕时
• 将设计转换为现代 Power Apps 控件时
• 使用 SharePoint 作为后端时

---

🔑 基本结构（pa.yaml Schema v3）

Power Apps Studio 要接受通过“Paste code”粘贴的 YAML，必须使用以下结构：

Screens:
    NombrePantalla:
        Properties:
            Fill: =SurfaceAlt
            OnVisible: |-
                =Set(varEjemplo, "hola")
        Children:
            - NombreControl:
                Control: TipoControl
                Variant: VarianteOpcional
                Properties:
                    X: =0
                    Y: =0
                    Width: =Parent.Width
                    Height: =100
                Children:
                    - ControlHijo:
                        Control: Text
                        Properties:
                            Text: ="Hola mundo"

结构规则

1. 顶层：始终以 Screens: 开头
2. 屏幕名称：必须与 Power Apps Studio 中的屏幕名称完全一致
3. 不要使用 Control: Screen：屏幕直接定义在 Screens: 下，不带 Control 属性
4. Children 是一个数组：每个子项以 - NombreControl: 开头
5. Control 和 Variant：定义在每个子项中，而不是屏幕中
6. 带 = 的值：所有属性开头都必须带 =：Text: ="Hola"、X: =0

---

🚨 现代控件的属性（重要）

Power Apps 使用名称与经典控件不同的现代控件。使用错误的名称会导致 PA2108: Unknown property 错误。

Text 控件（Label）

❌ 经典（不要使用）	✅ 现代（使用）
Color	FontColor
FontWeight	Weight

- lblEjemplo:
    Control: Text
    Properties:
        X: =0
        Y: =0
        Width: =200
        Height: =40
        Text: ="Hola"
        FontColor: =RGBA(0, 0, 0, 1)
        Size: =14
        Weight: =FontWeight.Bold
        Align: =Align.Center
        VerticalAlign: =VerticalAlign.Middle

Button 控件

❌ 经典（不要使用）	✅ 现代（使用）
Fill	BasePaletteColor
Color	FontColor
Size	FontSize
RadiusTopLeft/Right/etc	（不存在，使用 Fluent theme）

- btnEjemplo:
    Control: Button
    Properties:
        X: =0
        Y: =0
        Width: =200
        Height: =44
        Text: ="Click"
        BasePaletteColor: =BrandAccent
        FontColor: =TextOnAccent
        FontSize: =14
        FontWeight: =FontWeight.Semibold
        Appearance: ='ButtonCanvas.Appearance'.Primary
        OnSelect: =Notify("Clickeado")

Appearance 的值：

• 'ButtonCanvas.Appearance'.Primary — 主按钮
• 'ButtonCanvas.Appearance'.Secondary — 次要按钮
• 'ButtonCanvas.Appearance'.Transparent — 透明（适合覆盖层和返回按钮）

TextInput 控件

❌ 经典（不要使用）	✅ 现代（使用）
Default	Value
HintText / PlaceholderText	（现代控件中不存在）
Format	（现代控件中不存在）

- txtEjemplo:
    Control: TextInput
    Properties:
        X: =0
        Y: =0
        Width: =200
        Height: =44
        Value: =""
        Mode: =TextMode.MultiLine  # Opcional

DatePicker 控件

❌ 经典（不要使用）	✅ 现代（使用）
DefaultDate	SelectedDate

- dpEjemplo:
    Control: DatePicker
    Properties:
        X: =0
        Y: =0
        Width: =200
        Height: =44
        SelectedDate: =Today()

Dropdown 控件

- ddEjemplo:
    Control: Dropdown
    Properties:
        X: =0
        Y: =0
        Width: =200
        Height: =44
        Items: =["Opción 1", "Opción 2", "Opción 3"]
        DefaultSelectedItems: =["Opción 1"]
        OnChange: =Set(varSeleccion, Self.Selected.Value)

对于数值项：

Items: =Sequence(24, 0)              # 0 a 23
Items: =[0, 5, 10, 15, 20, 25, 30]   # Lista explícita

GroupContainer 控件

❌ 不支持	✅ 替代方案
OnSelect	在容器内放置一个透明的 Button 覆盖层
RadiusTopLeft/Right/etc	（现代控件中不存在）

- containerEjemplo:
    Control: GroupContainer
    Variant: ManualLayout
    Properties:
        X: =0
        Y: =0
        Width: =200
        Height: =100
        Fill: =Surface
        DropShadow: =DropShadow.Light

让容器可点击：

Children:
    - lblContenido:
        Control: Text
        Properties:
            Text: ="Mi contenido"
    - btnOverlay:
        Control: Button
        Properties:
            X: =0
            Y: =0
            Width: =Parent.Width
            Height: =Parent.Height
            Text: =""
            Appearance: ='ButtonCanvas.Appearance'.Transparent
            OnSelect: =Navigate(OtraPantalla, ScreenTransition.None)

---

📊 Gallery — 关键规则

规则 #1：Variant 是必需项

- galEjemplo:
    Control: Gallery
    Variant: BrowseLayout_Flexible_SocialFeed_ver5.0  # OBLIGATORIO

缺少时的错误： PA1011: The keyword 'Variant' is required but is missing or empty

规则 #2：直接使用 SharePoint 项 → 效果良好

Items: =MiListaSP

规则 #3：使用集合项 → 使用带显式架构的 ForAll

⚠️ 问题：当 Items 指向使用 GroupBy + AddColumns 创建的集合时，Gallery 内的控件会显示错误 ❌，因为 Power Apps 无法推断架构。

✅ 解决方案：使用 ForAll 显式定义记录 {campo: valor}：

OnVisible: |-
    =ClearCollect(
        colRanking,
        ForAll(
            GroupBy(colRegistros, Title, Email, Registros),
            {
                Nombre: ThisRecord.Title,
                EmailUsuario: ThisRecord.Email,
                Puntos: Sum(Registros, Puntos),
                Sesiones: CountRows(Registros)
            }
        )
    )

规则 #4：GroupBy — 列名不要加引号

# ❌ MAL — "Registros" se interpreta como texto
GroupBy(tabla, "Title", "Email", "Registros")

# ✅ BIEN — identificadores sin comillas
GroupBy(tabla, Title, Email, Registros)

规则 #5：不要按会变化的列分组

如果用户可以更改所属团队，就不要按 Equipo 分组，否则会出现重复项。应从最新记录中获取团队：

EquipoUsuario: Last(Registros).Equipo

规则 #6：在 ForAll 中访问分组表

# ❌ MAL — ThisRecord.Registros no resuelve
Sum(ThisRecord.Registros, Puntos)

# ✅ BIEN — acceso directo a la columna de grupo
Sum(Registros, Puntos)

使用集合的 Gallery 完整模板：

- galRanking:
    Control: Gallery
    Variant: BrowseLayout_Flexible_SocialFeed_ver5.0
    Properties:
        X: =16
        Y: =188
        Width: =Parent.Width - 32
        Height: =Parent.Height - 204
        Items: =SortByColumns(colRanking, "Puntos", SortOrder.Descending)
        TemplatePadding: =6
        TemplateSize: =80
        Fill: =RGBA(0, 0, 0, 0)
    Children:
        - CardItem:
            Control: GroupContainer
            Variant: ManualLayout
            Properties:
                Width: =Parent.Width
                Height: =74
                Fill: =Surface
                DropShadow: =DropShadow.Light
            Children:
                - lblNombre:
                    Control: Text
                    Properties:
                        X: =16
                        Y: =12
                        Width: =Parent.Width - 140
                        Height: =24
                        Text: =ThisItem.Nombre

---

🚀 本地缓存模式（优化）

问题

每个屏幕都独立查询 SharePoint → 速度慢且冗余。

解决方案：在 Screen_Inicio 中建立缓存中心

# Screen_Inicio.OnVisible — carga datos UNA VEZ
OnVisible: |-
    =Set(varUsuarioActual, User().FullName);
    Set(varEmailActual, User().Email);
    ClearCollect(
        colRegistrosMes,
        Filter(
            MiListaSP,
            Month(Fecha) = Month(Today()),
            Year(Fecha) = Year(Today())
        )
    );
    Set(varMisRegistros, Filter(colRegistrosMes, Email = varEmailActual));
    Set(varMiEquipo, LookUp(Miembros, Email = varEmailActual, Equipo))

在其他屏幕中复用

# Screen_Ranking — usa colRegistrosMes, NO re-consulta SharePoint
OnVisible: |-
    =ClearCollect(
        colRanking,
        ForAll(
            GroupBy(colRegistrosMes, Title, Email, Registros),
            { Nombre: ThisRecord.Title, Puntos: Sum(Registros, Puntos) }
        )
    )

# Screen_Equipos — usa varMiEquipo ya cacheado
OnVisible: |-
    =Set(varVistaEquipos, "Lista")
    # varMiEquipo ya está cargado desde Screen_Inicio

保存记录后 — 更新本地缓存

# En btnGuardar.OnSelect, después del Patch:
Patch(MiListaSP, Defaults(MiListaSP), { ... });
Collect(colRegistrosMes, { ...mismo registro... });
Navigate(Screen_Inicio, ScreenTransition.None)

结果：约 7 次 SP 查询 → 2 次查询（1 次 ClearCollect + 1 次 LookUp）

🎨 主题颜色（App.Formulas）

在 App > Formulas 中定义全局调色板：

BrandPrimary = RGBA(30, 41, 59, 1);
BrandAccent = RGBA(255, 107, 53, 1);
BrandAccentLight = RGBA(255, 107, 53, 0.08);
Surface = RGBA(255, 255, 255, 1);
SurfaceAlt = RGBA(245, 247, 252, 1);
TextPrimary = RGBA(15, 23, 42, 1);
TextSecondary = RGBA(100, 116, 139, 1);
TextOnAccent = RGBA(255, 255, 255, 1);
StatusSuccess = RGBA(16, 185, 129, 1);
StatusWarning = RGBA(234, 179, 8, 1);
StatusError = RGBA(239, 68, 68, 1);

---

⏰ 模式：使用下拉菜单选择时间

DatePicker 只能选择日期。要选择时间，请使用成对的下拉菜单：

# Horas (0-23)
- ddHoraH:
    Control: Dropdown
    Properties:
        Items: =Sequence(24, 0)
        DefaultSelectedItems: =[8]

# Separador ":"
- lblSep:
    Control: Text
    Properties:
        Text: =":"
        Weight: =FontWeight.Bold

# Minutos (intervalos de 5)
- ddHoraM:
    Control: Dropdown
    Properties:
        Items: =[0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55]
        DefaultSelectedItems: =[0]

从下拉菜单构建 DateTime：

DateAdd(
    DateAdd(Today(), Value(ddHoraH.Selected.Value), TimeUnit.Hours),
    Value(ddHoraM.Selected.Value),
    TimeUnit.Minutes
)

计算时长：

With(
    {
        mins: (Value(ddFinH.Selected.Value) * 60 + Value(ddFinM.Selected.Value)) -
              (Value(ddInicioH.Selected.Value) * 60 + Value(ddInicioM.Selected.Value))
    },
    If(mins > 0, Text(RoundDown(mins / 60, 0)) & "h " & Text(Mod(mins, 60)) & "min", "⚠️ Error")
)

---

📋 粘贴代码流程

1. 在 Power Apps Studio 中手动创建屏幕
2. 确保名称与 YAML 中定义的名称一致
3. 复制文件中的全部内容（包括 Screens:）
4. 在 Tree View 中选择屏幕
5. 按 Ctrl+V 粘贴，或右键 → Paste code
6. 如果 OnVisible 中的集合导致设计时错误，请运行（Play ▶️）以创建集合

---

⚠️ 常见错误表

错误	原因	解决方案
PA2108: Unknown property 'Color'	经典属性	使用 FontColor
PA2108: Unknown property 'FontWeight' in Text	经典属性	使用 Weight
PA2108: Unknown property 'Fill' in Button	经典属性	使用 BasePaletteColor
PA2108: Unknown property 'Default' in TextInput	经典属性	使用 Value
PA2108: Unknown property 'DefaultDate'	经典属性	使用 SelectedDate
PA2108: Unknown property 'OnSelect' in GroupContainer	不支持	添加透明的 Button 覆盖层
PA1011: 'Variant' is required in Gallery	缺少 Variant	添加 Variant: BrowseLayout_Flexible_SocialFeed_ver5.0
PA2109: Unknown variant 'X' in Gallery	Variant 无效	使用 BrowseLayout_Flexible_SocialFeed_ver5.0
YamlInvalidSyntax: PaModule	结构不正确	将 Screens: 用作顶层结构
Gallery 控件中显示 ❌	集合无法推断架构	使用 ForAll + 显式记录
排名中名称重复	按可变列执行 GroupBy	不要按会变化的字段分组
"Registros" error: text	GroupBy 中使用了引号	移除引号：GroupBy(t, Col, Grupo)

---

🧩 快速映射：经典 → 现代

控件	经典属性	现代属性
Text	Color	FontColor
Text	FontWeight	Weight
Button	Fill	BasePaletteColor
Button	Color	FontColor
Button	Size	FontSize
TextInput	Default	Value
TextInput	HintText	(不存在)
DatePicker	DefaultDate	SelectedDate
GroupContainer	OnSelect	(不存在)
所有控件	RadiusTopLeft 等	(不存在)

---

💡 Power Fx 提示

• 分隔符：使用逗号（,）作为分隔符 — 环境的区域设置决定 Power Apps 使用 , 还是 ;
• 多行字符串：在 YAML 中使用 |-，后接以 = 开头的公式
• SharePoint Choice 列：执行 Patch 时，Choice 类型的列使用 {Value: "texto"}
• SharePoint 列表名称：核对列表的确切名称（如果有重名，名称中会包含数字，例如：MiLista1）
• 类型化集合：对于为 Gallery 提供数据的集合，始终使用 ForAll({campo: valor})，而不是 AddColumns
• 全局变量：在 Screen_Inicio.OnVisible 中缓存共享数据，并在其他屏幕中重复使用