更新现有 SharePoint 网站和页面区域的品牌塑造
您可以刷新现有 SharePoint 网站和网站集上的品牌，并自定义 SharePoint 页面的区域。 例如，当您更新到网站的新版本时，可能想要执行此操作。
重要
此可扩展性选项仅适用于经典 SharePoint 体验。 不能将此选项用于 SharePoint Online 中的新式体验（如通信网站）。
刷新现有网站和子网站的品牌
GitHub 上的 Office 365 开发人员模式和实践项目中的 Branding.Refresh 示例向你演示如何使用 OfficeDevPnP.Core 库来循环访问现有网站和子网站，以验证并更新已应用的品牌。 该示例演示如何更新网站品牌，但是相同的概念可以用于执行其他操作，例如将新库部署到网站列表，或更新在设置过程中已部署的自定义操作。 你可以使用相同的过程将现有网站移动到较新版本中。
该操作包括两个步骤：
- 获取想要更新的网站。
- 更新网站品牌。
获取想要更新的网站
首先，获取您想要更新的网站和子网站的列表。 此示例演示如何使用搜索功能执行此操作，但其他选项包括读取网站目录，或提供管理员可以在其中指定列表的管理 UI。 下面的示例演示了如何使用搜索功能来生成列表。
// Get a list of sites. Search is one way to get this list, an alternative can be a site directory.
List<SiteEntity> sites = cc.Web.SiteSearchScopedByUrl("https://bertonline.sharepoint.com");
// Generic settings (apply changes on all webs or just root web).
bool applyChangesToAllWebs = true;
// Optionally further refine the list of returned site collections.
var filteredSites = from p in sites
where p.Url.Contains("13003")
select p;
List<SiteEntity> sitesAndSubSites = new List<SiteEntity>();
if (applyChangesToAllWebs)
{
// You want to update all sites, so the list of sites is extended to all subsites.
foreach (SiteEntity site in filteredSites)
{
sitesAndSubSites.Add(new SiteEntity() { Url = site.Url,
Title = site.Title,
Template = site.Template });
GetSubSites(cc, site.Url, ref sitesAndSubSites);
}
sites = sitesAndSubSites;
}
调用 GetSubSites 是递归形式的，所以可提取子网站树。 提取树后，验证所返回的数字是否正确，然后再继续进行。
更新品牌
选择要处理的网站之后，您可以使用 OfficeDevPnP.Core 方法操作该网站。 此示例演示如何为网站品牌执行此操作，但您可以以相同方式处理任何类型的更改。
此示例使用一种模式，即利用 Web 属性包来存储有关当前设置的信息。 代码首先读取 Web 属性包值，然后执行适用于每个值的操作。
// Verify that you have a property bag entry.
string themeName = cc.Web.GetPropertyBagValueString(BRANDING_THEME, "");
if (!String.IsNullOrEmpty(themeName))
{
// If no theme property bag entry, assume no theme has been applied.
if (themeName.Equals(currentThemeName, StringComparison.InvariantCultureIgnoreCase))
{
// The applied theme matches to the theme you want to update.
int? brandingVersion = cc.Web.GetPropertyBagValueInt(BRANDING_VERSION, 0);
if (brandingVersion < currentBrandingVersion)
{
DeployTheme(cc, currentThemeName);
// Set the web propertybag entries
cc.Web.SetPropertyBagValue(BRANDING_THEME, currentThemeName);
cc.Web.SetPropertyBagValue(BRANDING_VERSION, currentBrandingVersion);
}
}
else
{
if (forceBranding)
{
DeployTheme(cc, currentThemeName);
// Set the web propertybag entries.
cc.Web.SetPropertyBagValue(BRANDING_THEME, currentThemeName);
cc.Web.SetPropertyBagValue(BRANDING_VERSION, currentBrandingVersion);
}
}
}
之后，更新该主题的代码变得十分简单，它所基于的是 OfficeDevPnP.Core 方法。
string themeRoot = Path.Combine(AppRootPath, String.Format(@"Themes\{0}", themeName));
string spColorFile = Path.Combine(themeRoot, string.Format("{0}.spcolor", themeName));
string spFontFile = Path.Combine(themeRoot, string.Format("{0}.spfont", themeName));
string backgroundFile = Path.Combine(themeRoot, string.Format("{0}bg.jpg", themeName));
string logoFile = Path.Combine(themeRoot, string.Format("{0}logo.png", themeName));
if (IsThisASubSite(cc.Url))
{
// Retrieve the context of the root site of the site collection.
using (ClientContext ccParent = new ClientContext(GetRootSite(cc.Url)))
{
ccParent.Credentials = cc.Credentials;
cc.Web.DeployThemeToSubWeb(ccParent.Web, themeName, spColorFile, spFontFile, backgroundFile, "");
cc.Web.SetThemeToSubWeb(ccParent.Web, themeName);
}
}
else
{
cc.Web.DeployThemeToWeb(themeName, spColorFile, spFontFile, backgroundFile, "");
cc.Web.SetThemeToWeb(themeName);
}
自定义 SharePoint 页面的区域
如果您的目标是自定义 SharePoint 页面的区域，您可以使用与页面区域相关的文件上的远程设置和自定义级联样式表 (CSS) 的组合。 那么，最初，您必须知道哪些 SharePoint 文件与 SharePoint 页面的各个区域相关联。
表 1. SharePoint 页面区域和关联的文件
| 页面区域 | 关联的文件 | 详细信息 |
|---|---|---|
| 功能区 | 任何默认的母版页。 相应的 CSS：
|
可以通过“重点内容”按钮隐藏。 |
| 套件导航 | 任何默认的母版页。 | 可以通过“重点内容”按钮隐藏。 |
| 套件链接 | 可以通过“重点内容”按钮隐藏。 | |
| 欢迎菜单 | *。主人 | 可以通过“重点内容”按钮隐藏。 |
| 设置菜单或齿轮 | *。主人 | |
| 帮助 | *。主人 | |
| 功能区上下文选项卡 | 任何默认母版页。 | 有关示例，请参阅以下文章： |
| 快速访问工具栏 | *。主人 | 可以通过“重点内容”按钮隐藏。 |
| 网站徽标 | *。主人 相应的 CSS： .ms-sitelcon-img |
|
| 顶部导航 | 导航 CSOM/JSOM *。主人 相应的 CSS（不在编辑模式下）：
|
|
| 页面标题 | 相应的 CSS（在编辑模式下）：
|
|
| 搜索框 | Nav CSOM/JSOM *.master 对应的 CSS：
|
|
| 左侧导航 | Nav CSOM/JSOM *.master | 有关详细信息，请参阅： |
| 树状视图 | *。主人 | 有关详细信息，请参阅 如何自定义内置树状视图导航器(#如何自定义内置树状视图导航器)。 |
| 页面内容 | 页面布局/内容页面 Web 部件区域/Web 部件响应 CSS (Web 部件区域和 Web 部件) ：
|
有关详细信息，请参阅在 SharePoint 中创建页面布局。 |
有关自定义页面区域的示例，请参阅以下 GitHub 上的 Office 365 开发人员模式和做法项目中的内容：
默认的 SharePoint 母版页中所需的"最低限度"的内容占位符
SharePoint .master 页面要求您使用内容占位符，它可呈现出 SharePoint 页面支持页面生命周期所需的基本内容和结构元素。 表 2 列出并说明这些内容占位符。
表 2. SharePoint 母版页所需的最低内容占位符
| 内容占位符 | 保留的内容 |
|---|---|
| PlaceHolderAdditionalPageHead | 页面 \<head\> 部分中的其他项目。 |
| PlaceHolderBodyAreaClass | 页面标头中的其他样式。 |
| PlaceHolderBodyLeftBorder | 页面正文的左边框元素。 |
| PlaceHolderBodyRightBorder | 页面正文的右边框元素。 |
| PlaceHolderCalendarNavigator | 当日历显示在页面上时，用于在日历中进行导航的日期选取器。 |
| PlaceHolderFormDigest | "窗体摘要"安全控件。 |
| PlaceHolderGlobalNavigation | 全局导航痕迹导航（顶部导航）。 |
| PlaceHolderGlobalNavigationSiteMap | 全局导航中的站点地图（顶部导航）。 |
| PlaceHolderHorizontalNav | 页面的顶部导航菜单（顶部导航）。 |
| PlaceHolderLeftActions | 左下角导航区域（左侧导航）。 |
| PlaceHolderLeftNavBar | 左侧导航区域（左侧导航）。 |
| PlaceHolderLeftNavBarDataSource | 左侧导航菜单（左导航） 的数据源。 |
| PlaceHolderLeftNavBarTop | 左上角导航区域（左侧导航）。 |
| PlaceHolderMain | 页面的主要内容（页面内容）。 |
| PlaceHolderMiniConsole | 页面级别命令，如企业 wiki 网页上的"编辑页面"、"历史记录"和"传入链接"。 |
| PlaceHolderNavSpacer | 左侧导航区域（左侧导航）的宽度。 |
| PlaceHolderPageDescription | 页面内容的说明。 |
| PlaceHolderPageImage | 页面左上角的页面图标（功能区）。 |
| PlaceHolderPageTitle | 页面标题 (\<title\>)（页面标题）显示在浏览器页面的标题栏中。 |
| PlaceHolderPageTitleInTitle | 立即显示在痕迹导航下方的页面标题（页面标题）。 |
| PlaceHolderQuickLaunchBottom | 快速启动导航（顶部导航）的底部。 |
| PlaceHolderQuickLaunchTop | 快速启动导航（顶部导航）的顶部。 |
| PlaceHolderSearchArea | 搜索框控件显示的区域（搜索框）。 |
| PlaceHolderSiteName | 站点名称（套件导航）。 |
| PlaceHolderTitleAreaClass | 页面的标题区域（套件导航）。 |
| PlaceHolderTitleAreaSeparator | 标题区域（套件导航）中的阴影。 |
| PlaceHolderTitleBreadCrumb | 标题痕迹导航的内容区域。 |
| PlaceHolderTitleLeftBorder | 标题区域（套件导航）的左边框。 |
| PlaceHolderTitleRightMargin | 标题区域（套件导航）的右边距。 |
| PlaceHolderTopNavBar | 顶部导航区域（顶部导航）。 |
| PlaceHolderUtilities | 必须显示在页面底部的其他内容（页面内容）。 |
| SPNavigation | 包括与导航相关的操作。 |
| WSSDesignConsole | 页面处于"编辑"模式时的页面编辑控件。 |
如果您从 SharePoint 的 .master 页删除表 2 中列出的某个内容占位符，SharePoint 将弹出一个错误。 您可以添加隐藏可见性的内容占位符，它将隐藏不让最终用户看到的内容。
有关详细信息，请参阅 Windows SharePoint Services 默认母版页（此文章介绍 SharePoint Services 3 中的功能，但内容仍适用）。 请参阅 使用内容占位符控件。
默认的 SharePoint 母版页（如 seattle.master 和 oslo.master）包括比 SharePoint 所需更多的内容占位符。 例如，这些母版页包括 <SharePoint:Themes runat="server"> 和 <SharePoint.CssRegistration runat="server"> 控件。
页面生命周期过程中，将同时运行 Themes 和 CssRegistration 控件。 通过远程预配模式，可使用自定义操作添加服务器控件来注册自定义 CSS。
不可见的内容占位符仍然按预期正常工作，但它们生成的内容将从浏览器识别的 HTML 源代码中被省略。 带有 Visible="false" 的内容占位符处于隐藏状态。
重要
请不要在现成 .master 页面（如 seattle.master 和 oslo.master）中存在的自定义母版页内创建自定义占位符。 这会导致出现灾难性异常状况。
SharePoint Online 套件导航控件
SharePoint Online 引入套件导航控件的新母版页标记，呈现顶部导航。 套件导航控件的默认标记根据网站是内部网还是面向公众的网站而有所不同。 若要了解有关套件导航控件并查看可以添加到你的母版页的内部网和面向公众的网站的详细信息，请参阅 SharePoint Online 套件导航控件。
使用 CSOM 自定义 SharePoint 页面区域
一般情况下，我们建议你使用 UserCustomAction 类添加或删除链接等元素。 这是一种使用 CustomAction 元素的 SharePoint 变体，你如果熟悉完全信任的代码模型，就有可能将其视为功能框架的一部分。 虽然没有在客户端对象模型 (CSOM) 中对 CustomAction 元素和特征框架设置模式进行专门的支持，但可用于 CustomAction 元素的同样的位置标识符也可以用在 CSOM 代码中。
<CustomAction
RequiredAdmin = "Delegated | Farm | Machine"
ControlAssembly = "Text"
ControlClass = "Text"
ControlSrc = "Text"
Description = "Text"
FeatureId = "Text"
GroupId = "Text"
Id = "Text"
ImageUrl = "Text"
Location = "Text"
RegistrationId = "Text"
RegistrationType = "Text"
RequireSiteAdministrator = "TRUE" | "FALSE"
Rights = "Text"
RootWebOnly = "TRUE" | "FALSE"
ScriptSrc = "Text"
ScriptBlock = "Text"
Sequence = "Integer"
ShowInLists = "TRUE" | "FALSE"
ShowInReadOnlyContentTypes = "TRUE" | "FALSE"
ShowInSealedContentTypes = "TRUE" | "FALSE"
Title = "Text"
UIVersion = "Integer">
</CustomAction>
自定义 SharePoint 功能区
当你自定义功能区时，服务器呈现的 HTML 被分配到你分配给自定义样式的类名称。 若要使用此功能，请转到样式库，并为你想要添加到功能区的每个样式创建新的 CSS 文件。 你可以将自定义样式添加到功能区的两个部分：
- 对于页面元素部分：
span.ms-rteElement-{{YOUR_OWN_DEFINED_NAME}}。 或者，可以使用 H1、H2、H3 或 H4 这类将要把应用该样式的文本包裹起来的样式。 - 对于文本样式部分：
.ms-rteEStyle-{{YOUR_OWN_DEFINED_NAME}}。
然后，在 CSS 类定义中，添加以下行：
-ms-name:"The name visual in the ribbon for your style";
现在，可以在你的自定义 .css 文件中完成对自定义 CSS 类的细节定义。
自定义 Web 部件页上的套件导航
在 SharePoint 中，UI 具有基于页面磁贴的新式外观。 例如，在默认情况下，动态磁贴会出现在默认的 SharePoint 页面上。 顶部导航让用户能够轻松地查看和访问社交内容和 OneDrive for Business。 可以结合使用 CSS 和 JavaScript 自定义这些区域的外观。
创建 Web 部件页之后，将脚本编辑器 Web 部件添加到可用的 Web 部件区域。 可以使用此 Web 部件将 JavaScript 添加到页面。 可以将 JavaScript 代码通过其 ElementId 标识添加到可识别顶部导航栏的 SEWP，然后通过将其可见性属性设置为隐藏来隐藏它。
自定义“设置”菜单或齿轮
您可以使用 UserCustomAction 类和属性包条目来自定义任何 SharePoint 网站的设置菜单，如以下代码示例所示。
public void AddCustomActions(ClientContext clientContext)
{
// Add a site settings link if it doesn't already exist.
if (!CustomActionAlreadyExists(clientContext, "Sample_CustomSiteSetting"))
{
// Add a site settings link.
UserCustomAction siteSettingLink = clientContext.Web.UserCustomActions.Add();
siteSettingLink.Group = "SiteTasks";
siteSettingLink.Location = "Microsoft.SharePoint.SiteSettings";
siteSettingLink.Name = "Sample_CustomSiteSetting";
siteSettingLink.Sequence = 1000;
siteSettingLink.Url = string.Format(DeployManager.appUrl, clientContext.Url);
siteSettingLink.Title = "Modify Site Metadata";
siteSettingLink.Update();
clientContext.ExecuteQuery();
}
// Add a site actions link, if it doesn't already exist.
if (!CustomActionAlreadyExists(clientContext, "Sample_CustomAction"))
{
UserCustomAction siteAction = clientContext.Web.UserCustomActions.Add();
siteAction.Group = "SiteActions";
siteAction.Location = "Microsoft.SharePoint.StandardMenu";
siteAction.Name = "Sample_CustomAction";
siteAction.Sequence = 1000;
siteAction.Url = string.Format(DeployManager.appUrl, clientContext.Url); ;
siteAction.Title = "Modify Site Metadata";
siteAction.Update();
clientContext.ExecuteQuery();
}
}
自定义树状视图
若要修改树视图的宽度，请在 .master 页中的树标记周围添加标记 <div> ，并将具有样式宽度属性的 CSS 类分配给 <div>。 可以通过将以下样式定义添加到 *.css 文件来增加快速启动导航的宽度。
.ms-nav {
width: 220 px;
}
自定义页面内容
自定义页面内容的要求取决于你的页面中所包括的内容。 对于自定义“网站操作”菜单，你可以使用 UserCustomAction 对象以对 Web 部件预配品牌。
如果你正在生成发布网站，请参阅在 SharePoint 中创建页面布局来学习基础知识。 页面布局取决于 CSOM 中的 ContentTypeId 类的可用性。 对于 CSOM 中不可用的其他成员，可以使用 Windows Communication Foundation (WCF) 服务作为一个临时的替代方法来使用 ContentTypeId。