Usar provisionamento remoto para identidade visual de páginas do SharePoint
Você pode aplicar e interagir com temas usando recursos de provisionamento remoto no SharePoint. Esses recursos são fornecidos pelas seguintes APIs:
Importante
Essa opção de extensibilidade está disponível apenas para experiências clássicas do SharePoint. Você não pode usar essa opção com experiências modernas no SharePoint Online, como nos sites de comunicação.
O método ApplyTheme alimenta o Assistente de Alteração da Aparência. O assistente aplica uma aparência composta, ou uma aparência personalizada, a um site do SharePoint usando componentes especificados. Os temas são aplicados site a site.
As APIs do lado do servidor ApplyThemeApp e ThemeInfo são expostas por meio das APIs ApplyTheme e ThemeInfo em CSOM e JSOM.
Para obter um exemplo que mostra como aplicar um tema existente ou personalizado, consulte Branding.Themes no GitHub.
Método ApplyTheme
Use o método ApplyTheme do lado do cliente ao usar o provisionamento remoto para aplicar temas, conforme mostrado no exemplo a seguir.
public void ApplyTheme(
string colorPaletteUrl,
string fontSchemeUrl,
string backgroundImageUrl,
bool shareGenerated
)
O método ApplyTheme usa os seguintes parâmetros:
colorPaletteUrl – A URL relativa do servidor do arquivo de paleta de cores (por exemplo, spcolor).
fontSchemeUrl – A URL relativa do servidor do arquivo de esquema de fonte (por exemplo, spfont).
backgroundImageUrl – A URL relativa ao servidor da imagem em segundo plano. Se não houver nenhuma imagem em segundo plano, esse parâmetro retornará uma referência nula .
shareGenerated – um valor booliano. True se os arquivos de tema gerados devem ser aplicados à Web raiz; false se eles forem armazenados na Web atual.
Observação
O parâmetro shareGenerated determina se os arquivos de saída temáticos são armazenados em um local específico da Web ou em um local acessível em toda a coleção de sites. Recomendamos que você mantenha o valor padrão para o tipo de site.
Classe ThemeInfo
Você pode usar o código CSOM para obter informações sobre os looks compostos que são aplicados a um site. A classe ThemeInfo obtém o contexto associado aos temas, conforme mostrado no exemplo a seguir.
public ThemeInfo ThemeInfo { get; }
Você pode usar a classe ThemeInfo para obter detalhes sobre temas que são aplicados a um site, incluindo descrições, contexto, dados de objeto, cores e fontes para o nome especificado (e fontes para o código de idioma especificado), bem como o URI para a imagem em segundo plano definida para o visual composto.
Usar ApplyTheme e ThemeInfo no código CSOM
O exemplo de código a seguir mostra como usar ApplyTheme e ThemeInfo no código CSOM. Você pode usar esse código no padrão de provisionamento remoto. Por exemplo, você pode decidir criar looks compostos de forma programática, conforme especificado por um designer, e provisioná-los em sites em seu aplicativo Web.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Text;
using System.IO;
using Microsoft.SharePoint.Client;
namespace ApplyThemeAppWeb.Pages
{
public partial class Default : System.Web.UI.Page
{
public string _ContextToken
{
get
{
if (ViewState["ContextToken"] == null)
return null;
return ViewState["ContextToken"].ToString();
}
set
{
ViewState["ContextToken"] = value;
}
}
public string _HostWeb
{
get
{
if (ViewState["HostWeb"] == null)
return null;
return ViewState["HostWeb"].ToString();
}
set
{
ViewState["HostWeb"] = value;
}
}
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack)
{
_ContextToken = TokenHelper.GetContextTokenFromRequest(Page.Request);
_HostWeb = Page.Request["SPHostUrl"];
}
StatusMessage.Text = string.Empty;
}
protected void GetThemeInfo_Click(object sender, EventArgs e)
{
try
{
StatusMessage.Text += GetThemeInfo();
}
catch (Exception ex)
{
StatusMessage.Text += Environment.NewLine + ex.ToString();
}
}
protected void ApplyTheme_Click(object sender, EventArgs e)
{
try
{
ApplyTheme();
StatusMessage.Text += "Theme applied. Click Get Theme Info to see changes." + Environment.NewLine;
}
catch (Exception ex)
{
StatusMessage.Text += Environment.NewLine + ex.ToString();
}
}
private string GetThemeInfo()
{
using (var clientContext = TokenHelper.GetClientContextWithContextToken(_HostWeb, _ContextToken, Request.Url.Authority))
{
Web hostWebObj = clientContext.Web;
ThemeInfo initialThemeInfo = hostWebObj.ThemeInfo;
// Get the initial theme info for the web. No need to load the entire web object.
clientContext.Load(hostWebObj, w => w.ThemeInfo, w => w.CustomMasterUrl);
// Theme component info is available via a method call that must be run.
var linkShade = initialThemeInfo.GetThemeShadeByName("Hyperlink");
var titleFont = initialThemeInfo.GetThemeFontByName("title", 1033);
// Run.
clientContext.ExecuteQuery();
// Use ThemeInfo to show some data about the theme currently applied to the web.
StringBuilder initialInfo = new StringBuilder();
initialInfo.AppendFormat("Current master page: {0}\r\n", hostWebObj.CustomMasterUrl);
initialInfo.AppendFormat("Background Image: {0}\r\n", initialThemeInfo.ThemeBackgroundImageUri);
initialInfo.AppendFormat("The \"Hyperlink\" Color for this theme is: {0}\r\n", linkShade.Value);
initialInfo.AppendFormat("The \"title\" Font for this theme is: {0}\r\n", titleFont.Value);
return initialInfo.ToString();
}
}
protected void ApplyTheme()
{
using (var clientContext = TokenHelper.GetClientContextWithContextToken(_HostWeb, _ContextToken, Request.Url.Authority))
{
// Apply the new theme.
// First, copy theme files to a temporary location (the web's Site Assets library).
Web hostWebObj = clientContext.Web;
Site hostSiteObj = clientContext.Site;
Web hostRootWebObj = hostSiteObj.RootWeb;
// Get the necessary lists and libraries.
List themeLibrary = hostRootWebObj.Lists.GetByTitle("Theme Gallery");
Folder themeFolder = themeLibrary.RootFolder.Folders.GetByUrl("15");
List looksGallery = hostRootWebObj.Lists.GetByTitle("Composed Looks");
List masterLibrary = hostRootWebObj.Lists.GetByTitle("Master Page Gallery");
List assetLibrary = hostRootWebObj.Lists.GetByTitle("Site Assets");
clientContext.Load(themeFolder, f => f.ServerRelativeUrl);
clientContext.Load(masterLibrary, l => l.RootFolder);
clientContext.Load(assetLibrary, l => l.RootFolder);
// First, upload the theme files to the Theme Gallery.
DirectoryInfo themeDir = new DirectoryInfo(Server.MapPath("/Theme"));
foreach (var themeFile in themeDir.EnumerateFiles())
{
FileCreationInformation newFile = new FileCreationInformation();
newFile.Content = System.IO.File.ReadAllBytes(themeFile.FullName);
newFile.Url = themeFile.Name;
newFile.Overwrite = true;
// Sort by file extension into the correct library.
switch (themeFile.Extension)
{
case ".spcolor":
case ".spfont":
Microsoft.SharePoint.Client.File uploadTheme = themeFolder.Files.Add(newFile);
clientContext.Load(uploadTheme);
break;
case ".master":
case ".html":
Microsoft.SharePoint.Client.File updloadMaster = masterLibrary.RootFolder.Files.Add(newFile);
clientContext.Load(updloadMaster);
break;
default:
Microsoft.SharePoint.Client.File uploadAsset = assetLibrary.RootFolder.Files.Add(newFile);
clientContext.Load(uploadAsset);
break;
}
}
// Run the file upload.
clientContext.ExecuteQuery();
// Create a new composed look for the theme.
string themeFolderUrl = themeFolder.ServerRelativeUrl;
string masterFolderUrl = masterLibrary.RootFolder.ServerRelativeUrl;
// Optional: Use to make the custom theme available for selection in the UI. For
// example, for OneDrive for Business sites, you don't need this code because
// the ability to set a theme is hidden.
ListItemCreationInformation newLook = new ListItemCreationInformation();
Microsoft.SharePoint.Client.ListItem newLookItem = looksGallery.AddItem(newLook);
newLookItem["Title"] = "Theme Sample Look";
newLookItem["Name"] = "Theme Sample Look";
FieldUrlValue masterFieldValue = new FieldUrlValue();
masterFieldValue.Url = masterFolderUrl + "/seattle.master";
newLookItem["MasterPageUrl"] = masterFieldValue;
FieldUrlValue colorFieldValue = new FieldUrlValue();
colorFieldValue.Url = themeFolderUrl + "/ThemeSample.spcolor";
newLookItem["ThemeUrl"] = colorFieldValue;
FieldUrlValue fontFieldValue = new FieldUrlValue();
fontFieldValue.Url = themeFolderUrl + "/ThemeSample.spfont";
newLookItem["FontSchemeUrl"] = fontFieldValue;
newLookItem.Update();
// Apply the master page.
hostWebObj.CustomMasterUrl = masterFieldValue.Url;
// Update between the last and next steps. ApplyTheme throws errors if the theme
// and master page are updated in the same query.
hostWebObj.Update();
clientContext.ExecuteQuery();
// Apply the theme.
hostWebObj.ApplyTheme(
colorFieldValue.Url, // URL of the color palette (.spcolor) file
fontFieldValue.Url, // URL to the font scheme (.spfont) file (optional)
null, // Background Image URL (optional, null here)
false // False stores the composed look files in this web only. True shares the composed look with the site collection (to which you need permission).
// Need to call update to apply the change to the host web.
hostWebObj.Update();
// Run the Update method.
clientContext.ExecuteQuery();
}
}
}
}