SharePoint 加载项用户体验设计准则SharePoint Add-ins UX design guidelines

外接程序是 SharePoint 的一个新概念,它使最终用户能够将新功能添加到其网站中,同时仍可确保 SharePoint 网站本身的可靠性。创建良好的外接程序不但需要出色的功能(虽然其重要性很明显),而且还需要确保外接程序看上去很好并且与可以完美地适合安装它的网站。Add-ins are a new concept for SharePoint, empowering end users to add new functionality to their sites while still ensuring reliability for the SharePoint site itself. Creating a good add-in requires not only making great functionality (although that's obviously important), but also ensuring that the add-in looks right and fits seamlessly into the site where it's installed.

选择加载项的部件版式Choosing the chrome for your add-in

生成外接程序时首先必须确定想要标记页面的程度以及想在何处托管页面。根据这些选择,您用于支持部件版式的技术将会相对明显:The first thing you have to determine when you are building an add-in is how much or how little you want to brand your pages and where you want them to be hosted. Depending on those choices, which technology you use to power your chrome will be relatively obvious:

  • 在 SharePoint 中托管的 ASPX 页面: 使用外接程序模板。ASPX pages hosted in SharePoint: Use the add-in template.
  • SharePoint 中托管的 HTML 页或 SharePoint 外部的任何页面: 使用版式控件。HTML pages hosted in SharePoint or any pages outside SharePoint: Use the chrome control.
  • 自定义品牌页面: 使用自己的部件版式。Custom branded pages: Use your own chrome.

对 SharePoint 托管页面使用加载项模板Using the add-in template for SharePoint-hosted pages

外接程序模板只能用于 SharePoint 托管的 ASPX 页面。此模板包括 app.master 母版页(包含适合外接程序的部件版式并且旨在对主机网站赋予主题),并且它隐藏了外接程序 Web 内部某些无用或无意义的 SharePoint 功能。图 1 显示了使用外接程序模板的 SharePoint 托管的页面。The add-in template can be used only for SharePoint-hosted ASPX pages. The template includes the app.master master page (which contains chrome appropriate for an add-in and is designed to theme with the host site), and it hides some SharePoint functionality that either wouldn't work or doesn't make sense inside of an add-in web. Figure 1 shows a SharePoint-hosted page that uses the add-in template.

图 1. 使用外接程序模板的 SharePoint 托管的页面Figure 1. SharePoint-hosted page using the add-in template

使用应用程序模板的 SharePoint 托管的页面

创建加载项 Web 并在其中创建页面时,Visual Studio 中默认使用的是加载项模板。The add-in template is the default in Visual Studio when you create an add-in web and pages within that web.

在 SharePoint 加载项中使用部件版式控制Using the chrome control in SharePoint Add-ins

如果未生成 SharePoint 托管的 ASPX 页面,但是仍希望外接程序自然适合从中使用该外接程序的主机网站,那么部件版式控制是正确的选择。图 2 显示了部件版式控制。If you're not building SharePoint-hosted ASPX pages, but you still want your add-in to fit in naturally with the host site that it is used from, the chrome control is the right choice. Figure 2 shows the chrome control.

图 2:网页中的部件版式控制Figure 2. Chrome control on a webpage

网页中的部件版式控制

使用部件版式控制的具体步骤To use the chrome control

  1. 添加对控件库的引用。可使用以下两种方法执行此操作:Add a reference to the controls library. There are two ways to do this:

    • 指向布局文件夹根目录中的库,如以下示例中所示。Point to the library at the root of the layouts folder, as shown in the following example.

         <script 
           type="text/javascript" 
           src="http://{server URL}/_layouts/15/sp.ui.controls.js">
      </script>
      
    • 将库复制到您自己的网站,并从其中引用库。Copy the library to your own website, and reference it from there.

    注意

    如果您选择此替代方法,则您的外接程序将不会从控制更新中受益。If you opt for this alternative your add-in will not benefit from updates to the control.

  2. 添加将在其中呈现控件的占位符 DOM 元素,如此示例中所示。Add the placeholder DOM element where the control will be rendered, as shown in this example.

      <div id='chromeControlContainer'></div>
    
  3. 实例化此控件。Instantiate the control.

      function addchromecontrol(){
        var options = {};
        options.siteTitle ="{host site title}";
        options.siteUrl = "{host URL}";
        options.appHelpPageUrl = "{help page URL}";
        options.appIconUrl = "{app icon URL}";
        options.appTitle = "add-in Title";
        nav = new SP.UI.Controls.Navigation("chromeControlContainer", options);
        nav.setVisible(true);
    }
    
  4. (可选)如果不希望页面上有标题区域,可以运行下面的 JavaScript 代码来删除此区域。(Optional) If you don't want to have the title area on your page, you can remove it by running the following JavaScript code.

      nav.setBottomHeaderVisible(false);
    

部件版式控制提供了两个可选加载项图标:一个位于顶部导航栏,另一个位于标题区域。The chrome control provides for two optional add-in icons: one on the top navigation bar and one in the title area. 顶部导航栏上的加载项图标为 24x24 像素 (px),标题区域中的加载项图标与 SharePoint 网站图标大小相同(最高可为 64 px,最长可为 180 px)。The add-in icon on the top navigation bar is 24 x 24 pixels (px), and the icon in the title area is the same size as SharePoint site icons—up to 64 px high by up to 180 px long. 建议使用已在白色、黑色、灰色、明亮和柔和背景上测试过的 PNG 图像,因为用户和管理员可能会更改网站主题。We recommend you use a PNG image that you have tested on white, black, gray, bright, and muted backgrounds because users and admins can change the site theme. 若要详细了解如何使用部件版式控制,请参阅在 SharePoint 加载项中使用客户端部件版式控制For more information about using the chrome control, see Use the client chrome control in SharePoint Add-ins.

在 SharePoint 加载项中创建自定义品牌 UICreating a custom branded UI in SharePoint Add-ins

如果想要在外接程序内使用您自己的标记,而不是与主机网站的主题保持一致并适合在其中安装了外接程序的 SharePoint 网站,您将必须从头生成您的版式。然而,您仍然应该在页面的左上角(在从右到左 [RTL] 的语言中的右上方)中保留"返回网站"链接,此链接可以将用户重定向回在其中安装外接程序的网站。If, instead of aligning to the host site's theme and fitting into the SharePoint site where your add-in is installed, you want to use your own brand inside your add-in, you will have to build your chrome from scratch. However, you should still have a "back to site" link in the upper-left corner of the page (upper-right in right-to-left [RTL] languages) that redirects the user back to the site where the add-in is installed.

在 SharePoint 加载项中使用主机 Web CSSUsing the host web CSS in SharePoint Add-ins

通过使用在主机 Web 上使用的相同样式,您可以确保外接程序将与它们所来自的 SharePoint 网站保持一致。实际样式可能会根据网站设计发生变化,但是通过引用主机 Web 的 CSS 文件,您将知道无论在哪里安装外接程序,该外接程序均合适。By using the same styles that are used on the host web, you can ensure that your add-ins will remain consistent with the SharePoint site that they came from. The actual styles may change based on the design of the site, but by referencing the CSS file of the host web, you will know that your add-in will fit in no matter where it's installed.

若要从主机 Web 中获取 CSS 样式,您必须引用其 CSS 文件。您可以通过几种不同的方式来执行此操作。To get the CSS styles from the host web, you have to reference its CSS file. You can do this in several different ways.

引用主机 Web 的 CSS 文件To reference the host web's CSS file

  1. 如果使用的是外接程序模板或外接程序部件版式控制,则会自动为你处理此事。If you're using the add-in template or add-in chrome control, this is automatically taken care of for you.

  2. 如果您在外接程序 Web 内,则通过将以下代码放在母版页或 ASPX 页面上,您可以使用 CssRegistrationCssLink 控件引用 CSS 文件:If you're inside the add-in web, you can use the CssRegistration and CssLink controls to reference the CSS file by putting the following code on either your master page or ASPX page:

      <SharePoint:CssRegistration runat="server" name="default" />
    <SharePoint:CssLink runat="server />
    
    
  3. 通过生成一个 URL 以离开主机 Web 的 URL,您可以使用 元素引用 CSS 文件,如此示例中所示。You can use a element to reference the CSS file by building a URL off of the host web's URL, as shown in this example.

      <link rel="stylesheet" href="{host web URL}/_layouts/15/defaultcss.ashx" />
    

    如果使用这种方法,必须在页面上运行 JavaScript,才能从查询字符串中获取主机 Web URL。If you use this approach, you have to run JavaScript on the page to get the host web's URL off the query string. 然后,可以先将主机 Web URL 插入 link 元素,再将此元素写入页面的 DOM。You can then insert the host web's URL into the link element before you write the element to the page's DOM.

若要设置加载项样式,首先要尽可能使用语义 HTML。The first thing to do when you are styling your add-in is to use semantic HTML as much as possible. 也就是说,要对各种标题使用 H1H2H3 等,并对按钮使用输入标记。That means using H1, H2, H3, and so on, for the various headings and input tags for buttons. 此外,还应尽可能使用 SharePoint 核心样式,以便在主机网站的主题发生变化时,加载项可以顺畅地自动应用这些更改。You should also try to use SharePoint core styles as much as possible so that when the theme of the host site changes, your add-in picks up those changes seamlessly and automatically. 下表展示了默认主题中使用的样式。The following tables show how styles are used in the default theme.

表 1:正文文本样式Table 1. Body text styles

示例Example 用途Used for 样式Style
ms-textXLarge 特大正文文本Extra large body text .ms-textXLarge.ms-textXLarge
ms-textlarge 大号正文文本Large body text .ms-textLarge.ms-textLarge
body 普通正文文本Normal body text 自动继承Inherited automatically
ms-textsmall 小号正文文本Small body text .ms-textSmall.ms-textSmall
ms-metadata 元数据文本Metadata text .ms-metadata.ms-metadata

表 2. 标题和页眉样式Table 2. Title and header styles

示例Example 用途Used for 样式Style
ms-core-pagetitle 页面上的主标题Main title on the page. .ms-core-pageTitle.ms-core-pageTitle
h1 对话框、表单、博客和讨论帖的标题。Title for dialog boxes, forms, blogs, and discussion posts. 它是占据整个页面(有别于常规 wiki 网页或 Web 部件页)的特殊内容类型或加载项的备用“主”标题。It's an alternative "primary" title for special content types or add-ins that take up the entire page that you want to be different from a regular wiki or web parts page. H1H1
h2 相对于 H1 的副标题。例如,社区对文章标题使用 H1 强调文字颜色,对文章的最佳“响应”使用 H2 强调文字颜色。Secondary heading in relation to H1. For example, Communities uses H1 Accent for the title of a post, and H2 Accent for the best "response" to the post. H2H2
h3 通常是 H2 下面的副标题。Generally a subheading under H2. H3H3
h4 H3 下面的副标题。Subheadings under H3. H4H4
ms-webpart-titletext 页面上的主要 Web 部件的标题或主要部分标题的标题。Title of the main/primary Web Part on a page, or for main section headers. .ms-webpart-titleText.ms-webpart-titleText
ms-dlg-heading 用作对话框或标注内的标题的标题。Title for headings within dialog boxes or callouts. .ms-dlg-heading.ms-dlg-heading

表 3. 导航样式Table 3. Navigation styles

示例Example 用途Used for 样式Style
QuickLaunchHeading 左侧导航栏的标题。Heading of the left navigation bar. .ms-core-listMenu-verticalBox > .ms-core-listMenu-root > li > .ms-core-listMenu-item.ms-core-listMenu-verticalBox > .ms-core-listMenu-root > li > .ms-core-listMenu-item
QuickLaunchLink 左侧导航栏中的链接。Link in the left navigation bar. .ms-core-listMenu-verticalBox.ms-core-listMenu-verticalBox
QuickLaunchSelected 左侧导航栏中的选定项。Selected item in the left navigation bar. .ms-core-listMenu-verticalBox + .ms-accentText.ms-core-listMenu-verticalBox + .ms-accentText
TopNav 顶部导航栏中的项。Item in the top navigation bar.
TopNavSelected 顶部导航栏中的选定项。Selected item in the top navigation bar.

表 4. 命令样式Table 4. Command styles

示例Example 用途Used for 样式Style
ms-commandlink 用户预期会在给定容器或页面中采取的主要操作的链接。Primary action links that you expect the user to take within a given container or page. 例如,这用于设置标注下方命令的样式。For example, this would be used to style the commands underneath a callout. 对于已访问和未访问的命令,这始终都会显示相同颜色。This will always be the same color for visited and non-visited commands. .ms-commandLink.ms-commandLink
ms-secondarycommandlink 也用于设置操作链接的样式,但适合次要于内容的操作。此样式用于这些次要操作,因此其被关注的程度比不上内容。Also used to style action links, but for actions that are secondary to the content. This style is used for these secondary actions, so they don't compete with content for attention. .ms-secondaryCommandLink.ms-secondaryCommandLink
ms-calloutlink 标注中的链接。Links in the callout. .ms-calloutLink.ms-calloutLink

表 5. 修饰符样式Table 5. Modifier styles

示例Example 用途Used for 样式Style
ms-accenttext 将为文本提供当前主题中的强调文字颜色的帮助器类。Helper class that will provide the accent color from the current theme for text. .ms-accentText.ms-accentText
超链接 内容中的链接应该继承自默认的超链接样式设置和行为。超链接样式设置会应用颜色和悬停效果以指明这是链接而不是普通文本。Links in the content should inherit from default hyperlink styling and behavior. Hyperlink styling applies a color and a hover effect to indicate that it's a link instead of normal text. 通过使用 继承。Inherited from using .
ms-error 表单中出现的错误消息。Error messages that occur in forms. .ms-error.ms-error
ms-soften 为着重程度应不如普通正文文本的文本提供柔和灰色的帮助器类。Helper class that provides a softened gray for text that should be less emphasized than normal body text. .ms-soften.ms-soften
ms-disabled 对文本应用“已禁用”颜色的帮助器类,这用于表示禁用状态。Helper class that applies the "disabled" color to text, which is used for denoting disabled states. .ms-disabled.ms-disabled
ms-uppercase 将文本转换为全大写的帮助器类。Helper class that transforms the text to all caps. .ms-uppercase.ms-uppercase
ms-helper 用于将文本样式设置为与表单相似的帮助器类。Helper class to style text like forms. .ms-helper.ms-helper
hr 用于在快速启动和菜单中分隔部分的虚线分隔线。Dashed line divider that is used to divide sections in the Quick Launch and in menus. HRHR

表 6. 部件用户界面样式Table 6. Part user interface styles

示例Example 用途Used for 样式Style
拖动文件 部件顶部的主要嵌入式文本。Main inline text at the top of a part. .ms-textXLarge + .ms-soften.ms-textXLarge + .ms-soften
ms-herocommandlink 部件顶行中的命令;每个部件最多只能有一两个顶行命令。Commands in the top line of a part; at most there should be only one or two of these per part. .ms-heroCommandLink.ms-heroCommandLink
ms-attractmode 所显示用于在部件不包含数据时诱惑用户与部件交互的文本。Text shown to entice the user to interact with the part when it doesn't contain data. .ms-attractMode.ms-attractMode
ms-emptymode 在没有可用数据时向用户显示的文本。Text shown to the user when there is no data available. .ms-emptyMode.ms-emptyMode
mspivotlink 视图控件,如透视。View controls, such as a pivot. .ms-pivot-link.ms-pivot-link
ms-listlink 也为链接的列表项。List items that are also links. .ms-listLink.ms-listLink

表 7. 背景和边框样式Table 7. Background and border styles

|示例Example|用途Used for|样式Style| |:-----|:-----|:-----| |ms-emphasis|设置应该在页面上重点强调的矩形的样式。To style a rectangle that should be heavily emphasized on the page.|.ms-emphasis.ms-emphasis| |ms-emphasisborder|强调的元素的边框。Border of an emphasized element.|.ms-emphasisBorder.ms-emphasisBorder| |ms-subtleemphasis|元素的更细微的强调。A more subtle emphasis of an element.|.ms-subtleEmphasis.ms-subtleEmphasis| |ms-subtleemphasiscommand|采用 ms-subtleEmphasis 设置样式的元素中的命令。Commands in an element styled with ms-subtleEmphasis.|.ms-subtleEmphasisCommand.ms-subtleEmphasisCommand| |ms-subtleemphasiscommand-disabled|采用 ms-subtleEmphasis 设置样式的元素中的禁用命令。Disabled command in an element styled with ms-subtleEmphasis.|.ms-subtleEmphasisCommand-disabled.ms-subtleEmphasisCommand-disabled| |ms-sidenav|侧导航栏元素Side navigation elements.|.ms-sideNav.ms-sideNav| |ms-sidenav-selected|设置所选侧导航栏元素的样式。To style the selected side navigation element.|.ms-sideNav-selected.ms-sideNav-selected| |ms-lines|使用边框强调元素。To emphasize an element using a border.|.ms-lines.ms-lines| |ms-subtlelines|使用细微型边框强调元素。To emphasize an element using a subtle border.|.ms-subtleLines.ms-subtleLines| |ms-stronglines|使用增强或彩色的边框强调元素。To emphasize an element using a strong or colored border.|.ms-strongLines.ms-strongLines| |ms-disabledlines|使用边框强调禁用的元素。To emphasize a disabled element using a border.|.ms-disabledLines.ms-disabledLines| |ms-accentlines|使用强调文字颜色边框强调元素。To emphasize an element using an accent border.|.ms-accentLines.ms-accentLines| |ms-popupborder|包含弹出窗口。To contain pop-up windows.|.ms-popupBorder.ms-popupBorder| |ms-bgoverlay|对背景元素应用覆盖。To apply an overlay on the background element.|.ms-bgOverlay.ms-bgOverlay| |bgdisabled|使元素的背景显示为禁用状态。To make the background of an element appear disabled.|.ms-bgDisabled.ms-bgDisabled| |ms-bgheader|应用页眉背景色。To apply the header background color.|.ms-bgHeader.ms-bgHeader| |ms-bgfooter|应用页脚背景色。To apply the footer background color.|.ms-bgFooter.ms-bgFooter| |md-bghoverable 正常|悬停时应具有高亮颜色的元素。此示例显示了其上未悬停鼠标时的元素。Elements that should have a highlighted color on hover. The example shows the element when the mouse is not hovering over it.|.ms-bgHoverable.ms-bgHoverable| |ms-bghoverable-onhover|悬停时应具有高亮颜色的元素。此示例显示了其上悬停鼠标时的元素。Elements that should have a highlighted color on hover. The example shows the element when the mouse is hovering over it.|.ms-bgHoverable.ms-bgHoverable| |ms-bgselected|显示对元素所做的选择。To show selection on an element.|.ms-bgSelected.ms-bgSelected| |ms-topbar|页面顶栏中的元素。Elements in the top bar of the page.|.ms-topBar.ms-topBar| 有关详细信息,请参阅在 SharePoint 加载项中使用 SharePoint 网站的样式表For more information, see Use a SharePoint website's style sheet in SharePoint Add-ins.

在 SharePoint 加载项中统一设置常用项的样式Styling common items consistently in SharePoint Add-ins

为了帮助用户学习如何在 SharePoint 和加载项之间互换,应统一设置多个常用元素的样式。To help users learn skills that translate between SharePoint and add-ins, you should style several common elements consistently.

内部导航Internal navigation

若要在加载项内实现导航,可采用以下两个主要模式:左侧导航顶部导航To provide navigation within your add-in, there are two main patterns to follow: left navigation and top navigation. 具体使用哪个选项在某种程度上取决于加载项其余部分的内容是什么。Which option you use depends somewhat on what the content is in the rest of your add-in. 一般来说,左侧导航是正确选择,尤其是要在不同列表之间进行切换时,或加载项的重点是母版-详细信息视图时。In general, left navigation will be the correct choice, particularly if you're switching between different lists, or the focus of your add-in is a master-detail view. 然而,如果导航主要用于切换(所谓的)同一列表的不同视图,可以选择改用顶部导航。On the other hand, if your navigation mainly switches between what could be considered different views of the same list, you could choose to use top navigation instead.

左侧导航和顶部导航都具有对象模型表示形式,在 SharePoint 中设置这些表示形式时将正确设置其样式。在 SharePoint 页面之外,您必须做少量的其他工作才能亲自为顶部或左侧导航创建标记,然后必须添加合适的 CSS 类,以便正确设置其样式。Both left navigation and top navigation have object model representations that will be styled correctly when they are set in SharePoint. Outside of SharePoint pages, you'll have to do a bit more work to create the markup for the top or left navigation yourself, and then add the appropriate CSS classes so that it's styled correctly.

工具栏Toolbars

在许多情况下,要向用户快速呈现的命令很少。In many cases, you will have a small number of commands that you want to surface quickly to the user. 如果已在页面上使用功能区,最佳选择是将这些命令添加到现有功能区内的逻辑位置上。If you are using the ribbon on your page already, the best choice is to add those commands to logical locations within the existing ribbon. 不过,如果页面上尚无功能区,为了屈指可数的几个命令而添加功能区可能并不合理。However, in the case where you don't already have a ribbon on the page, it probably doesn't make sense to add one for a handful of commands. 在这种情况下,建议向将应用命令的项添加工具栏上下文。In that case, we recommend that you add a toolbar contextual to the item where the commands will apply. 应使用字形和/或使用 ms commandLink 设置样式的文本,在工具栏上表示命令,工具栏的背景色应与页面的其余部分一样。You should use either glyph, text styled with ms-commandLink, or both, to represent your commands on the toolbar, which should have the same background color as the rest of the page.

列表Lists

列表是向用户呈现数据的一种常用方法。如果您的外接程序使用的是 SharePoint 页面,则可以使用列表视图 Web 部件向用户呈现数据,以及获取其附带的样式和交互。然而,如果在别处具有页面,或者想要加强控制用户与列表的交互,则应该在 SharePoint 中模仿列表样式,同时提供自己的呈现和交互方式。以下是在外接程序中使用列表时要记住的一些样式问题:Lists are a common way to represent data to users. If your add-in is using SharePoint pages, you could use the List View Web Part to represent the data to users and get the styling and interaction that comes with it. However, if you have your pages elsewhere, or you want more control over the interaction that users have with your list, you should mimic the styling of lists in SharePoint while providing your own rendering and interaction. The following are some style issues to keep in mind when you are using lists in your add-in:

  • 视图: 在单一列表上呈现多个视图时,应该在列表顶部使用透视,就像在常规 SharePoint 列表顶部使用透视一样。绝不要使用透视作为呈现主要详细信息数据的方法。Views: When representing multiple views on a single list, you should use a pivot at the top of the list, just as regular SharePoint lists do. You should never use pivots as a way of representing master-detail data.

  • 筛选器: 在现有列表或主要详细信息排列上提供筛选器时,应该使用与内容区域左侧对齐并且宽度至少为 300 像素的提要栏。您还应该复制 SharePoint 选择样式,以向用户指明所选择的筛选器或项目。Filters: When providing a filter on an existing list or a master-detail arrangement, you should use a sidebar that is flush with the left side of the content area and that is at least 300-pixels wide. You should also copy the SharePoint selection styling to indicate to the user which filters or items are selected.

  • 表单: 如果用户要查看或编辑单个项目,则应该使用内置的 SharePoint 表单或者模仿其样式以获取一致的体验。Forms: When a user is viewing or editing a single item, you should either use the built-in SharePoint forms or mimic their styling for a consistent experience.

表单、对话框和标注Forms, dialog boxes, and callouts

以下三种不同的模式可向用户提供关于对象的详细信息,或者提供用于用户输入的用户界面 (UI):完整页面表单、对话框和标注。具体使用哪一种,则取决于用户意图以及将显示或请求的信息量。There are three distinct patterns for providing the user with more information about an object, or for providing a user interface (UI) for user input: full-page forms, dialog boxes, and callouts. Whichever one you use depends on the user intent and how much information will be shown or requested.

  • 完整页面表单: 如果想要用户输入若干条不同的信息,或者想要同时向用户显示许多结构化信息,那么这是最佳选择。此外,在需要诸如功能区之类的更复杂交互模型的情况下,完整页面表单最有意义。在此情况下,必要时应将用户指向表单页面。应确保可以使用按钮或功能区以明确的方式保存或取消用户的更改。在可能需要滚动的非常长的表单中,在表单的顶部和底部放置“保存”**** 和“取消”**** 选项是一个好主意。Full-page forms: This is the best choice when you want users to enter several different pieces of information, or you want to show them a lot of structured information at one time. Full-page forms also make the most sense in scenarios where more complex interaction models, such as the ribbon, are required. In this case, you would point the user to the form page when necessary. You should make sure that there is a clear way to save or cancel their changes, by using either buttons or the ribbon. In very long forms that might require scrolling, it's a good idea to place the Save and Cancel options at both the top and bottom of the form.

  • 对话框: 这些是模式 UI 容器,通常用于根据上下文显示更多信息和操作。它们还用于更短的表单或用户输入。通常,在对话框中托管的 UI 应该既简单又非常适合较小的呈现图面。而完整页面表单可以更好地为诸如功能区之类的较长表单或较复杂交互模型提供服务。Dialog boxes: These are modal UI containers that are typically used to show more information or actions in a contextual manner. They are also used for shorter forms or user input. In general, the UI that is hosted within a dialog box should be simple and well suited for a smaller rendering surface. Longer forms or more complex interaction models, such as the ribbon, are better served by full-page forms instead.

  • 标注: 这些标注围绕着特定项提供相关的上下文信息和操作。标注通常用于在轻型 UI 中向用户显示关于某个项的更多信息或操作。如果滚动条或用户输入是必需的,则标注可能不是一个好的选择。Callouts: These provide relevant contextual information and actions around a particular item. Callouts are generally used to show the user more information or actions about an item in a lightweight UI. If scrollbars or user input are necessary, the callout is probably not a good choice.

动画Animation

虽然动画能够产生更加鲜明和动人的体验,但是应该小心不要在您的 UI 中过度使用动画。用户几乎不会注意到制作精美的动画,但是,它能够给人一种更快更好地执行 UI 的印象。使用动画时,应该确保遵循像物理学和惯性这样的原理,并提供看上去自然且优美的 UI。我们建议不要过度使用动画,如过度跳动或过度灵活,或者在进行最微小的用户操作时让对象在屏幕四周飘移。通常,对象应该采用到其目标的直接路径,并且,为了使用户能够感觉到发生了移动,通常只需要对实际更改的前面或最后 10% 进行动画处理。Although animation can lead to a more vibrant and engaging experience, you should be careful to not overuse it in your UI. Animation that is done well will be hardly noticeable by the user, but it will give the impression of faster, better-performing UI. When using animation, you should make sure to respect concepts like physics and inertia and provide UI that seems natural and graceful. We strongly recommend against exaggerated animations like excessive bouncing or elasticity, or having objects fly around the screen at the slightest user action. Objects should generally take a direct path to their destination, and often will only need the first or last 10 percent of the actual change to be animated in order to give the user the sense that it has moved.

选项卡和数据透视Tabs and pivots

在 SharePoint 中,只应该在功能区上使用选项卡。在 SharePoint 中的其他每个地方,都应该使用透视来表示更改内容区域的概念。In SharePoint, the only place where you should use tabs is on the ribbon. Everywhere else in SharePoint should use pivots to express the concept of changing the content area.

与结合使用 Office UI Fabric 和 SharePoint 加载项相关的 FAQOffice UI Fabric with SharePoint Add-ins FAQ

使用此常见问题来了解如何使用 Office UI Fabric 并使您的 SharePoint 外接程序的外观与 Office 365 的其余部分相似。Use this FAQ to understand how to use Office UI Fabric and make your SharePoint Add-in look and feel like the rest of the Office 365.

1. 什么是 Office UI Fabric?1. What is Office UI Fabric?

Office UI Fabric 是响应迅速且移动设备优先的前端框架,可便于使用 Office 设计语言创建 Web 体验。Office UI Fabric is a responsive, mobile-first, front-end framework that enables you to create web experiences by using the Office Design Language. 它是通过一组字体和和 CSS 类实现,这些类提供 UI 组件、图标、动画和官方 Office 调色板。It is implemented with a set of fonts and with CSS classes that provide UI components, icons, animation, and the official Office color palette. 有关详细信息,请参阅 Office UI FabricFor details, see Office UI Fabric.

2. 能否在我的 SharePoint 加载项中使用 Office UI Fabric?2. Can I use Office UI Fabric in my SharePoint Add-ins?

可以。你的外接程序页面可以使用与引用其他 CSS 框架(如 bootstrap)的相同方式来引用 Office UI Fabric 文件。Yes. Your add-in pages can reference the Office UI Fabric files in the same way that other CSS frameworks, like bootstrap, are referenced.

3. 我应当何时将 Office UI Fabric 与 SharePoint 外接程序协同使用?3. When should I use Office UI Fabric with SharePoint Add-ins?

当您想让您的外接程序具有 Office 365 的外观体验时,就可以使用它。它是使用 SharePoint 主机 Web 的 CSS 文件的一种可替代方法。Use it when you want your add-in to have the look and feel of Office 365. It is an alternative to using the CSS file of the SharePoint host web.

4. 如何在 SharePoint 加载项中使用 Office UI Fabric?4. How can Office UI Fabric be used in SharePoint Add-ins?

只需将 Office UI Fabric 文件添加到开发项目,并向 HTML 或 ASPX 页面添加对 fabric.css 库的引用即可。Just add the Office UI Fabric files to your development project, and include a reference to the fabric.css library to your HTML or ASPX page. 有关详细信息,请参阅入门For details, see Getting started.

5. 如何在 SharePoint 加载项中使用 Office UI Fabric 组件?5. How can Office UI Fabric Components be used in SharePoint Add-ins?

只需向 HTML 或 ASPX 页面添加对 fabric.components.css 库的引用即可。Just add a reference to the fabric.components.css library to your HTML or ASPX page. 有关详细信息,请参阅入门For details, see Getting started.

6. 能否结合使用 Office UI Fabric 和 SharePoint 加载项的主机 Web CSS?6. Can I use Office UI Fabric along with a SharePoint Add-in's host web CSS?

目前,我们建议不要混合使用 Office UI Fabric 和主机 Web CSS。这是为了防止类名冲突和样式不匹配。Currently, we recommend against mixing Office UI Fabric with host web CSS. This is to prevent class name collisions and style mismatches.

7. Office UI Fabric 是否支持 SharePoint 主题?7. Does Office UI Fabric support SharePoint themes?

否,Office UI Fabric 不支持 SharePoint 主题。No, Office UI Fabric does not support SharePoint themes. 不过,应用 Office UI Fabric 主题不会与 SharePoint 主题相冲突。However, applying Office UI Fabric theming will not conflict with SharePoint themes.

扩展加载项中的 SharePoint UIExtending SharePoint UI in add-ins

SharePoint 允许外接程序扩展现有 UI 的某些部分,这样,您就可以在用户可能需要外接程序的地方提供外接程序。您可以使用以下方法扩展主机 Web 的 UI:SharePoint allows add-ins to extend some of the existing UI, which enables you to make your add-in available in the places where users might need it. You can extend the host web's UI by using the following methods:

  • 外接程序部件: 使你能够显示 iframe 元素以包含外接程序中的内容。Add-in parts: Enable you to surface an iframe element to contain content from your add-in.

  • 自定义操作: 您可以通过自定义操作扩展功能区或上下文菜单。利用自定义操作,可以在列表项、文档或显示功能区的任何其他地方使用您的外接程序。Custom actions: You can extend the ribbon or contextual menu through custom actions. Custom actions make your add-in available on list items or documents, or anywhere else the ribbon is shown.

将外接程序部件添加到主机 Web 中Adding add-in parts to the host web

部件 是供外接程序在安装了外接程序的主机 Web 中显示某些信息或小交互点的一种方法。最终用户通过在 SharePoint 中使用 Web 部件框架,可以在其页面中嵌入这些部件。图 3 将标记云部件显示为部件示例。Parts are a way for your add-in to surface some information or a small interaction point in the host web where the add-in is installed. End users can embed those parts in their pages by using the Web Part framework in SharePoint. Figure 3 shows the tag cloud part as an example of a part.

图 3. 标记云部件Figure 3. Tag cloud part

“标记云”部件

In Figure 3, the Tag Cloud from UX Design add-in is the title of the part. The tag cloud itself is served from the add-in content, and it is hosted in an iframe element and fully isolated from the hosting page. Because the add-in content is using the host web's CSS file, it fits in seamlessly with the host page.In Figure 3, the Tag Cloud from UX Design add-in is the title of the part. The tag cloud itself is served from the add-in content, and it is hosted in an iframe element and fully isolated from the hosting page. Because the add-in content is using the host web's CSS file, it fits in seamlessly with the host page.

某些类型的 UI 非常适合通过部件 UI 来公开。例如,您可能想要提供一组不同外接程序体验的快捷方式,或者甚至想提供用户可在其他页面上嵌入的单一启动点。另一个用户可能要在应用程序中显示一小部分数据,或者显示最近对某些内容所做的更改。您可能需要提供一个小型交互区域,以利用外接程序执行快速操作,而不必打开外接程序来执行这些操作。您提供的部件的类型将由外接程序支持的方案来控制。您应该记住并非所有外接程序都有部件,只有部件对用户体验有意义时才应该提供部件。Some kinds of UI lend themselves well to being exposed through part UI. For example, you might want to provide a set of shortcuts into different experiences of your add-in, or even a single launch point that users can embed on other pages. Another use might be to show a small subset of the data in the add-in, or show the most recent changes to something. You might want to provide a small interactive zone for performing quick actions with the add-in without having to open it to do so. What type of part you provide will be driven by the scenarios your add-in supports. You should keep in mind that not all add-ins will have parts, you should only provide them if they make sense for the user experience.

在此部件中显示的页面托管在 iframe 中,因此应确保用户编写的所有 JavaScript 都已注意到这一点,并能够非常智能地访问窗口对象等内容。The page you display inside the part will be hosted in an iframe, so you should make sure that any JavaScript you write is aware of that and is smart about accessing things like the window object. 即使加载项的其余部分有大量品牌样式,也应考虑对此部件采用主机 Web 样式,因为它会嵌入主机 Web 页面中,而如果不适应的话,则会看起来非常突兀和不好看。Even if the rest of your add-in is heavily branded, you should consider adopting the host web's styling for your part, because it will be embedded within the host web's pages and will look jarring and unappealing if it doesn't fit in. 若要使用主机 Web 样式,必须手动生成默认 CSS 文件的链接。In order to use the host web's styling, you'll have to build the link to the default CSS file manually. 有关详细信息,请参阅本文中的如何:引用主机 Web CSS 文件For more information, see How to: Reference the host web's CSS file in this article. 此外,页面上不得有任何部件版式,因为它嵌入到的页面本身已有部件版式。There also should not be any chrome on the page, because it will be embedded on a page that already has chrome itself.

页面必须跨不同的域在 iframe 中很好地工作,因此,必须确保不要仅对本页面的 X-Framing-Options 指定相同的源。默认情况下,SharePoint 页面的确规定页面应该仅在相同域内的 iframe 中。因此,对于 SharePoint 中托管的页面,必须在页面上的某个地方添加 AllowFraming Web 部件,以便不为想要在部件中显示的页面选择该行为,如以下示例中所示。The page has to work nicely in an iframe across different domains, so you'll have to make sure that you do not specify same-origin only for X-Framing-Options of this page. By default, SharePoint pages do specify that they should only be in an iframe within the same domain. So for pages that are hosted in SharePoint, you'll have to opt out of that behavior for the pages you want to show in parts by adding the AllowFraming Web Part somewhere on the page, as shown in the following example.

<WebPartPages:AllowFraming ID="AllowFraming1" runat="server" />

因为无法强行规定用 Iframe 将页面嵌入到哪些域中,所以在外接程序部件中托管的页面很容易受到点击劫持安全攻击。在点击劫持攻击中,页面可能位于恶意页面上的 iframe 中,并且可能会引诱用户选择按钮以执行他们不了解的操作。设计页面时,应该注意这一点,如果恶意页面中显示了将具有危险性的部件,则应确保不要在页面中对该部件公开任何功能。Because you cannot enforce which domains your pages are iframed into, the pages you host in add-in parts are vulnerable to a clickjacking security attack. In clickjacking attacks, pages can be in an iframe on a malicious page, and users could be tricked into choosing buttons to take actions they're not aware of. When designing your page, you should be aware of this and make sure you're not exposing any functionality in the page for the part that would be dangerous if surfaced in a malicious page.

虽然用户可以对部件手动设置不同的大小,但是您可以在部件定义中为部件设置特定大小。您还可以请求通过 postmessages 动态调整部件的大小。默认情况下,建议以 30px 为增量为您的部件选择大小(例如 150px 或 210px),以便在相同页面上混合来自不同外接程序的部件时,用户仍然可以感觉出为在相同区域中工作已生成了每个部件。如果想要部件从入门体验中模仿平铺,则部件的高度和宽度应该为 150px。如果想要部件显示在侧栏中以显示详细信息,则部件的宽度应该为 300px。Although users can manually set a different size on your part, you are able to set a particular size for the part in the part definition. You also have the ability to request that your part is resized dynamically through postmessages. By default, we recommend that your part choose sizes in increments of 30px (for example, 150px or 210px) so that when parts from different add-ins are mixed on the same page, the user can still get a sense that each of the parts was built to work in the same space. If your part is meant to mimic a tile from the getting started experience, it should have a height and width of 150px. If the part is meant to display in a side column to show details, it should have a width of 300px.

如果您的部件显示动态内容,则请求调整大小以减少页面内所嵌入的滚动条是一个好主意。以下示例向您表明如何使用 postmessages 调整部件的大小:If your part displays dynamic content, it's a good idea to request a resize to reduce having scrollbars embedded within a page. The following example shows you how to use postmessages to resize the part:

window.parent.postMessage('<message senderId={your ID}>resize(120, 300)</message>', {hostweburl});

在以上示例中,呈现页面时,外接程序部件代码将对页面的查询字符串自动设置 senderId 值。在请求调整大小时,您的页面只需从查询字符串中读取 SenderId 值并使用该值即可。您可以通过将 StandardTokensHostUrl 令牌追加到外接程序部件定义中的 Src 属性来检索查询字符串的主机 Web URL。In the example above, the senderId value will be set on the query string of the page automatically by the add-in part code when the page is rendered. Your page would just need to read the SenderId value off of the query string and use it when requesting a resize. You can retrieve the host web URL from the query string by appending the StandardTokens or HostUrl tokens to the Src attribute in your add-in part definition.

要为主机 Web 指定部件,您必须在外接程序包内的功能文件(不是包内 WSP 中的功能文件)中指定客户端 Web 部件。您可以创建可由最终用户配置的部件,如通过指定 ZIP 或邮政编码来创建。以下标记指定了外接程序部件,并且 Properties 元素为可选元素:To specify a part for the host web, you must specify a client Web Part in the feature file in the add-in package (not the feature file in the WSP in the package). You can create a part that could be configurable by the end user, such as by specifying a ZIP or postal code. The following markup specifies an add-in part, and the Properties element is optional:

<ClientWebPart 
    Name="Sample Add-in Part" 
    DefaultWidth="600" 
    DefaultHeight="300" 
    Title="Sample Add-in Part" 
    Description="This is a sample part with properties.">
    <Content Type="html" Src="~appWebUrl/Pages/Part.aspx?Property1=_prop1_&amp;amp;Property2=_prop2_&amp;amp;Property3=_prop3_&amp;amp;Property4=_prop4_" />
    <Properties>
        <Property 
            Name="prop1" 
            Type="string" 
            WebBrowsable="true" 
            WebDisplayName="First Property" 
            WebDescription="Description 1" 
            WebCategory="Custom Properties" 
            DefaultValue="String Property" 
            RequiresDesignerPermission="true" />
        <Property 
            Name="prop2" 
            Type="boolean" 
            WebBrowsable="true" 
            WebDisplayName="Second Property" 
            WebDescription="Description 2" 
            WebCategory="Custom Properties" 
            DefaultValue="TRUE" 
            RequiresDesignerPermission="true" />
        <Property 
            Name="prop3" 
            Type="int" 
            WebBrowsable="true" 
            WebDisplayName="Third Property" 
            WebDescription="Description 3" 
            WebCategory="Custom Properties" 
            DefaultValue="1" 
            RequiresDesignerPermission="true" />
        <Property 
            Name="prop4" 
            Type="enum" 
            WebBrowsable="true" 
            WebDisplayName="Fourth Property" 
            WebDescription="Description 4" 
            WebCategory="Custom Properties" 
            DefaultValue="one" 
            RequiresDesignerPermission="true" >
            <EnumItems>
                <EnumItem Value="one" WebDisplayName="One" />
                <EnumItem Value="two" WebDisplayName="Two" />
                <EnumItem Value="three" WebDisplayName="Three" />
            </EnumItems>
        </Property>
    </Properties>
</ClientWebPart>

在您的 ClientWebPart 元素中,您将指定以下各项:In your ClientWebPart element, you'll want to specify the following things:

  • 名称: 用于标识外接程序的内部名称;必须是唯一的。Name: An internal name that is used to identify the add-in; must be unique.
  • DefaultWidth/DefaultHeight: Web 部件的默认大小。如有必要,可以在部件内部调整页面大小。DefaultWidth/DefaultHeight: The default size of the Web Part. If necessary, you can resize the page inside the part.
  • 标题: 最终用户通过 Web 部件添加器将部件添加到页面中时向最终用户显示的名称。Title: The name that is displayed to end users when they add your part to a page through the Web Part adder.
  • 描述: 最终用户通过 Web 部件添加器将部件添加到页面中时向最终用户显示的描述。Description: The description that is shown to end users when they add your part to a page through the Web Part adder.

您可以指定 stringenumintBoolean类型的部件属性。也可以使用 WebCategory 特性指定想要在其中显示您的属性的 toolpart 类别。您想要指定的 Property 元素的属性如下:You can specify part properties of type string, enum, int, and Boolean. You can specify the toolpart category that you want your properties to appear in by using the WebCategory attribute. The attributes on the Property element that you want to specify are as follows:

  • 名称: 用于将此属性与查询字符串上要替换的令牌匹配的名称。Name: The name used to match this property with a token on the query string to replace.
  • WebDisplayName: 工具部件中使用的名称。WebDisplayName: The name used in the tool part.
  • WebCategory: 要将此属性添加到的工具窗格中的工具部件。WebCategory: The tool part in the toolpane to add this property to.
  • 类型: 期待用户提供的输入数据类型。类型可以为 stringenumintBooleanType: The input data type that is expected from the user. Type can be string, enum, int, or Boolean.
  • DefaultValue: 属性的默认值。DefaultValue: The default value for your property.

向页面添加部件时,查询字符串中与 propertyName are 模式匹配的任何字符串会被自动替换为在 Web 部件实例上具有该名称的属性的值,如果用户尚未设置该值,则会替换为默认值。然后您应该运行页面内的代码以通过查询字符串进行分析,并提取属性以在页面呈现和交互中使用这些属性。When the part is added to the page, any strings in the query string that match the pattern propertyName are automatically replaced with the value of the property with that Name on the Web Part instance, or the default value if the user hasn't set it. You would then run code inside the page to parse through the query string and pull out the properties to use them in rendering and interaction on your page.

还可以使用 wpid 字符串表示查询字符串内的替换位置,从而通过查询字符串发送 Web 部件 ID。You can also choose to have the Web Part ID sent on the query string by using the wpid string to represent where you want it to be replaced on the query string. 如果希望能够按每实例存储用户选择或交互信息,这样可能有助于区分不同的部件实例。This can be helpful in differentiating different part instances if you want to be able to store information about user choices or interactions on a per-instance basis. 有关详细信息,请参阅创建与 SharePoint 加载项一起安装的加载项部件For more information, see Create add-in parts to install with your SharePoint Add-in.

向主机 Web 添加自定义操作Adding custom actions to the host web

如果您所具有的功能在列表项或文档上下文中显示是有意义的,或者在主机 Web 内的特定功能区选项卡上显示是有意义的,则可以使用自定义操作将这些内容添加到上下文菜单或功能区中。若要在主机 Web 上显示自定义操作,则需要在外接程序包内某种类型的宽松功能文件中定义自定义操作,这种类型与包含 ClientWebPart 定义的类型相同。If you have functionality that would make sense to surface in the context of list items or documents, or on particular ribbon tabs in the host web, you can add those to the context menu or the ribbon by using custom actions. To surface custom actions in the host web, you'll need to define them in the same kind of loose feature file in the add-in package as the one that contains ClientWebPart definitions.

图 4. 上下文菜单中的自定义操作Figure 4. A custom action in the contextual menu

上下文菜单中的自定义操作

显示在主机 Web 中的自定义操作的代码与以前版本的 SharePoint 中的代码相同,但具有以下限制:The code for custom actions that are surfaced in the host web is the same as in previous versions of SharePoint, with the following restrictions:

  • \*\*Location\*\* 属性必须为 \*\*CommandUI.Ribbon\*\* 或 \*\*EditControlBlock**。The **Location** attribute must be either **CommandUI.Ribbon** or **EditControlBlock**.
  • CustomAction 不能包含 JavaScript:CustomAction cannot contain JavaScript:
    • 任何 UrlActionsCommandActions 都必须是要导航到的 URL。可以用普通自定义操作标记以及特定于应用程序的标记对 URL 进行参数化操作。Any UrlActions or CommandActions must be a URL to navigate to. The URL can be parameterized with normal custom actions tokens in addition to the app-specific tokens.
    • 功能区自定义中不允许使用 EnabledScriptEnabledScript is not allowed in ribbon customizations.

通常,当用户选择自定义操作时,自定义操作会根据用户的选择将用户导航到您用任何解析的标记指定的 URL。但是,在某些情况下,您可能想要用户保留在页面上下文中,例如,为了对特定文档执行快速操作。如果想要让自定义操作打开对话框,而不是导航,应该向 CustomAction 元素添加以下属性。Normally when a user chooses a custom action, it will navigate them to the URL you have specified with any tokens resolved based on their selections. However, there are some cases where you might want the user to stay in context on the page, such as for quick actions on a particular document. If you want to have your custom action open a dialog box instead of navigating, you should add the following attributes to the CustomAction element.

HostWebDialog="TRUE"
HostWebDialogHeight="500" 
HostWebDialogWidth="500"
\*\*HostWebDialogHeight\*\* 属性和 \*\*HostWebDialogWidth\*\* 属性是可选属性。如果未指定这些属性,则将使用 SharePoint 中对话框的默认大小。但是,通常,您应该指定对话框的大小,以在向用户显示对话框时,对话框看上去正常并且不使用滚动条。The **HostWebDialogHeight** attribute and the **HostWebDialogWidth** attribute are optional. If the attributes are not specified, the default size for a dialog box in SharePoint will be used. In general, though, you should specify the size of your dialog box so that it looks right and doesn't use scrollbars when it is displayed to the user.

对话框始终在对话框版式中包括"关闭"按钮。您也可以在页面上包括按钮,这些按钮将关闭对话框并告诉来源页面它是否应该刷新。如果您做了可在用户查看的视图中反映出来的某些操作(例如:更新文档属性),则应该刷新页面。另一方面,如果未更新任何项(例如:"取消"操作或将文件发送到存档但未更新任何属性),则可以告诉页面不需要刷新。以下示例向您表明如何发送"公告"消息以关闭对话框。The dialog box always includes a Close button in the dialog box chrome. You can also include buttons on your page that will close the dialog box and tell the originating page whether it needs to refresh. If you've done something that could be reflected in the view the user is looking at (for example: updating properties on a document), you should refresh the page. On the other hand, if you didn't update anything (for example: a "cancel" action or sending a file to an archive without updating any properties), you can tell the page that no refresh is necessary. The following examples show you how to send POST messages to close the dialog box.

window.parent.postMessage('CloseCustomActionDialogRefresh', '*');
window.parent.postMessage('CloseCustomActionDialogNoRefresh', '*');

根据您使用的是 CloseCustomActionDialogRefresh 还是 CloseCustomActionDialogNoRefresh,对话框将会关闭,并且会刷新其背后的页面,或者不会刷新。Depending on whether you use CloseCustomActionDialogRefresh or CloseCustomActionDialogNoRefresh, the dialog box closes, and it either refreshes the page behind it or it does not.

您无法通过外接程序将自定义选项卡添加到主机 Web 的功能区中。您只能添加自定义组或单个控件。您不应该替代任何默认的 SharePoint 功能区控件。您应该让您的控件与 SharePoint 控件并行存在。You cannot add a custom tab to the ribbon of the host web from your add-in. You can only add custom groups or individual controls. You should not override any of the default SharePoint ribbon controls. You should have your controls exist side-by-side with the SharePoint controls.

若有一些相互关联的控件,或有用户可能会与使用加载项关联起来的控件,应将它们分入自己的自定义组中,这样用户更有可能会找到它们。If you have a few controls that are related to each other, or that the user will likely associate with using your add-in, you should group them in their own custom group so that the user is more likely to find them. 然而,如果要添加的功能更有可能会被用户视为网站核心体验的一部分,应尝试将相应控件安装到现有功能区内的逻辑位置上。If, on the other hand, the functionality you're adding is more likely to be something the user considers part of the core experience of their site, you should try to fit that control into a logical spot in the existing ribbon locations. 有关详细信息,请参阅创建与 SharePoint 加载项一起部署的自定义操作For more information, see Create custom actions to deploy with SharePoint Add-ins.

为加载项配置提供设置页面Providing a settings page for add-in configuration

在许多情况下,让外接程序具有一些可由用户更改的配置信息以及让外接程序使用设置页面公开这些信息是有意义的。理想情况下,您可以为这些设置选择合理的默认值,用户只有在需要修改这些默认值时才能选择转至设置 UI。在某些情况下,运行外接程序之前,需要向外接程序提供某些信息或选项。如果外接程序在运行之前需要信息,则应该提供用户体验来指导用户到达设置页面以更新配置。In many cases, it makes sense for your add-in to have some configuration information that the user can change, and to expose this information through the use of a settings page. Ideally, you can choose reasonable defaults for those settings, and users can choose to go to the settings UI only if they need to modify those defaults. In some cases, the add-in will require certain information or choices to be provided before the add-in can function. When your add-in requires information before it can function, you should provide a user experience that guides the user to the settings page to update the configuration.

在适当情况下,应将设置页面 URL 添加到应用的右上角菜单,以便用户能够轻松找到它。You should add the settings page URL to the app's top-right menu if appropriate so that users can find it easily. 如果加载项提供入门体验或其他设置,也可以添加这些信息。If your add-in has a getting started experience or other settings, you can add those also. 有关详细信息,请参阅在 SharePoint 加载项中使用客户端部件版式控制For more information, see Use the client chrome control in SharePoint Add-ins.

您还应该记住当前正在访问外接程序的用户可能无法配置外接程序。另外,您的 UI 不应该假定当前用户能够完成配置。如果用户无法配置您的外接程序,则您的外接程序应该指导用户找到合适的人员。You should also keep in mind that the user who is currently visiting the add-in might not be able to configure it. Your UI should also not assume that the current user is able to complete the configuration. Your add-in should guide the user to find the right person if they cannot configure it.

在加载项中管理用户许可证Managing user licenses in add-ins

如果您的外接程序不是免费的,则应该在试用或非许可模式下的可用或受限功能与完全付费版本的功能之间寻找一个合理的平衡点。If your add-in is not free, you should find a good balance between the features that are available or restricted in the trial or unlicensed modes versus the fully paid version.

如果您提供限时试用版,则在试用期间,试用版应该表现得与付费版一样。请为用户提供他们对您的外接程序付款之后实际期待得到的产品。如果选择在试用期间限制某些功能,请非常明确地表明用户在付款后如何能够获得更多的功能。对于不受限制的试用版,您应该尽量向用户提供您认为需要的功能,以便他们很好地体验外接程序的价值。请说明用户在对外接程序付款后具体可获得哪些好处。If you provide a time-limited trial, the trial version should act just like the paid version during the trial period. Give users a realistic expectation of what they will get when they pay for the add-in. If you choose to restrict anything during the trial period, be very clear about how the user can get more when they pay. For unlimited trials, you should expose as much functionality as you think is needed for the user to get a good sense of the value of your add-in. Make it clear what extra benefits they would get by paying for it.

当人们首次看到您的外接程序时,他们可能没有外接程序许可证。例如,一个用户可能会将您的外接程序添加到团队网站中,但忘记给任何其他人颁发许可证。团队网站上的其他用户将在没有许可证的情况下使用您的外接程序,直到许可证经理解决这种情况为止。您应该确保他们获得一个好的印象,以便他们更有可能需要或购买许可证。始终允许用户在您的外接程序中查看和浏览数据是一个好主意。请说明具有许可证如何能够启用更多功能,但不要在每个会话中多次提醒用户。When people first see your add-in, they may not have a license for it. For example, one user might add your add-in to a team site, but forget to license anyone else. Other users on the team site would be using your add-in without a license until the license manager fixes the situation. You should make sure they get a good impression so they will be more likely to demand or buy a license. It is a good idea to always let users view and navigate through the data in your add-in. Be clear about how having a license will enable more features, but don't remind them more than once per session.

如果应用程序的核心价值是显示数据(您不希望免费提供),则应该显示受限制的数据子集,或者显示无任何交互的数据。您不应该阻止未授权的用户查看您的外接程序。未授权的用户应该尝试外接程序可以为其做哪些事情,以便他们购买外接程序的可能性较大。If your app's core value is in displaying data (and you don't want to give that away for free), you should show a limited subset of the data, or show the data without any interactivity. You should not block unlicensed users from viewing your add-in. Unlicensed users should get a taste of what your add-in can do for them so that they are more likely to buy it.

