SharePoint 网站设计和网站脚本概述SharePoint site design and site script overview

备注

网站设计和网站脚本当前仅受 SharePoint Online 支持。Site designs and site scripts are currently only supported by SharePoint Online.

使用网站脚本和网站设计,可以通过自己的自定义配置,自动预配新的或现有的新式 SharePoint 网站。Use site designs and site scripts to automate provisioning new or existing modern SharePoint sites that use your own custom configurations.

如果组织中有人新建 SharePoint 网站,通常都需要确保一定水平的一致性。When people in your organization create new SharePoint sites, you often need to ensure some level of consistency. 例如,可能需要向每个新网站都应用适当的品牌和主题。For example, you may need proper branding and theming applied to each new site. 可能还需要有每次新建网站时都必须应用的详细网站预配脚本(如使用 PnP 预配引擎)。You may also have detailed site provisioning scripts, such as using the PnP provisioning engine, that need to be applied each time a new site is created.

本文介绍了如何使用网站设计和网站脚本提供要在新建网站时应用的自定义配置。This article describes how you can use site designs and site scripts to provide custom configurations to apply when new sites are created.

网站设计的工作原理How site designs work

网站设计类似于模板。Site designs are like a template. 可以在每次新建网站时使用它们,以应用一组一致的操作。They can be used each time a new site is created to apply a consistent set of actions. 还可以将它们应用于现有新式网站(与组连接的团队网站和通信网站)。They can also be applied to existing modern sites (group-connected Team and Communication sites). 大多数操作通常影响的是网站本身,如设置主题或创建列表。Most actions typically affect the site itself, such as setting the theme or creating lists. 不过,网站设计也可以包含其他操作,如将新网站 URL 记录到日志或发送推文。But a site design can also include other actions, such as recording the new site URL to a log, or sending a tweet.

请创建网站设计,并在 SharePoint 中将网站设计注册到下列新式模板网站之一:团队网站或通信网站。You create site designs and register them in SharePoint to one of the modern template sites: the Team site or the Communication site. 有关网站设计的工作原理,请执行以下步骤。You can see how this works in the following steps.

  1. 在开发人员租户上转到 SharePoint 起始页。Go to the SharePoint start page on your developer tenant.

  2. 选择“创建网站”****。Choose Create site.

    将看到两个新式模板网站:“团队网站”**** 和“通信网站”****。You'll see the two modern template sites: Team site and Communication site.

  3. 选择“通信网站”****。Choose Communication site.

通信网站提供“选择设计”**** 框,其中包含以下网站设计:The Communication site has a Choose a design box, which comes with the following site designs:

  • 主题Topic
  • 展示Showcase
  • 空白Blank

这些是默认网站设计。These are the default site designs. 每个网站设计都有标题、说明和图像。For each site design, there is a title, description, and image.

通信网站模板中默认网站设计的标题、说明和图像

如果选择了“团队网站”模板,其中只包含一个名为“团队网站”**** 的默认网站设计。Had you chosen the Team site template, it contains only one default site design named Team site.

若要详细了解如何更改默认网站设计,请参阅自定义默认网站设计For more information about how you can change the default site designs, see Customize a default site design.

在用户选择网站设计后,SharePoint 便会新建网站,并运行网站设计的网站脚本。When a site design is selected, SharePoint creates the new site, and runs site scripts for the site design. 网站脚本包含新建列表或应用主题等操作的详细信息。The site scripts detail the work such as creating new lists or applying a theme. 这些脚本操作在后台运行。These script actions are run in the background. 此时将显示一个通知栏,网站创建者可以单击该通知栏以查看正在应用的操作的状态。A notification bar will be displayed, which the site creator can click to view the status of the actions being applied.

显示脚本操作应用正在进行中的通知栏

脚本应用完成后,通知栏消息将更改为允许网站创建者刷新页面以查看应用脚本的结果或查看网站脚本详细信息。When the scripts are complete the notification bar message will change - allowing the site creator to either refresh the page to see the results of the applied scripts or to view the site script details.

显示脚本操作应用已完成的通知栏

网站所有者可以随时调用网站设计信息面板,以查看已对网站应用的网站设计(及其脚本详细信息)以及应用全新或更新的网站设计。The site design information panel can be invoked by a site owner at any time to see what site designs have been applied to the site (and their script details) as well as to apply new or updated site designs.

在脚本中的操作完成后,SharePoint 便会在进度窗格中显示这些操作的详细结果。When the actions in the scripts are completed, SharePoint displays detailed results of those actions in a progress pane.

网站设计信息面板

备注

现在可以将网站设计应用于先前创建的新式网站集。Site designs can now be applied to previously created modern site collections. 有关详细信息,请参阅 REST APIPowerShell 文章。For more information, see the REST API and PowerShell articles.

网站脚本剖析Anatomy of a site script

网站脚本是 JSON 文件,指定要在新建网站时运行的操作的顺序列表。Site scripts are JSON files that specify an ordered list of actions to run when creating the new site. 操作按列表中的顺序运行。The actions are run in the order listed.

