2016年9月13日,星期二

SharePoint框架中的Web双色球推荐一注属性– part 1

现代SharePoint页面具有新的Web双色球推荐一注编辑体验。这由现代Web双色球推荐一注和新的SharePoint Framework(SPFx)提供支持,希望使用这些新页面的开发人员需要了解新模型。当您开始构建现代Web双色球推荐一注时,’会发现需要实现Web双色球推荐一注属性–这样您的最终用户可以提供所需的任何选项或设置。微软提供了一套常见的“property pane”控件,例如文本框,下拉菜单,滑块等– and it’也可以添加完全自定义的控件(我’将在以后的文章中介绍)。在大多数情况下,核心控件是您的起点,因此在本文中,我’我将开始研究使用这些控件所需的TypeScript / JSON。

第一件事– 反应性 vs. non-reactive 属性窗格s

实施Web双色球推荐一注属性时,首先要了解的是默认情况下,当页面编辑器更改属性时,新页面框架支持Web呈现的“立即”更改。这被称为“reactive” 属性窗格 - no more having to click “Save”, “OK”, “OK”只是看到一个变化。让’s以Web双色球推荐一注属性为例,该属性指定了小双色球推荐一注的描述-如果用户在文本框中进行编辑,并且该内容显示在Web双色球推荐一注的主要区域中,则它将随着用户的输入而动态更新。尽管可以要求开发人员在更复杂的情况下实施某些操作,但这是自动发生的。

Sometimes you want to disable 这个 though – perhaps it’不适合使UI不断更新,或者每次都需要对SharePoint进行查找’s a change. You can disable the 反应性 behavior by adding 这个 code to your web part class:

protected get disableReactivePropertyChanges():boolean {
    return true;
  }

 

将Web双色球推荐一注属性构造为页面和组