鼓励用户获取许可证Encouraging users to get a license

在未许可用户或试用许可用户正在使用外接程序的情况下,您应该鼓励他们获取完整许可证。可采用以下两种方法鼓励用户获取完整许可证:In the case where an unlicensed or trial license user is using your add-in, you should encourage them to get a full license. There are two ways to encourage users to get a full license:

  • 用页面顶部的状态栏指明其许可证状态。With a status bar at the top of the page that indicates their license state.
  • 在用户尝试访问需要许可证的内容或功能的上下文中。In context when the user tries to access content or functionality that requires a license.

您应该格外小心,不要在第二种情况下过多使用许可证警告。与因无法执行操作而令用户感到不愉快的意外相比,使用顶级状态消息并禁用任何未许可的功能可为用户带来更好的体验。无论是哪种情况,您的消息应该是友好且鼓舞人心的,而非严肃的。您应该为用户提供一个指向外接程序的店面外接程序详细信息页面的链接,在此页面中,他们可以获取许可证。You should be very careful about overusing the second case of license warnings. It is a better experience for the user when you use the top-level status message and disable any unlicensed functionality than to let the user be unpleasantly surprised by an inability to do something. In either case, your message should be friendly and encouraging rather than stern. You should give the user a link to the storefront add-in details page for your add-in, where they can get a license.

