通过API设置SharePoint网站页眉背景图片

一、全站范围设置页眉背景图 #

全站页眉背景图的配置存储在站点Web对象属性中，可通过REST API直接更新：

1. 请求详情
   • 请求URL：_api/web
   • 请求方法：PATCH
   • 请求头：
     • Accept: application/json;odata=verbose
     • Content-Type: application/json;odata=verbose
     • X-HTTP-Method: PATCH
     • If-Match: *
   • 请求体（示例）：

     {
       "__metadata": { "type": "SP.Web" },
       "HeaderBackgroundImageUrl": "/sites/<sitename>/SiteAssets/global-header-bg.png",
       "HeaderEmphasis": 4
     }
     

   • 参数说明：
     • HeaderBackgroundImageUrl：背景图的服务器相对路径（需先将图片上传至站点的SiteAssets或其他可访问文档库）
     • HeaderEmphasis：背景图的对比度/透明度等级，可选值0-4，数值越高对比度越强

二、仅Home.aspx页面单独设置页眉背景图 #

现代页面的页眉布局属性存储在页面ListItem的LayoutProperties字段中（CanvasContent1仅存储页面上的Web部件内容，与页眉配置无关），可通过以下步骤修改：

1. （可选）获取当前页面的LayoutProperties，用于确认现有配置

   • 请求URL：_api/web/getfilebyserverrelativeurl('/sites/<sitename>/SitePages/Home.aspx')/ListItemAllFields?$select=LayoutProperties
   • 请求方法：GET

2. 更新页面的页眉背景图配置

   • 请求URL：_api/web/getfilebyserverrelativeurl('/sites/<sitename>/SitePages/Home.aspx')/ListItemAllFields
   • 请求方法：PATCH
   • 请求头：
     • Accept: application/json;odata=verbose
     • Content-Type: application/json;odata=verbose
     • X-HTTP-Method: PATCH
     • If-Match: *
   • 请求体（示例）：

     {
       "__metadata": { "type": "SP.Data.SitePagesItem" },
       "LayoutProperties": "{\"headerLayout\":\"standard\",\"headerBackgroundImageUrl\":\"/sites/<sitename>/SiteAssets/home-header-bg.png\",\"headerEmphasis\":3}"
     }
     

   • 参数说明：
     • headerLayout：页眉布局类型，保持standard即可（若需其他布局需对应调整）
     • headerBackgroundImageUrl：页面专属背景图的服务器相对路径
     • headerEmphasis：页面页眉的对比度等级，可选值0-4

关键说明 #

• 你之前查询的CanvasContent1仅负责存储页面Web部件内容，不包含页眉背景图配置，因此找不到相关属性
• _api/siteiconmanager接口用于管理站点图标（网站Logo），与页眉背景图配置无关，属于接口方向错误
• 背景图需先上传至站点可访问的库中，路径必须使用服务器相对路径（避免绝对URL）

内容的提问来源于stack exchange，提问作者Stijn