下面的示例展示了包含两个顶级操作的脚本。The following example is a script that has two top-level actions. 首先,它会应用之前创建的“Contoso 资源管理器”**** 主题。First, it applies a theme that was previously created named Contoso Explorers. 然后,它会创建“客户跟踪”**** 列表。It then creates a Customer Tracking list.

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json",
  "actions": [
    {
      "verb": "applyTheme",
      "themeName": "Contoso Explorers"
    },
    {
      "verb": "createSPList",
      "listName": "Customer Tracking",
      "templateType": 100,
      "subactions": [
        {
          "verb": "setDescription",
          "description": "List of Customers and Orders"
        },
        {
          "verb": "addSPField",
          "fieldType": "Text",
          "displayName": "Customer Name",
          "isRequired": false,
          "addToDefaultView": true
        },
        {
          "verb": "addSPField",
          "fieldType": "Number",
          "displayName": "Requisition Total",
          "addToDefaultView": true,
          "isRequired": true
        },
        {
          "verb": "addSPField",
           "fieldType": "User",
          "displayName": "Contact",
          "addToDefaultView": true,
          "isRequired": true
        },
        {
          "verb": "addSPField",
          "fieldType": "Note",
          "displayName": "Meeting Notes",
          "isRequired": false
        }
      ]
    }
  ],
  "version": 1
}

在 JSON 中,网站脚本中的每个操作都是由谓词值指定。Each action in a site script is specified by a verb value in the JSON. 在上面的脚本中,第一个操作是由 applyTheme 谓词指定。In the previous script, the first action is specified by the applyTheme verb. 接下来,createSPList 谓词创建列表。Next, the createSPList verb creates the list. 请注意,createSPList 谓词包含自己的一组谓词,用于仅对此列表执行其他操作。Notice that the createSPList verb contains its own set of verbs that run additional actions on only the list.

可执行操作包括:Available actions include:

  • 创建新列表或库(或修改在该网站中创建的默认列或库)Creating a new list or library (or modifying the default one created with the site)
  • 创建网站栏、内容类型和配置其他列表设置Creating site columns, content types, and configuring other list settings
  • 设置网站品牌打造属性,如导航布局、页眉布局和页眉背景Set site branding properties like navigation layout, header layout and header background
  • 应用主题Applying a theme
  • 设置网站徽标Setting a site logo
  • 将链接添加到快速启动或中心导航Adding links to quick launch or hub navigation
  • 触发 Power Automate 流Triggering a Power Automate flow
  • 从应用程序目录安装部署的解决方案Installing a deployed solution from the app catalog
  • 设置网站的区域设置Setting regional settings for the site
  • 将主体(用户和组)添加到 SharePoint 角色Adding principals (users and groups) to SharePoint roles
  • 设置网站的外部共享功能Setting external sharing capability for the site

有关可用操作及其参数的完整列表,请参阅 JSON 架构For a complete list of available actions and their parameters, see the JSON schema.

备注

对于库和列表,请使用 PowerShell 命令 Get-SPOSiteScriptFromList 以便从现有 SharePoint 列表创建网站脚本语法。For libraries and lists, use the PowerShell command Get-SPOSiteScriptFromList to create the site script syntax from an existing SharePoint list.

预配后,可以在同一网站上重新运行网站脚本。Site scripts can be run again on the same site after provisioning. 由于网站脚本不具有破坏性,因此它们可以在重新运行时,确保网站与脚本中的配置保持一致。Site scripts are non-destructive, so when they run again, they ensure that the site matches the configuration in the script.

例如,如果网站上的现有列表与网站脚本要创建的列表同名,网站脚本只会向现有列表添加缺少的字段。For example, if the site already has a list with the same name that the site script is creating, the site script will only add missing fields to the existing list.

我们之前将网站脚本操作的限制限定为 30 个。We'd previously capped the limit of site script actions to 30. 这也是使用 Invoke-SPOSiteDesign 命令同步应用脚本的限制,但根据客户反馈和出于对其他操作的支持,当异步应用脚本(通过 UI 或使用 Add-SPOSiteDesignTask 命令)时,我们已将此限制提高到 300 个操作(或 100,000 个字符)。This remains the limit for scripts applied synchronously using the Invoke-SPOSiteDesign command, but based on customer feedback and support for additional actions we have bumped this limit to 300 actions (or 100,000 characters) when the scripts are applied asynchronously (either through the UI or using the Add-SPOSiteDesignTask command).

每个租户还有 100 个网站脚本和 100 个网站设计的限制。There is also a limit of 100 site scripts and 100 site designs per tenant.

使用 PowerShell 或 REST 处理网站设计和网站脚本Using PowerShell or REST to work with site designs and site scripts

可以使用 PowerShell 或 REST API 创建网站设计和网站脚本。You can create site designs and site scripts by using PowerShell or the REST API. 下面的示例展示了如何创建网站脚本和使用网站脚本的网站设计。The following example creates a site script and a site design that uses the site script.

