Utiliser l’approvisionnement à distance pour personnaliser des pages SharePoint
Vous pouvez appliquer des thèmes et interagir avec eux à l’aide des fonctionnalités d’approvisionnement à distance dans SharePoint. Ces fonctionnalités sont fournies par les API suivantes :
Importante
Cette option d’extensibilité est disponible uniquement pour des expériences SharePoint classiques. Vous ne pouvez pas l’utiliser avec des expériences modernes dans SharePoint Online, telles que des sites de communication.
La méthode ApplyTheme alimente l’Assistant Modification de l’apparence. L’Assistant applique une apparence composée, ou une apparence personnalisée, à un site SharePoint à l’aide de composants spécifiés. Les thèmes sont appliqués site par site.
Les API côté serveur ApplyThemeApp et ThemeInfo sont exposées via les API ApplyTheme et ThemeInfo dans CSOM et JSOM.
Pour obtenir un exemple qui vous montre comment appliquer un thème existant ou personnalisé, consultez Branding.Themes sur GitHub.
Méthode ApplyTheme
Utilisez la méthode côté client ApplyTheme lorsque vous utilisez l’approvisionnement à distance pour appliquer des thèmes, comme illustré dans l’exemple suivant.
public void ApplyTheme(
string colorPaletteUrl,
string fontSchemeUrl,
string backgroundImageUrl,
bool shareGenerated
)
La méthode ApplyTheme utilise les paramètres suivants :
colorPaletteUrl : URL relative du serveur du fichier de palette de couleurs (par exemple, spcolor).
fontSchemeUrl : URL relative du serveur du fichier de jeu de polices (par exemple, spfont).
backgroundImageUrl : URL relative du serveur de l’image d’arrière-plan. S’il n’y a pas d’image d’arrière-plan, ce paramètre retourne une référence null .
shareGenerated : valeur booléenne. True si les fichiers de thème générés doivent être appliqués au site web racine ; false s’ils doivent être stockés dans le site web actuel.
Remarque
Le paramètre shareGenerated détermine si les fichiers de sortie à thème sont stockés dans un emplacement spécifique au web ou dans un emplacement accessible dans la collection de sites. Nous vous recommandons de conserver la valeur par défaut pour votre type de site.
Classe ThemeInfo
Vous pouvez utiliser du code CSOM pour obtenir des informations sur les apparences composées appliquées à un site. La classe ThemeInfo obtient le contexte associé aux thèmes, comme illustré dans l’exemple suivant.
public ThemeInfo ThemeInfo { get; }
Vous pouvez utiliser la classe ThemeInfo pour obtenir des détails sur les thèmes appliqués à un site, notamment les descriptions, le contexte, les données d’objet, les couleurs et les polices pour le nom spécifié (et les polices pour le code de langue spécifié), ainsi que l’URI de l’image d’arrière-plan définie pour l’apparence composée.
Utiliser ApplyTheme et ThemeInfo dans le code CSOM
L’exemple de code suivant montre comment utiliser ApplyTheme et ThemeInfo dans le code CSOM. Vous pouvez utiliser ce code dans le modèle d’approvisionnement à distance. Par exemple, vous pouvez décider de créer des apparences composées par programmation, comme spécifié par un concepteur, et de les approvisionner sur les sites de votre application 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();
}
}
}
}