许可证状态栏Licensing status bar

SharePoint 有内置状态栏,可以在 SharePoint 页面上使用,只需调用 JavaScript API 即可。SharePoint has a built-in status bar that you can use on SharePoint pages by calling the JavaScript API. 也可以复制内置状态栏的样式。You can also copy the styling of the built-in status bar. 应使用黄色的“警告”颜色,并显示与用户当前所处情况相称的消息。例如:You should use the yellow "warning" color, with a message appropriate to the situation the user is in, for example:

  • 对于不限时试用版的用户:For users of an unlimited trial:

    “这是 <应用名称> 的试用版。"This is a trial version of <app name>. 请转到此处购买完整版本,并解锁 <付费功能>。”Go here to purchase the full version and unlock <paid functionality>."

  • 对于限时但未到期的试用版的用户:For users of an unexpired time-limited trial:

    “此试用版 <应用名称> 还有 <用可读指标表示的一段时间,如“3 天”,而不是“73:42:12”> 到期。"There [is|are] <amount of time, expressed in a human-readable metric like "3 days" not "73:42:12"> left in this trial of <app name>. 请转到此处购买完整版本,以确保不错过完整功能的任何精彩瞬间。”Go here to purchase the full version and ensure you don't miss a moment of full functionality."

  • 对于限时且已到期的试用版的用户:For users of an expired time-limited trial:

    “很遗憾,此试用版 <应用名称> 已到期。"Unfortunately, there is no more time left in this trial of <app name>. 请转到此处购买完整版本,才能重新使用完整功能。Go here to purchase the full version and return to full functionality."

  • 对于无任何许可证的用户:For users without any license:

    “很遗憾,尚无 <应用名称> 的许可证。请转到此处购买完整版本,并启用 <付费功能>。”"Unfortunately, you don't have a license for <app name>. Go here to purchase the full version and enable <paid functionality>."

