现代SharePoint页面具有新的Web部件编辑体验。这由现代Web部件和新的SharePoint Framework（SPFx）提供支持，希望使用这些新页面的开发人员需要了解新模型。当您开始构建现代Web部件时，’会发现需要实现Web部件属性–这样您的最终用户可以提供所需的任何选项或设置。微软提供了一套常见的“property pane”控件，例如文本框，下拉菜单，滑块等– 和 it’也可以添加完全自定义的控件（我’将在以后的文章中介绍）。在大多数情况下，核心控件是您的起点，因此在本文中，我’我将开始研究使用这些控件所需的TypeScript / JSON。
- In 这个 article:
- Reactive vs. non-reactive 属性窗格s
- 将Web部件属性构造为页面和组
- 文字框，下拉框和复选框控件
- 其他文章：
第一件事– 反应性 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. 您 can disable the 反应性 behavior by adding 这个 code to your web part class:
protected get disableReactivePropertyChanges（）：boolean {
return 真正;
}
将Web部件属性构造为页面和组
Perhaps the second thing to mention 是 that the new web part 属性窗格 can be structured into multiple pages, each with groups of 属性. And the best 新闻 是 that we don’在没有人使用过的每个Web部件上都包含旧的Web部件属性的包（（“Allow Minimize”, “Allow Close” etc.). So 在里面new world, a simple web part 属性窗格 with a couple of pages 和 groups might look something like the 图片s below –注意页面标题，组标题和分页控件：
This allows us to better structure our 属性, 和 so in my example the page 2 of the web part props might look like 这个:
您 can continue to define additional pages 和 the framework will take care of providing paging 在里面UI for you. In terms of the code to do 这个 (and define SPFx web part 属性 in general), all the action happens 在里面getPropertyPaneConfiguration（） 方法。这里’上面的代码（顺便说一句，’m using Gist for longer code samples like 这个 one but have 其他 “inline”在帖子中，很抱歉，它们看上去有些不同！）– 任何way, we basically have two pages being defined in our structure 现在:
使用不同的控件
现在，我们了解了如何将控件分为页面和组，让’s move on to the controls themselves. 的first step in editing your web part code 是 to add 进口 statements for TypeScript 模组 –我们针对希望使用的每个控件执行此操作。因此，在您的Web部件类的顶部，从类似以下的步骤开始：
..至..
导入{
BaseClientSideWebPart，
IPropertyPaneConfiguration，
IWebPartContext,
PropertyPaneTextField，
PropertyPaneCheckbox，
PropertyPaneChoiceGroup，
PropertyPaneDropdown，
属性PaneSlider,
属性PaneButton,
属性PaneToggle
}来自
'@ microsoft / sp-webpart-base'From there, we can start expanding the code 在里面getPropertyPaneConfiguration（） 方法。在前面的代码示例中，我们看到了如何将属性划分为页面和组，但在此处将其放大一秒钟。’s a specific change to move 从 the default arrangement to something with a second group. So we would move 从 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”
})
]
}
]
As with 任何 JSON, you have to take care with closing brackets 和 braces! Note that for simplicity/illustration, you can see I’我不在这里将我的字符串（例如groupName和控件标签文本）放入单独的字符串类中–但在现实生活中，我建议您这样做，以避免在您的代码中乱成一团的魔术字符串。
因此，将属性分为页面和组非常简单。现在让’开始查看各个控件– I’我会在这里看到一些，在以后的文章中也会看到。
文字方块（PropertyPaneTextField）
特性：
| 属性 | 描述 |
| 标签 | 标签显示在控件旁边。 |
| 描述 | 说明显示在控件旁边。 |
| 值 | Value 在里面field –可用于设置默认文本。 |
| ariaLabel | 不可见的标签–根据ARIA标准，由针对可访问性的工具和浏览器使用。 |
| 多行 | 指定文本框是否为多行（布尔）。 |
| 占位符 | 允许您提供默认的占位符文本，当控件没有值时显示。 |
| 可调整大小 | Specifies whether the control can be enlarged by the user (to make it easier to enter larger amounts of 数据). |
| 下划线的 | 文本字段是否带下划线。 |
| 错误信息 | 错误消息的静态值– it’我不清楚你什么时候’d use 这个, because the error 是 always displayed. 的onGetErrorMessage property 是 what you’d似乎真的使用它。 |
| onGetErrorMessage | 用于验证的函数指针– returns either a 串 (containing the error message) for simple cases OR a Promise<string>对于更复杂的情况，您需要对SharePoint（或类似文件）进行异步调用以进行验证。
请参阅下面的更多细节。 |
| deferredValidationTime | 显示验证错误消息之前要等待的时间（毫秒）–例如允许用户完成输入值。 |
的code:
注意我’m在下面的代码中还显示了一个简单的文本框验证例程–注意onGetErrorMessage用法：
属性PaneTextField（'textboxProperty'，{
标签：“这是标签”，
多行: 真正,
可调整大小: 真正,
onGetErrorMessage: 这个.simpleTextBoxValidationMethod,
错误信息: "这是错误消息",
deferredValidationTime：5000，
占位符: "这是占位符文本（在未输入任何值时显示）",
"description": "This 是 the 描述"
})
private simpleTextBoxValidationMethod(value: 串): 串 {
if (value.length < 5) {
return "值必须超过5个字符！";
} else {
return "";
}
}
看起来像什么：
..并在验证函数执行后显示一个更真实的示例：
文本框控件的更高级验证
So 在里面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’ not populated? 的answer 是 that it just 是n’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 在里面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'，{
文字：“这是文字”，
已检查: 真正,
残障人士: false
})
看起来像什么：
下拉菜单（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 是 *disabled* (not sure why 这个 是 flipped the other way compared to other controls! Hopefully 这个 will be made consistent in future releases..) |
码：
属性PaneDropdown（'dropdownProperty'，{
标签：“这是标签”，
残障人士: false,
选项s: [
{键：“红色”，文字：“红色”}，
{键：“绿色”，文字：“绿色”}，
{键：“ DarkBlue”，文字：“ Dark blue”}
]
})
看起来像什么：
概要
Building web parts 在里面SharePoint框架 brings a few new things, including a new model for web part 属性. This 是 where the framework shines compared to other techniques like using a Script Editor web part 和 a separate JavaScript file –该方法根本没有提供使用自定义属性的方法。在本文中，我们研究了前几个控件，并指出动态填充下拉列表需要一种特定的方法，我将在另一篇文章中详细介绍。
在以后的文章中，我’我们将看看其他现成的Web部件属性控件。
