Instalace a aktivace

Nasazení balíčku .sppkg do katalogu aplikací a aktivace formuláře na seznamu.

Požadavky

• SharePoint Online s moderním prostředím seznamů. Řešení je postavené na SPFx 1.23 (FormCustomizer rozšíření a ListViewCommandSet).
• Role pro nasazení: správce App Catalogu (tenantového, nebo site collection) a pro aktivaci na seznamu vlastník webu. Pro skripty v PowerShellu modul PnP.PowerShell (Install-Module -Name PnP.PowerShell -Scope CurrentUser).
• Sestavení balíčku: Node.js >=22.14 <23 a nainstalované závislosti v obou balících (spfx-form-customizer i spfx-form-customizer-core). Hotový .sppkg už Node nepotřebuje.

Sestavení balíčku

Pokud máte hotový .sppkg od dodavatele, přejděte rovnou na Nasazení balíčku.

1. V obou složkách spfx-form-customizer-core a spfx-form-customizer spusťte npm install (balíčky nemají workspaces, každý má vlastní node_modules).
2. V kořeni repozitáře spusťte npm run ship. Příkaz synchronizuje jádro, spustí unit testy, smaže staré výstupy a sestaví produkční balíček.
3. Výsledek je spfx-form-customizer/sharepoint/solution/spfx-form-customizer.sppkg. Skripty a styly jsou uvnitř balíčku (includeClientSideAssets) a SharePoint je servíruje z CDN katalogu aplikací, žádné externí úložiště není potřeba.

Nasazení balíčku

Balíček se nahrává do katalogu aplikací. Vyberte jednu ze dvou variant.

Tenantový App Catalog (doporučeno)

