powerapps-yaml.md
15 KB • MD • jun. 18, 2026 06:54
---
name: powerapps-yaml
description: >
Genera código YAML pasteable en Power Apps Studio usando el schema pa.yaml v3.
Incluye controles modernos, patrones de caché, Gallery con colecciones, y
todas las lecciones aprendidas para vibe codear sin errores.
Trigger: Cuando el usuario pida crear pantallas, controles o código para Power Apps en formato YAML.
metadata:
author: matias-beltran
version: "2.0"
scope: [global]
auto_invoke:
- "Crear pantalla Power Apps"
- "Generar YAML para Power Apps"
- "Código pasteable Power Apps"
- "pa.yaml"
- "Power Apps con SharePoint"
---
# Power Apps YAML — Guía Completa para Vibe Coding
## Cuándo usar
- Al generar código YAML para pegar en Power Apps Studio
- Al crear o modificar pantallas de Power Apps
- Al convertir diseños a controles Power Apps modernos
- Al trabajar con SharePoint como backend
---
## 🔑 Estructura Base (pa.yaml Schema v3)
La estructura **OBLIGATORIA** para que Power Apps Studio acepte el YAML via "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"
```
### Reglas de estructura
1. **Top-level**: Siempre empieza con `Screens:`
2. **Screen name**: Debe coincidir EXACTAMENTE con el nombre de la pantalla en Power Apps Studio
3. **No usar `Control: Screen`**: Las pantallas se definen directamente bajo `Screens:`, SIN propiedad `Control`
4. **Children es un array**: Cada hijo comienza con `- NombreControl:`
5. **Control y Variant**: Se definen dentro de cada hijo, NO en la pantalla
6. **Valores con `=`**: TODAS las propiedades llevan `=` al inicio: `Text: ="Hola"`, `X: =0`
---
## 🚨 Propiedades de Controles Modernos (CRÍTICO)
Power Apps usa controles **modernos** que tienen nombres DIFERENTES a los clásicos. Usar los nombres incorrectos produce error `PA2108: Unknown property`.
### Control `Text` (Label)
| ❌ Clásico (NO usar) | ✅ Moderno (USAR) |
|----------------------|-------------------|
| `Color` | `FontColor` |
| `FontWeight` | `Weight` |
```yaml
- 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
```
### Control `Button`
| ❌ Clásico (NO usar) | ✅ Moderno (USAR) |
|----------------------|-------------------|
| `Fill` | `BasePaletteColor` |
| `Color` | `FontColor` |
| `Size` | `FontSize` |
| `RadiusTopLeft/Right/etc` | _(no existe, usa Fluent theme)_ |
```yaml
- 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")
```
**Valores de Appearance:**
- `'ButtonCanvas.Appearance'.Primary` — botón principal
- `'ButtonCanvas.Appearance'.Secondary` — botón secundario
- `'ButtonCanvas.Appearance'.Transparent` — transparente (ideal para overlays y back buttons)
### Control `TextInput`
| ❌ Clásico (NO usar) | ✅ Moderno (USAR) |
|----------------------|-------------------|
| `Default` | `Value` |
| `HintText` / `PlaceholderText` | _(no existe en moderno)_ |
| `Format` | _(no existe en moderno)_ |
```yaml
- txtEjemplo:
Control: TextInput
Properties:
X: =0
Y: =0
Width: =200
Height: =44
Value: =""
Mode: =TextMode.MultiLine # Opcional
```
### Control `DatePicker`
| ❌ Clásico (NO usar) | ✅ Moderno (USAR) |
|----------------------|-------------------|
| `DefaultDate` | `SelectedDate` |
```yaml
- dpEjemplo:
Control: DatePicker
Properties:
X: =0
Y: =0
Width: =200
Height: =44
SelectedDate: =Today()
```
### Control `Dropdown`
```yaml
- 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)
```
**Para items numéricos:**
```yaml
Items: =Sequence(24, 0) # 0 a 23
Items: =[0, 5, 10, 15, 20, 25, 30] # Lista explícita
```
### Control `GroupContainer`
| ❌ NO soportado | ✅ Alternativa |
|-----------------|---------------|
| `OnSelect` | Usar un Button overlay transparente dentro del container |
| `RadiusTopLeft/Right/etc` | _(no existe en modernos)_ |
```yaml
- containerEjemplo:
Control: GroupContainer
Variant: ManualLayout
Properties:
X: =0
Y: =0
Width: =200
Height: =100
Fill: =Surface
DropShadow: =DropShadow.Light
```
**Para hacer un container clickeable:**
```yaml
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 — Reglas Críticas
### Regla #1: Variant es OBLIGATORIO
```yaml
- galEjemplo:
Control: Gallery
Variant: BrowseLayout_Flexible_SocialFeed_ver5.0 # OBLIGATORIO
```
**Error si falta:** `PA1011: The keyword 'Variant' is required but is missing or empty`
### Regla #2: Items de SharePoint directo → funciona bien
```yaml
Items: =MiListaSP
```
### Regla #3: Items de colección → usar ForAll con esquema explícito
⚠️ **PROBLEMA**: Cuando `Items` apunta a una colección creada con `GroupBy + AddColumns`, los controles dentro de la gallery muestran errores ❌ porque Power Apps no puede inferir el esquema.
✅ **SOLUCIÓN**: Usar `ForAll` con registros de forma explícita `{campo: valor}`:
```yaml
OnVisible: |-
=ClearCollect(
colRanking,
ForAll(
GroupBy(colRegistros, Title, Email, Registros),
{
Nombre: ThisRecord.Title,
EmailUsuario: ThisRecord.Email,
Puntos: Sum(Registros, Puntos),
Sesiones: CountRows(Registros)
}
)
)
```
### Regla #4: GroupBy — NO usar comillas en columnas
```
# ❌ MAL — "Registros" se interpreta como texto
GroupBy(tabla, "Title", "Email", "Registros")
# ✅ BIEN — identificadores sin comillas
GroupBy(tabla, Title, Email, Registros)
```
### Regla #5: No agrupar por columnas que cambian
Si un usuario puede cambiar de equipo, NO agrupar por `Equipo` porque aparecerá duplicado. Tomar el equipo del último registro:
```
EquipoUsuario: Last(Registros).Equipo
```
### Regla #6: Acceder a tabla agrupada dentro de ForAll
```
# ❌ MAL — ThisRecord.Registros no resuelve
Sum(ThisRecord.Registros, Puntos)
# ✅ BIEN — acceso directo a la columna de grupo
Sum(Registros, Puntos)
```
### Template completo para Gallery con colección:
```yaml
- 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
```
---
## 🚀 Patrón de Caché Local (Optimización)
### Problema
Cada pantalla hace queries independientes a SharePoint → lento y redundante.
### Solución: Centro de caché en Screen_Inicio
```yaml
# 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))
```
### Reutilizar en otras pantallas
```yaml
# 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
```
### Después de guardar un registro — actualizar caché local
```yaml
# En btnGuardar.OnSelect, después del Patch:
Patch(MiListaSP, Defaults(MiListaSP), { ... });
Collect(colRegistrosMes, { ...mismo registro... });
Navigate(Screen_Inicio, ScreenTransition.None)
```
**Resultado**: ~7 queries SP → **2 queries** (1 ClearCollect + 1 LookUp)
---
## 🎨 Colores del Tema (App.Formulas)
Definir paleta global en `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);
```
---
## ⏰ Patrón: Selector de Hora con Dropdowns
El `DatePicker` solo selecciona fecha. Para hora, usar pares de Dropdowns:
```yaml
# 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]
```
### Construir DateTime desde dropdowns:
```
DateAdd(
DateAdd(Today(), Value(ddHoraH.Selected.Value), TimeUnit.Hours),
Value(ddHoraM.Selected.Value),
TimeUnit.Minutes
)
```
### Calcular duración:
```
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")
)
```
---
## 📋 Proceso de Paste Code
1. **Crear la pantalla** manualmente en Power Apps Studio
2. **Asegurar que el nombre** coincide con el definido en el YAML
3. **Copiar TODO** el contenido del archivo YAML (incluyendo `Screens:`)
4. **Seleccionar la pantalla** en el Tree View
5. **Pegar** con Ctrl+V o Click derecho → Paste code
6. Si hay errores de design-time por colecciones en `OnVisible`, ejecutar (Play ▶️) para que se creen
---
## ⚠️ Tabla de errores comunes
| Error | Causa | Solución |
|-------|-------|----------|
| `PA2108: Unknown property 'Color'` | Propiedad clásica | Usar `FontColor` |
| `PA2108: Unknown property 'FontWeight'` en Text | Propiedad clásica | Usar `Weight` |
| `PA2108: Unknown property 'Fill'` en Button | Propiedad clásica | Usar `BasePaletteColor` |
| `PA2108: Unknown property 'Default'` en TextInput | Propiedad clásica | Usar `Value` |
| `PA2108: Unknown property 'DefaultDate'` | Propiedad clásica | Usar `SelectedDate` |
| `PA2108: Unknown property 'OnSelect'` en GroupContainer | No soportado | Button overlay transparente |
| `PA1011: 'Variant' is required` en Gallery | Falta Variant | Agregar `Variant: BrowseLayout_Flexible_SocialFeed_ver5.0` |
| `PA2109: Unknown variant 'X'` en Gallery | Variant inválido | Usar `BrowseLayout_Flexible_SocialFeed_ver5.0` |
| `YamlInvalidSyntax: PaModule` | Estructura incorrecta | Usar `Screens:` como top-level |
| Gallery con ❌ en controles | Colección sin esquema inferible | Usar `ForAll` + registros explícitos |
| Nombre duplicado en ranking | GroupBy por columna variable | No agrupar por campos que cambian |
| `"Registros" error: text` | Comillas en GroupBy | Quitar comillas: `GroupBy(t, Col, Grupo)` |
---
## 🧩 Mapeo rápido: Clásico → Moderno
| Control | Propiedad Clásica | Propiedad Moderna |
|---------|-------------------|-------------------|
| Text | `Color` | `FontColor` |
| Text | `FontWeight` | `Weight` |
| Button | `Fill` | `BasePaletteColor` |
| Button | `Color` | `FontColor` |
| Button | `Size` | `FontSize` |
| TextInput | `Default` | `Value` |
| TextInput | `HintText` | _(no existe)_ |
| DatePicker | `DefaultDate` | `SelectedDate` |
| GroupContainer | `OnSelect` | _(no existe)_ |
| Todos | `RadiusTopLeft` etc. | _(no existe)_ |
---
## 💡 Tips Power Fx
- **Separadores**: Usar **comas** (`,`) como separadores — la config regional del entorno define si Power Apps espera `,` o `;`
- **Strings multilínea**: Usar `|-` en YAML seguido de la fórmula con `=` al inicio
- **SharePoint Choice columns**: Al hacer Patch, usar `{Value: "texto"}` para columnas de tipo Choice
- **SharePoint list names**: Verificar el nombre EXACTO de la lista (con números si hay duplicados, ej: `MiLista1`)
- **Colecciones tipadas**: Siempre usar `ForAll({campo: valor})` en vez de `AddColumns` para colecciones que alimentan Gallery
- **Variables globales**: Cachear datos compartidos en `Screen_Inicio.OnVisible` y reutilizar en otras pantallas