SharePoint 加载项的其他设计注意事项Other design considerations for SharePoint Add-ins

除了已经探讨的内容以外,在创建 SharePoint 外接程序时,还应该记住以下事项。In addition to what has already been explored, you should keep these things in mind when you are creating your SharePoint Add-in.

在 Cookie 中保留必要信息Persisting necessary information in cookies

为了与 SharePoint 交互,您的外接程序将需要许多信息,比如主机网站的 URL 或具有 SharePoint 凭据的"公告"消息。在客户端 Cookie 中保留信息意味着外接程序不必总是从 SharePoint 中请求信息,从而可以为最终用户带来更加流畅、更具有出色表现的体验。There will be a lot of information that your add-in will need to be able to interact with SharePoint, such as the URL of the host site or the POST message with SharePoint credentials. Persisting information in a client cookie means that your add-in doesn't have to keep requesting the information from SharePoint, which leads to a smoother, better-performing experience for the end user.

请求新的 OAuth 令牌Requesting a new OAuth token

如果您的外接程序没有凭据,则可以通过将用户重定向到重定向页面(具有外接程序 ID 以及用户尝试转到的 URL)来请求一个新凭据。URL 必须在为正在使用的 OAuth 外接程序 ID 注册的重定向 URL 域的下面。以下 URL 是如何重定向您的外接程序用户的示例。(占位符放在大括号内。)If your add-in doesn't have credentials, you can request a new one by redirecting the user to the redirect page with your add-in ID and the URL that the user is trying to go to. The URL must be under the domain of the redirect URL that is registered for the OAuth add-in ID that you are using. The following URL is an example of how to redirect your add-in users. (Placeholders are in braces.)

{hostWebURL}/_layouts/15/appredirect.aspx?client_id={OAuth_app_ID}&amp;redirect_uri={redirectUrl}

检查 SharePoint 网站上的只读模式Checking for read-only mode on SharePoint sites

由于升级或站点维护的缘故,有时在用户访问外接程序时,SharePoint 处于只读模式。如果您打算允许用户处理 SharePoint 数据,则应该确保不要让用户进行无法保存回服务器的更改。请禁止在处于只读模式时编辑 UI。要检查网站是否处于只读模式,您可以调用此 API:Due to upgrades or site maintenance, there might be times when SharePoint is in read-only mode at the moment the user accesses your add-in. If you're going to allow the user to manipulate SharePoint data, you should make sure you don't let the user make changes that can't be saved back to the server. Disable the editing UI when in read-only mode. To check if the site is in read-only mode, you can call this API:

{hostWebUrl}/_api/site/ReadOnly

另请参阅See also