1. Otevřete SharePoint Admin Center (https://<tenant>-admin.sharepoint.com), sekci Apps a v ní App Catalog (nebo přímo https://<tenant>.sharepoint.com/sites/appcatalog).
2. Nahrajte spfx-form-customizer.sppkg do knihovny Apps for SharePoint.
3. V dialogu zaškrtněte Enable this app and add it to all sites. Balíček má skipFeatureDeployment: true, takže se nasadí pro celý tenant a nemusíte ho přidávat na jednotlivé weby.
4. Potvrďte tlačítkem Enable app.

App Catalog site collection

Pokud nemáte přístup k tenantovému katalogu, může správce site collection vytvořit vlastní App Catalog (Add-PnPSiteCollectionAppCatalog) a balíček nahrát do něj. Řešení se pak nabízí jen na webech té site collection.

Aktivace formuláře na seznamu

Nasazení balíčku samo nic na seznamech nemění. Formulář musíte na seznamu zapnout, a to jednou z cest níže. Aktivací se pro vybrané typy obsahu nastaví komponenta CustomFormCustomizer (ID 910d1ea6-1bac-43f1-8f31-01aeba0c3605) jako formulář nové položky, úpravy a zobrazení.

Tlačítko „Vlastní formulář“ / „Otevřít editor FormCraft 365“ (Form Activator)

Balíček obsahuje rozšíření FormActivatorCommandSet, které přidá na příkazovou lištu seznamu příkaz pro správu vlastního formuláře (náhrada PowerShellu) a v případě nakonfigurovaných vlastních akcí seznamu také tlačítka na lištu a do kontextového menu.

1. Otevřete seznam a na příkazové liště klikněte na Vlastní formulář (pokud na seznamu vlastní formulář ještě není aktivní) nebo na Otevřít editor FormCraft 365 (pokud už je vlastní formulář aktivní). Příkaz vidí jen vlastníci webu (kontrola oprávnění ManageWeb, případně člen skupiny návrhářů). Viditelnost a stav aktivace se určí hned při načtení lišty z oprávnění stránky a výsledek se pamatuje do konce relace prohlížeče (sessionStorage), takže lišta nepřeblikává; skutečná oprávnění se vždy ověřují při načtení a uložení konfigurace. Pokud už je formulář aktivní, tlačítko otevře přímo návrhář formuláře (RibbonBuilderHost), kde lze formulář upravovat i spravovat aktivaci přes tlačítko Aktivace na seznamech.
2. V dialogu Aktivace vlastního formuláře případně vyberte jiný seznam webu (nabízejí se seznamy se šablonou 100, 120 a 1100; knihovny dokumentů se nenabízejí).
3. Zvolte, pro které režimy se formulář použije: Nový záznam (NewForm), Editace záznamu (EditForm), Zobrazení záznamu (DisplayForm).
4. Zaškrtněte typy obsahu seznamu (skryté typy a složky se nenabízejí) a klikněte na Aktivovat vlastní formulář. Dialog dále nabízí dvě volby (výchozí zapnuto): Vypnout offline dostupnost seznamu (bez toho se tlačítka a akce seznamu u uživatelů se synchronizací Microsoft Lists nemusí zobrazit; seznam nebude dostupný offline) a Vypnout rychlé úpravy (zobrazení mřížky) (zabrání úpravám mimo formulář). Pravidla FormCraftu (povinnost, zámky, výpočty) platí jen ve formuláři; úpravy přes Excel, Power Automate, API nebo mobilní aplikaci je neobejdou jen tehdy, když jsou pravidla nastavena přímo na sloupcích SharePointu. Selhání nastavení seznamu je jen varování. Při deaktivaci lze volbou Obnovit offline dostupnost a rychlé úpravy obě nastavení vrátit. U již aktivních typů je tlačítko Aktualizovat nastavení a Deaktivovat (vrátit výchozí SP formulář).

PowerShell (Manage-FormCustomizer.ps1)

Pro hromadnou správu je v repozitáři skript scripts/Manage-FormCustomizer.ps1 (PnP.PowerShell 1.x i 2.x). Při spuštění se interaktivně připojí k webu (Connect-PnPOnline -Interactive), případně použije existující spojení k téže URL. Nastavuje vlastnosti NewFormClientSideComponentId, EditFormClientSideComponentId a DisplayFormClientSideComponentId na typech obsahu seznamu (kromě složek 0x0120) pomocí Set-PnPContentType, stejně jako dialog „Vlastní formulář“.

# Zjištění stavu (NATIVNÍ SHAREPOINT / AKTIVNÍ / JINÁ KOMPONENTA pro každý formulář)
.\scripts\Manage-FormCustomizer.ps1 -SiteUrl "https://contoso.sharepoint.com/sites/intranet" -ListTitle "Poptavky" -Action Status

# Aktivace pro NewForm, EditForm i DisplayForm
.\scripts\Manage-FormCustomizer.ps1 -SiteUrl "https://contoso.sharepoint.com/sites/intranet" -ListTitle "Poptavky" -Action Enable

# Návrat na nativní formuláře (prázdné GUID)
.\scripts\Manage-FormCustomizer.ps1 -SiteUrl "https://contoso.sharepoint.com/sites/intranet" -ListTitle "Poptavky" -Action Disable

Soubory v SiteAssets

Konfigurace formulářů se ukládá do knihovny Site Assets webu, ve kterém seznam leží. Složku SiteAssets/FormCustomizer vytvoří návrhář při prvním uložení. Způsob jejího zabezpečení popisuje Oprávnění.

Aktualizace na novou verzi

1. Před sestavením zvyšte verzi v spfx-form-customizer/config/package-solution.json: solution.version i features[0].version (formát major.minor.patch.build, např. 1.9.0.0 na 1.9.1.0). Bez nové verze SharePoint nový balíček jako aktualizaci nepřijme.
2. Sestavte balíček příkazem npm run ship.
3. V App Catalogu nahrajte nový .sppkg a potvrďte přepsání stávajícího. U tenantového nasazení potvrďte znovu Enable app.
4. Po obnovení stránky (případně po vyprázdnění cache prohlížeče) se používá nová verze. Konfigurace v SiteAssets, licenční klíč ani politika skriptů se při aktualizaci nemění.
5. Aktualizace balíčku (nový .sppkg s volbou přidat na všechny weby) existující záznamy Tenant Wide Extensions nemění ani nemaže, přidá jen chybějící. Po aktualizaci vždy zkontrolujte, že seznam obsahuje právě 6 záznamů z tabulky a žádný není zakázaný (Disabled = Yes), viz kontrola záznamů Tenant Wide Extensions.

Kontrola záznamů Tenant Wide Extensions (aktualizace na 1.28.1 a ze starší verze než 1.26.0)

Rozšíření Command Set tvoří od verze 1.28.1 dvě samostatné komponenty: FormActivatorCommandSet (příkazová lišta: příkaz „Vlastní formulář“ / „Otevřít editor FormCraft 365“ a akce seznamu pro lištu) a FormListActionsContextMenu (kontextové menu položky: jen akce seznamu pro kontextové menu). Každá je registrovaná pro šablony seznamů 100, 120 a 1100. Celkem jde o 6 záznamů v seznamu Tenant Wide Extensions v App Catalogu.

SharePoint při aktualizaci přidá záznamy, které v seznamu chybí podle názvu; existující záznamy nemění ani nemaže, zastaralé je nutné smazat ručně. Po aktualizaci vždy zkontrolujte, že seznam obsahuje právě 6 záznamů z tabulky a že žádný z nich nemá Disabled = Yes (zakázaný záznam SharePoint vůbec nedoručí, takže příslušný příkaz se nespustí). Chybějící nebo zakázané záznamy způsobí, že se tlačítko „Vlastní formulář“ / „Otevřít editor FormCraft 365“ na liště nezobrazí. Zastaralé záznamy způsobí zdvojená tlačítka na liště a administrátorský příkaz i v kontextovém menu.

Očekávané záznamy (Sequence 0, Disabled No, Web Template a Host Properties prázdné):

Postup v prohlížeči:

1. Otevřete seznam https://<tenant>.sharepoint.com/sites/<appcatalog>/Lists/TenantWideExtensions/AllItems.aspx (App Catalog, Obsah webu, Tenant Wide Extensions).
2. Do zobrazení přidejte sloupce Component Id, Location, List Template a Component Properties a vyfiltrujte Component Id 4a8b7c12-5d3e-4f9a-8b1c-6e2d9f4a3b5c.
3. Aktualizace na 1.28.1 a novější: smažte staré záznamy kontextového menu, tedy ty s Location ClientSideExtension.ListViewCommandSet.ContextMenu, jejichž Component Id je 4a8b7c12-5d3e-4f9a-8b1c-6e2d9f4a3b5c (názvy FormActivatorCommandSet-ContextMenu-<šablona>). Nové záznamy FormListActionsContextMenu-<šablona> s Component Id a9998067-8e06-423f-b8a0-3177988f3a42 SharePoint přidal sám; nejsou-li v seznamu, vytvořte je.
4. Chybějící záznamy doplňte tlačítkem New (nová položka) podle tabulky výše. Ověřte, že žádný záznam nemá Disabled = Yes.
5. Zastaralé záznamy smažte: ty, jejichž Location je jen ClientSideExtension.ListViewCommandSet (bez přípony .CommandBar / .ContextMenu), záznamy lišty s prázdnými Component Properties a všechny záznamy, které v tabulce nejsou. Řiďte se sloupci Location a Component Id, ne názvem.
6. Změna se na webech projeví zhruba do 20 minut, poté obnovte stránku (Ctrl+F5). Příkaz „Vlastní formulář“ / „Otevřít editor FormCraft 365“ má být na liště jen jednou a v kontextovém menu nikdy.

Alternativa: odeberte aplikaci z App Catalogu včetně koše a nahrajte ji znovu s volbou přidat na všechny weby. SharePoint záznamy vytvoří znovu se správnými Component Id. Po tu dobu jsou formuláře nedostupné na všech webech; konfigurace v SiteAssets zůstanou zachované.

Totéž přes PnP PowerShell (nejdřív spusťte jen výpis; úpravy až po kontrole). Výchozí aplikace PnP Management Shell byla vyřazena, proto je u -ClientId nutné zadat vlastní aplikaci registrovanou v Microsoft Entra ID tenantu:

Connect-PnPOnline -Url https://<tenant>.sharepoint.com/sites/<appcatalog> -Interactive -ClientId <id-vaší-aplikace>
$list = "Lists/TenantWideExtensions"
$barId = "4a8b7c12-5d3e-4f9a-8b1c-6e2d9f4a3b5c"   # FormActivatorCommandSet (lišta)
$ctxId = "a9998067-8e06-423f-b8a0-3177988f3a42"   # FormListActionsContextMenu (kontextové menu, od 1.28.1)
$bar = "ClientSideExtension.ListViewCommandSet.CommandBar"; $ctx = "ClientSideExtension.ListViewCommandSet.ContextMenu"
$mine = { Get-PnPListItem -List $list | Where-Object { $_["TenantWideExtensionComponentId"] -in @($barId, $ctxId) } }
# 1) Výpis: ID | Component Id | Location | šablona | vlastnosti
& $mine | ForEach-Object { "{0} | {1} | {2} | {3} | {4}" -f $_.Id, $_["TenantWideExtensionComponentId"], $_["TenantWideExtensionLocation"], $_["TenantWideExtensionListTemplate"], $_["TenantWideExtensionComponentProperties"] }
# 2) Aktualizace na 1.28.1+: staré záznamy ContextMenu s Component Id lišty SMAZAT (ne upravovat; nové vytvoří SharePoint / krok 4)
& $mine | Where-Object { $_["TenantWideExtensionComponentId"] -eq $barId -and $_["TenantWideExtensionLocation"] -eq $ctx } |
  ForEach-Object { Remove-PnPListItem -List $list -Identity $_.Id -Force }
# 3) Smazání zastaralých záznamů (Location bez přípony, záznamy lišty bez vlastností)
& $mine | Where-Object { $_["TenantWideExtensionLocation"] -eq "ClientSideExtension.ListViewCommandSet" -or
  ($_["TenantWideExtensionComponentId"] -eq $barId -and -not $_["TenantWideExtensionComponentProperties"]) } |
  ForEach-Object { Remove-PnPListItem -List $list -Identity $_.Id -Force }
# 4) Doplnění chybějících záznamů (existující se přeskočí)
$existing = & $mine
foreach ($tpl in "100","120","1100") {
  foreach ($s in @(@{ Cid = $barId; Loc = $bar; Props = '{"surface":"commandBar"}'; Name = "FormActivatorCommandSet-$tpl" },
                   @{ Cid = $ctxId; Loc = $ctx; Props = '{}'; Name = "FormListActionsContextMenu-$tpl" })) {
    if ($existing | Where-Object { $_["TenantWideExtensionComponentId"] -eq $s.Cid -and $_["TenantWideExtensionLocation"] -eq $s.Loc -and "$($_["TenantWideExtensionListTemplate"])" -eq $tpl }) { continue }
    Add-PnPListItem -List $list -Values @{
      Title = $s.Name; TenantWideExtensionComponentId = $s.Cid; TenantWideExtensionLocation = $s.Loc
      TenantWideExtensionListTemplate = $tpl; TenantWideExtensionComponentProperties = $s.Props
      TenantWideExtensionSequence = 0; TenantWideExtensionDisabled = $false } | Out-Null
  }
}

Odinstalace

1. Na každém seznamu formulář deaktivujte: dialog „Vlastní formulář“ (Deaktivovat) nebo Manage-FormCustomizer.ps1 -Action Disable. Seznam se vrátí k výchozím formulářům SharePointu.
2. V App Catalogu balíček odeberte (Remove, případně smažte soubor z knihovny Apps for SharePoint).
3. Volitelně uklidíte data: smažte složku SiteAssets/FormCustomizer na webech, kde se formulář používal, a odeberte Storage Entity:

   Remove-PnPStorageEntity -Key SpfxFormCustomizer_License
   Remove-PnPStorageEntity -Key FormCraft365_ScriptsPolicy
   Remove-PnPStorageEntity -Key SpfxFormCustomizer_ScriptPolicy