Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Die Beispiele in diesem Artikel zeigen, wie Sie die Power Pages Client-APIs kombinieren, um allgemeine Szenarien in Formularen und Listen zu implementieren. Jedes Beispiel ist vollständig, sodass Sie sie in eine JavaScript-Webdatei oder in den Abschnitt "Custom JavaScript " einer Seite kopieren und dann die Formularnamen, Spaltennamen und Tabellennamen so ändern können, dass sie Ihrer Website entsprechen.
Alle Beispiele verwenden das in der Client-API-Initialisierung beschriebene Rückrufmuster, das garantiert, dass die Client-API bereit ist, bevor der Code ausgeführt wird. Der Callback wird mit async deklariert, sodass er await verwenden kann. Lassen Sie das Schlüsselwort async weg, wenn Ihr eigener Code await nicht verwendet.
| Beispiel | Description |
|---|---|
| Festlegen eines modalen Nachschlagewerts aus einem Dataverse-Datensatz | Rufen Sie einen Dataverse-Datensatz ab, und verwenden Sie ihn zum Füllen eines modalen Lookup-Steuerelements. |
| Festlegen eines Nachschlagewerts, wenn das Nachschlagen als Dropdownliste gerendert wird | Legen Sie einen Nachschlagewert fest, der darauf basiert, ob das Steuerelement als Dropdownliste oder als modale Suche gerendert wird. |
| Lesen und Festlegen von Werten in einer Mehrfachauswahlspalte | Lesen Sie die ausgewählten Optionen, und fügen Sie eine Option hinzu, ohne vorhandene Auswahlen zu entfernen. |
| Arbeiten mit Steuerelementen, die auf dem Server schreibgeschützt oder ausgeblendet sind | Überprüfen Sie die Verfügbarkeit und den schreibgeschützten Zustand des Steuerelements, bevor Sie das Verhalten des Steuerelements ändern. |
| Festlegen einer spalte, die auf dem Wert einer anderen Spalte basiert | Wenden Sie bedingte Anforderungen und eine benutzerdefinierte Überprüfung basierend auf dem Wert eines anderen Steuerelements an. |
| Ein- oder Ausblenden von Spalten in einer Liste | Blenden Sie eine Spalte in einer modernen Liste aus, und passen Sie die Überschrift und den Tooltip einer anderen Spalte an. |
| Ein- oder Ausblenden von Datensätzen in einer Liste | Blenden Sie inaktive Zeilen aus, und unterscheiden Sie Datensätze, die der aktuelle Benutzer nicht bearbeiten kann. |
Festlegen eines modalen Nachschlagewerts aus einem Dataverse-Datensatz
In diesem Beispiel wird ein Kontodatensatz mit der Web-API abgerufen und zum Auffüllen eines modalen Nachschlagevorgangs in einem Formular verwendet. Eine modale Suche erfordert ein Objekt, das die ID, den Namen und den Tabellennamen des zugehörigen Datensatzes enthält.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
// 1. Retrieve the first account record.
// $top=1 returns a single record, and $select limits the payload to the
// columns that the lookup control needs.
const queryOptions = '$select=accountid,name&$top=1';
const response = await $pages.webAPI.retrieveMultipleRecords('accounts', queryOptions);
const records = response.value;
if (!records || records.length === 0) {
console.warn('No account records were returned from Dataverse.');
return;
}
const firstAccount = records[0];
console.log(`Retrieved account: ${firstAccount.name}`);
// 2. Get the form. Use the name or the ID of your basic or multistep form.
const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');
if (!form) {
console.error('The target form was not found on the page.');
return;
}
// 3. Get the lookup control by its logical name.
const lookupControl = form.getControlByLogicalName('new_managingpartnerid');
if (!lookupControl) {
console.error('The lookup control was not found on the form.');
return;
}
// 4. Set the lookup value. A modal lookup expects an object that contains
// the id, name, and entityType values.
lookupControl.setValue({
id: firstAccount.accountid,
name: firstAccount.name,
entityType: 'account'
});
console.log('The lookup control is populated.');
});
Tip
Um ein Steuerelement zu finden, wenn Sie den logischen Namen nicht kennen, enumerieren form.controls und verwenden Sie die getName Methode wie in form.controls.find(control => control.getName() === 'Managing Partner').
Festlegen eines Nachschlagewerts, wenn das Nachschlagen als Dropdownliste gerendert wird
Eine Nachschlagespalte wird entweder als modales Dialogfeld oder als Dropdownliste gerendert, je nachdem, wie das Formular konfiguriert ist. Die beiden Steuerelemente akzeptieren unterschiedliche Werte in der setValue Methode. Überprüfen Sie daher die isDropdown Eigenschaft, bevor Sie den Wert festlegen. Ein Dropdown-Nachschlagevorgang erwartet, dass die ID der Option ausgewählt wird, und ein modales Nachschlagen erwartet ein Objekt.
Wichtig
Ein Dropdown-Nachschlagefeld enthält nur die Datensätze, die von der konfigurierten Ansicht und den Filtern zurückgegeben werden. Legen Sie den Wert auf die ID eines Datensatzes fest, der in der Dropdownliste verfügbar ist. Filtern Sie in diesem Beispiel Ihre Abfrage so, dass sie nur Datensätze zurückgibt, die der Nachschlagevorgang anbietet.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');
const lookupControl = form && form.getControlByLogicalName('new_managingpartnerid');
if (!lookupControl) {
console.error('The lookup control was not found on the form.');
return;
}
const response = await $pages.webAPI.retrieveMultipleRecords('accounts', '$select=accountid,name&$top=1');
const records = response.value;
if (!records || records.length === 0) {
return;
}
const account = records[0];
if (lookupControl.isDropdown) {
// A dropdown lookup expects the ID of the option to select.
lookupControl.setValue(account.accountid);
// getValue returns an object that contains the id and name of the selected option.
const selected = lookupControl.getValue();
console.log(`Selected option: ${selected && selected.name}`);
} else {
// A modal lookup expects an object.
lookupControl.setValue({
id: account.accountid,
name: account.name,
entityType: 'account'
});
}
});
Lesen und Festlegen von Werten in einer Mehrfachauswahlspalte
Eine Mehrfachauswahl-Auswahlliste speichert ein Array von Zahlen. In diesem Beispiel wird der aktuellen Auswahl eine Option hinzugefügt, ohne die Bereits ausgewählten Optionen zu entfernen.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');
const control = form && form.getControlByLogicalName('new_areasofinterest');
if (!control || control.getType() !== 'MultiSelectPicklist') {
return;
}
// 1. Read the options that are currently selected.
const selectedValues = control.getValue() || [];
console.log(`Selected options: ${selectedValues.join(', ')}`);
// 2. Add an option only when it isn't selected yet.
// setValue throws an error when a value isn't one of the available options.
const newsletterOption = 740740002;
if (!selectedValues.includes(newsletterOption)) {
control.setValue([...selectedValues, newsletterOption]);
}
// 3. Clear the selection.
// control.setValue([]);
});
Arbeiten mit Steuerelementen, die auf dem Server schreibgeschützt oder ausgeblendet sind
Power Pages wendet Formularmetadaten und Tabellenberechtigungen auf dem Server an, und die Client-API kann diese Einstellungen nicht außer Kraft setzen. Schreiben Sie Defensivcode, der überprüft, ob ein Steuerelement vorhanden ist und ob es schreibgeschützt ist, bevor Sie es ändern.
Es gelten folgende Verhaltensweisen:
- Eine Spalte, die nicht im Formular enthalten ist oder für die jemand keine Leseberechtigung hat, wird nicht angezeigt. Die
getControlByLogicalNameMethode gibt für diese Spalte zurückundefined. Überprüfen Sie daher das Ergebnis, bevor Sie sie verwenden. - Wenn ein Steuerelement auf dem Server gesperrt ist, z. B. eine Mehrfachauswahlliste in einem schreibgeschützten Formular oder Feld, hat die
setDisabled(false)Methode keine Auswirkung. - Die
setRequired(false)Methode kann eine Spalte nicht optional machen, wenn die Spalte auf dem Server erforderlich ist. - Die
setVisible(false)Methode blendet ein Steuerelement nur im Browser aus. Verwenden Sie Tabellenberechtigungen und Spaltensicherheit, um Daten zu schützen. Verlassen Sie sich niemals darauf, ein Steuerelement zum Sichern von Daten auszublenden.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');
if (!form) {
return;
}
const creditLimit = form.getControlByLogicalName('creditlimit');
// The column isn't on the form, or the user can't read it.
if (!creditLimit) {
console.log('The credit limit column is not available to this user.');
return;
}
// A control that's locked on the server stays disabled, even after
// you call setDisabled(false).
creditLimit.setDisabled(false);
if (creditLimit.getDisabled()) {
console.log('The credit limit column is locked on the server.');
}
// Hide the control in the browser. This changes only what people see.
// Use table permissions and column security to protect the data.
const internalNotes = form.getControlByLogicalName('new_internalnotes');
if (internalNotes) {
internalNotes.setVisible(false);
}
});
Festlegen einer spalte, die auf dem Wert einer anderen Spalte basiert
In diesem Beispiel wird eine Spalte nur benötigt, wenn jemand eine bestimmte Option in einer anderen Spalte auswählt, und es wird ein benutzerdefinierter Validator hinzugefügt, der beim Senden des Formulars ausgeführt wird. Weitere Informationen finden Sie unter addValidator-Methodenparameter.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');
if (!form) {
return;
}
const contactMethod = form.getControlByLogicalName('preferredcontactmethodcode');
const mobilePhone = form.getControlByLogicalName('mobilephone');
if (!contactMethod || !mobilePhone) {
return;
}
const applyRules = () => {
// Option 3 is Phone in this example.
const requiresPhone = contactMethod.getValue() === '3';
// Make the column required and provide a localized message.
mobilePhone.setRequired(requiresPhone, 'Enter a mobile phone number.');
if (requiresPhone) {
// Add a format check that runs when the form is submitted.
// Reusing the same ID replaces the earlier validator instead of adding another one.
mobilePhone.addValidator(
'mobilePhoneFormat',
(value) => /^(?=.*\d)[0-9\s+()-]{7,20}$/.test((value || '').trim()),
'Enter a valid mobile phone number.'
);
} else {
mobilePhone.removeValidator('mobilePhoneFormat');
}
};
// Apply the rules when the page loads and whenever a value on the form changes.
applyRules();
form.getHtmlElement().addEventListener('change', applyRules);
});
Note
Eine Spalte, die auf dem Server erforderlich ist, bleibt auch beim Aufrufen setRequired(false)erforderlich.
Ein- oder Ausblenden von Spalten in einer Liste
In diesem Beispiel wird eine Spalte in einer modernen Liste ausgeblendet und eine weitere Spalte umbenannt. Lesen Sie die Daten der Liste in einem loaded-Ereignishandler, da das Ereignis jedes Mal erneut auftritt, wenn die Liste aktualisiert, sortiert, gefiltert oder paginiert wird. Weitere Informationen finden Sie unter Listenereignisse.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
const list = $pages.currentPage.lists.getListById('list_#1');
if (!list || !list.isModern) {
return;
}
list.on('loaded', () => {
// Hide a column that people don't need to see.
const createdOn = list.getColumn('createdon');
if (createdOn) {
createdOn.setVisible(false);
}
// Rename a column and add a tooltip that screen readers use as the
// accessible name of the header. Read the configured display name, and
// then derive the header so that the code produces the same result
// each time the event occurs.
const name = list.getColumn('name');
if (name) {
name.setHeader(`${name.getDisplayName()} (primary)`);
name.setTooltip('The primary name of the account.');
}
});
});
Ein- oder Ausblenden von Datensätzen in einer Liste
In diesem Beispiel werden inaktive Datensätze ausgeblendet und die Datensätze hervorgehoben, die jemand nicht bearbeiten kann. Durch das Ausblenden einer Zeile wird nur geändert, was personen in der Liste sehen; die Daten oder die Anzahl der vom Server zurückgegebenen Datensätze werden nicht geändert.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
const list = $pages.currentPage.lists.getListById('list_#1');
if (!list || !list.isModern) {
return;
}
list.on('loaded', () => {
list.rows.forEach((row) => {
const state = row.getState();
// Hide inactive records, where statecode is 1.
if (state && state.stateCode === 1) {
row.setVisible(false);
return;
}
// Highlight the records that this user can't edit.
const privileges = row.getPrivileges();
if (privileges && !privileges.canWrite) {
row.addClassName('read-only-row');
const nameCell = row.getCell('name');
if (nameCell) {
nameCell.setStyle({ fontStyle: 'italic' });
}
}
});
});
});
Wichtig
Verwenden Sie die Werte, die die getPrivileges Methode zurückgibt, um zu ändern, wie Daten angezeigt werden. Verwenden Sie sie nicht, um Sicherheit zu erzwingen. Power Pages erzwingt Tabellenberechtigungen auf dem Server.