Verwenden der Remotebereitstellung zum Branding von SharePoint-Seiten
Sie können Designs mithilfe von Remotebereitstellungsfeatures in SharePoint anwenden und mit ihnen interagieren. Diese Features werden von den folgenden APIs bereitgestellt:
Wichtig
Diese Erweiterbarkeitsoption ist nur für klassische SharePoint-Oberflächen verfügbar. Sie können diese Option nicht mit modernen Benutzeroberflächen in SharePoint Online, wie z. B. mit Kommunikationswebsites, verwenden.
Die ApplyTheme-Methode unterstützt den Assistenten zum Ändern des Aussehens. Der Assistent wendet ein zusammengesetztes Aussehen oder ein benutzerdefiniertes Aussehen auf eine SharePoint-Website mithilfe der angegebenen Komponenten an. Designs werden websiteweise angewendet.
Die serverseitigen APIs ApplyThemeApp und ThemeInfo werden über die ApplyTheme - und ThemeInfo-APIs in CSOM und JSOM verfügbar gemacht.
Ein Beispiel, das zeigt, wie Sie ein vorhandenes oder benutzerdefiniertes Design anwenden, finden Sie unter Branding.Themes auf GitHub.
ApplyTheme-Methode
Verwenden Sie die clientseitige ApplyTheme-Methode , wenn Sie die Remotebereitstellung verwenden, um Designs anzuwenden, wie im folgenden Beispiel gezeigt.
public void ApplyTheme(
string colorPaletteUrl,
string fontSchemeUrl,
string backgroundImageUrl,
bool shareGenerated
)
Die ApplyTheme-Methode verwendet die folgenden Parameter:
colorPaletteUrl : Die serverrelative URL der Farbpalettendatei (z. B. spcolor).
fontSchemeUrl – Die serverrelative URL der Schriftartenschemadatei (z. B. spfont).
backgroundImageUrl : Die serverrelative URL des Hintergrundbilds. Wenn kein Hintergrundbild vorhanden ist, gibt dieser Parameter einen NULL-Verweis zurück.
shareGenerated : Ein boolescher Wert. True , wenn die generierten Designdateien auf das Stammweb angewendet werden sollen; false , wenn sie im aktuellen Web gespeichert werden sollen.
Hinweis
Der shareGenerated-Parameter bestimmt, ob die Designausgabedateien an einem webspezifischen Speicherort oder an einem Speicherort gespeichert werden, auf den in der gesamten Websitesammlung zugegriffen werden kann. Es wird empfohlen, den Standardwert für Ihren Websitetyp beizubehalten.
ThemeInfo-Klasse
Sie können CSOM-Code verwenden, um Informationen zu den zusammengesetzten Looks abzurufen, die auf eine Website angewendet werden. Die ThemeInfo-Klasse ruft den Kontext ab, der den Designs zugeordnet ist, wie im folgenden Beispiel gezeigt.
public ThemeInfo ThemeInfo { get; }
Sie können die ThemeInfo-Klasse verwenden, um Details zu Designs abzurufen, die auf eine Website angewendet werden, einschließlich Beschreibungen, Kontext, Objektdaten, Farben und Schriftarten für den angegebenen Namen (und Schriftarten für den angegebenen Sprachcode) sowie den URI für das Hintergrundbild, das für das zusammengesetzte Aussehen definiert ist.
Verwenden von ApplyTheme und ThemeInfo im CSOM-Code
Im folgenden Codebeispiel wird gezeigt, wie ApplyTheme und ThemeInfo im CSOM-Code verwendet werden. Sie können diesen Code im Remotebereitstellungsmuster verwenden. Beispielsweise können Sie sich entscheiden, zusammengesetzte Looks programmgesteuert zu erstellen, wie von einem Designer angegeben, und sie für Websites in Ihrer Webanwendung bereitzustellen.
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();
}
}
}
}