C:\> Get-Content 'c:\scripts\site-script.json' `
     -Raw | `
     Add-SPOSiteScript `
    -Title "Contoso theme and list"

Id          : 2756067f-d818-4933-a514-2a2b2c50fb06
Title       : Contoso theme and list
Description :
Content     :
Version     : 0

C:\> Add-SPOSiteDesign `
  -Title "Contoso customer tracking" `
  -WebTemplate "64" `
  -SiteScripts "2756067f-d818-4933-a514-2a2b2c50fb06" `
  -Description "Creates customer list and applies standard theme"

在上面的示例中,Add-SPOSiteScript cmdlet 或 CreateSiteScript REST API 返回网站脚本 ID。此 ID 在后续调用 Add-SPO-SiteDesign cmdlet 或 CreateSiteDesign REST API 的过程中用于 SiteScripts 参数。In the previous example, the Add-SPOSiteScript cmdlet or CreateSiteScript REST API returns a site script id. This is used for the SiteScripts parameter in the subsequent call to the Add-SPOSiteDesign cmdlet or CreateSiteDesign REST API.

如果 WebTemplate 参数设置为值 64,表明是向团队网站模板注册此网站设计。The WebTemplate parameter set to the value 64 indicates registering this site design with the Team site template. 如果已禁用新式组创建,则可以使用 WebTemplate 1 来发布网站设计,使其显示“无组”团队网站模板。If you have disabled modern Group creation, then publish your site designs using WebTemplate 1 so that they display for the "Group-less" Team site template. 如果设置为值 68,则表明是向通信网站模板注册。The value 68 would indicate registering with the Communication site template. 如果新建团队网站,用户会在查看网站设计时看到 TitleDescription 参数。The Title and Description parameters are displayed when a user views site designs as they create a new Team site.

备注

一个网站设计可以运行多个脚本。A site design can run multiple scripts. 脚本 ID 以数组形式进行传递,并按列出的顺序运行。The script IDs are passed in an array, and they run in the order listed.

若要逐步了解如何创建网站设计,请参阅开始创建网站设计For step-by-step information about creating a site design, see Get started creating site designs.

使用 Power Automate 流执行 PnP 预配和自定义PnP provisioning and customization using Power Automate

网站脚本提供的一个操作是能够触发 Power Automate 流。One action provided by site scripts is the ability to trigger a Power Automate flow. 这样一来,可以指定在网站脚本原生提供的操作范围之外需要的任何自定义操作。This allows you to specify any custom action that you need beyond the actions provided natively in site scripts.

如果使用 PnP 预配引擎自动创建网站,可以使用 Power Automate 流与网站设计进行集成。If you use the PnP provisioning engine to automate site creation, you can use a Power Automate flow to integrate with site designs. 既可以维护所有现有预配脚本,也可以使用此技术新建自定义预配脚本。You can maintain all your existing provisioning scripts as well as create new custom provisioning scripts by using this technique.


Microsoft 流的触发过程

此过程的运行机制如下:The process works as follows:

  1. 脚本使用包含其他详细信息的 URL 实例化 Power Automate 流。The script instantiates your Power Automate flow using a URL with additional details.

  2. 流向已配置的 Azure 存储队列发送消息。The flow sends a message to an Azure storage queue that you have configured.

  3. 消息触发调用已配置的 Azure 函数。The message triggers a call to an Azure function that you have configured.

  4. Azure 函数运行自定义脚本(如 PnP 预配引擎),应用自定义配置。The Azure function runs your custom script, such as the PnP provisioning engine, to apply your custom configurations.

若要逐步了解如何为自己的 Power Automate 流配置 PnP 预配,请参阅使用 PnP 预配引擎生成完整的网站设计For a step-by-step tutorial about how to configure your own Power Automate flow with PnP provisioning, see Build a complete site design using the PnP provisioning engine.

界定访问权限Scoping

可以将网站设计配置为只对组织中的特定组或人员显示。You can configure site designs to only appear for specific groups or people in your organization. 这样一来,可以有效确保用户只看到专供自己使用的网站设计。This is useful to ensure that people only see the site designs intended for them. 例如,你可能需要让会计部门只看到专供他们使用的网站设计。For example, you might want the accounting department to only see site designs specifically for them. 向其他任何人显示会计网站设计可能都没有意义。And the accounting site designs may not make sense to show to anyone else.

默认情况下,网站设计在创建后可供所有人查看。By default, a site design can be viewed by everyone when it is created. 使用 Grant-SPOSiteDesignRights cmdlet 或 GrantSiteDesignRights REST API 可以界定访问权限。Scopes are applied by using the Grant-SPOSiteDesignRights cmdlet or the GrantSiteDesignRights REST API. 可以指定只有用户或启用邮件的安全组才能访问。You can specify the scope by user or a mail-enabled security group.

下面的示例展示了如何向 Nestor(虚构 Contoso 网站中的用户)授予对网站设计的查看权限。The following example shows how to add Nestor (a user at the fictional Contoso site) view rights on a site design.

Grant-SPOSiteDesignRights `
  -Identity 44252d09-62c4-4913-9eb0-a2a8b8d7f863 `
  -Principals "nestorw@contoso.onmicrosoft.com" `
  -Rights View

若要详细了解如何界定访问权限,请参阅界定对网站设计的访问权限For more information about working with scopes, see Scoping access to site designs.

另请参阅See also