Perhaps the second thing to mention is that the new web part 属性窗格 can be structured into multiple pages, each with groups of properties. And the best news is that we don’在没有人使用过的每个Web双色球推荐一注上都包含旧的Web双色球推荐一注属性的包((“Allow Minimize”, “Allow Close” etc.). So in the new world, a simple web part 属性窗格 with a couple of pages and groups might look something like the images below –注意页面标题,组标题和分页控件:

SNAGHTML61509e7e

This allows us to better structure our properties, and so in my example the page 2 of the web part props might look like 这个:

SNAGHTML6152c7e6

You can continue to define additional pages and the framework will take care of providing paging in the UI for you. In terms of the code to do 这个 (and define SPFx web part properties in general), all the action happens in the getPropertyPaneConfiguration() 方法。这里’上面的代码(顺便说一句,’m using Gist for longer code samples like 这个 one but have others “inline”在帖子中,很抱歉,它们看上去有些不同!)–无论如何,我们现在基本上在结构中定义了两个页面:

使用不同的控件

现在,我们了解了如何将控件分为页面和组,让’继续控制本身。编辑Web双色球推荐一注代码的第一步是为TypeScript模块添加导入语句–我们针对希望使用的每个控件执行此操作。因此,在您的Web双色球推荐一注类的顶部,从类似以下的步骤开始:

导入{
 BaseClientSideWebPart,
 IPropertyPaneConfiguration,
  IWebPartContext,
 PropertyPaneTextField
}来自 '@ microsoft / sp-webpart-base'

..至..

导入{
 BaseClientSideWebPart,
 IPropertyPaneConfiguration,
  IWebPartContext,
 PropertyPaneTextField,
 PropertyPaneCheckbox,
 PropertyPaneChoiceGroup,
 PropertyPaneDropdown,
  属性PaneSlider,
  属性PaneButton,
  属性PaneToggle
}来自 '@ microsoft / sp-webpart-base'

从那里,我们可以开始在 getPropertyPaneConfiguration() 方法。在前面的代码示例中,我们看到了如何将属性划分为页面和组,但在此处将其放大一秒钟。’s a specific change to move from the default arrangement to something with a second group. So we would move from the default of 这个:

组:[
            {
              groupName: 串s.BasicGroupName,
              groupFields:[
               PropertyPaneTextField('description',{
                  标签: 串s.DescriptionFieldLabel
                })
              ]
            }
         ]

..至..

组:[
            {
              groupName: 串s.BasicGroupName,
              groupFields:[
               PropertyPaneTextField('description',{
                  标签: 串s.DescriptionFieldLabel
                })
              ]
            },
            {
              groupName: "COB settings",
              groupFields:[
               PropertyPaneTextField('query',{
                  标签: “Query” 
                })
              ]
            }
         ]

与任何JSON一样,您必须注意使用方括号和大括号!请注意,为简单起见,您可以看到我’我不在这里将我的字符串(例如groupName和控件标签文本)放入单独的字符串类中–但在现实生活中,我建议您这样做,以避免在您的代码中乱成一团的魔术字符串。

因此,将属性分为页面和组非常简单。现在让’开始查看各个控件– I’我会在这里看到一些,在以后的文章中也会看到。

文字方块(PropertyPaneTextField)
特性:

属性

描述

标签 标签显示在控件旁边。
描述 说明显示在控件旁边。
领域价值–可用于设置默认文本。
ariaLabel 不可见的标签–根据ARIA标准,由针对可访问性的工具和浏览器使用。
多行 指定文本框是否为多行(布尔)。
占位符 允许您提供默认的占位符文本,当控件没有值时显示。
可调整大小 指定用户是否可以扩大控件(以使其更容易输入大量数据)。
下划线的 文本字段是否带下划线。
错误信息 错误消息的静态值– it’我不清楚你什么时候’d use 这个, because the error is always displayed. The onGetErrorMessage property is what you’d似乎真的使用它。
onGetErrorMessage 用于验证的函数指针– returns either a 串 (containing the error message) for simple cases OR a Promise<string>对于更复杂的情况,您需要对SharePoint(或类似文件)进行异步调用以进行验证。

请参阅下面的更多细节。
deferredValidationTime 显示验证错误消息之前要等待的时间(毫秒)–例如允许用户完成输入值。
编码:

注意我’m在下面的代码中还显示了一个简单的文本框验证例程–注意onGetErrorMessage用法:

属性PaneTextField('textboxProperty',{
                 标签:“这是标签”,
                  多行: true,
                  可调整大小: true,
                  onGetErrorMessage: 这个.simpleTextBoxValidationMethod,
                  错误信息: "这是错误消息",
                 deferredValidationTime:5000,
                  占位符: "这是占位符文本(在未输入任何值时显示)",
                  "description": "This is the 描述"
                })

private simpleTextBoxValidationMethod(value: 串): 串 {
    if (value.length < 5) {
        return "值必须超过5个字符!";
    } else {
      return "";
    }
  }

看起来像什么:

SNAGHTML4d5ddb9f

..并在验证函数执行后显示一个更真实的示例:

SNAGHTML4df82741

文本框控件的更高级验证

So in the example above, I showed a simple function to check the 值 the user entered was more than 5 characters. But what if you want to talk to SharePoint, or make some other async call to validate 文本 box contents? In 这个 case our function referenced in onGetErrorMessage 必须返回一个承诺<string> rather than a 串 –由于需要正确的上下文,因此事情变得更加复杂‘this’在你的职能。这里’s异步文本框验证方法的示例– I’m检查输入的值是否与当前站点中的列表匹配:

但是那里’还有更多。最初我收到错误消息,指出‘this’在我的函数中未定义– manifesting in a ”未捕获的TypeError:无法读取未定义的属性“上下文”” error as I was trying to access 这个.context in my web part code. So why was ‘this’没有人吗?答案是,事实并非如此’t,此处带有默认功能指针。 To get around 这个, we need to use the JavaScript/TypeScript ‘bind’ method. 这允许重新调用我们可以通过的函数‘this’ as a parameter – the receiving function then has the context. So where we reference our function in the onGetErrorMessage property of the 文本box, instead of 这个:

onGetErrorMessage: 这个.asyncTextBoxValidationMethod,

..you need 这个:

onGetErrorMessage: 这个.asyncTextBoxValidationMethod.bind(this),

给我的同事和朋友的大道具 瓦尔达曼 for 这个 – he has a great article on 这个 specific subject (在官方文档中提及之前),’s there that I discovered 这个 solution. Thanks Vard!

复选框(PropertyPaneCheckbox)
特性:

属性

描述

文本 复选框旁边显示的文本。
已检查 指定是否检查控件。
残障人士 指定是否禁用控件。
码:
属性PaneCheckbox('checkboxProperty',{
                 文字:“这是文字”, 
                  已检查: true,
                  残障人士: false 
                })
看起来像什么:

SNAGHTML4e0dbd03

 

下拉菜单(PropertyPaneDropdown)
特性:

属性

描述

标签 标签显示在控件旁边。
选项s IPropertyPaneDropdownOption对象的数组(类似于HTML<option> tag – defines the key/text etc. of the 选项). Can be specified in a static way, or fetched dynamically – see my other post (coming soon!) for details on 这个.
selectedKey 所选项目的键名。可用于设置最初选择的项目。
残障人士 Specifies if the control is *disabled* (not sure why 这个 is flipped the other way compared to other controls! Hopefully 这个 will be made consistent in future releases..)
码:
属性PaneDropdown('dropdownProperty',{
                 标签:“这是标签”, 
                  残障人士: false,
                  选项s: [
                   {键:“红色”,文字:“红色”},
                   {键:“绿色”,文字:“绿色”},
                   {键:“ DarkBlue”,文字:“ Dark blue”}
                  ]
                })
看起来像什么:

SNAGHTML5c0d42aa

概要

在SharePoint Framework中构建Web双色球推荐一注带来了一些新功能,包括Web双色球推荐一注属性的新模型。与其他技术(例如,使用脚本编辑器Web双色球推荐一注和单独的JavaScript文件)相比,这是该框架的亮点。–该方法根本没有提供使用自定义属性的方法。在本文中,我们研究了前几个控件,并指出动态填充下拉列表需要一种特定的方法,我将在另一篇文章中详细介绍。

在以后的文章中,我’我们将看看其他现成的Web双色球推荐一注属性控件。

2条评论:

埃里奥·斯特鲁夫(Elio Struyf)说过...

一如既往的伟大文章。您可以为组设置的另一个有用的属性是 displayGroupsAsAccordion。顾名思义,它将显示手风琴中的每个组。

页数:[{
标头:{
描述: 串s.PropertyPaneDescription
},
组:[{
组名:串s.BasicGroupName,
groupFields:[
属性PaneTextField('title', {
标签:串s.FieldsTitleLabel
})
]
},{
组名:串s.TemplateGroupName,
groupFields:[
属性PaneToggle('external', {
标签:串s.FieldsExternalLabel
})
]
}],
displayGroupsAsAccordion:true
}]

问候,
埃里奥

克里斯·奥'Brien说过...

@Elio,

哦,贴士!谢了哥们..

COB。