Power Pages ví dụ về API máy khách (bản xem trước)

[Bài viết này là tài liệu trước khi phát hành và có thể thay đổi.]

Các ví dụ trong bài viết này cho thấy cách kết hợp các API Power Pages khách để thực hiện các kịch bản phổ biến trên biểu mẫu và danh sách. Mỗi ví dụ đều hoàn tất, vì vậy bạn có thể sao chép nó vào một tệp web JavaScript hoặc vào phần JavaScript Tùy chỉnh của một trang, rồi thay đổi tên biểu mẫu, tên cột và tên bảng để khớp với site của bạn.

Quan trọng

  • Đây là một tính năng xem trước.
  • Các tính năng xem trước không được dùng cho sản xuất và có thể có chức năng bị hạn chế. Các tính năng này tuân theo các điều khoản sử dụng bổ sung và có sẵn trước khi phát hành chính thức để khách hàng có thể truy cập sớm và cung cấp phản hồi.

Tất cả các ví dụ đều sử dụng mẫu gọi lại được mô tả trong khởi tạo API Máy khách, đảm bảo rằng API máy khách đã sẵn sàng trước khi mã của bạn chạy. Gọi lại được khai báo bằng để async có thể sử dụng await. Bỏ qua từ khóa async khi mã của riêng bạn không sử dụng await.

Ví dụ Mô tả
Đặt giá trị tra cứu mô thức từ bản ghi Dataverse Truy xuất bản ghi Dataverse và dùng nó để nhập điều khiển tra cứu mô thức.
Đặt giá trị tra cứu khi tra cứu kết xuất dưới dạng danh sách thả xuống Đặt giá trị tra cứu dựa trên việc điều khiển kết xuất dưới dạng danh sách thả xuống hay tra cứu theo phương thức.
Đọc và đặt giá trị trong cột lựa chọn đa lựa chọn Đọc các lựa chọn đã chọn và thêm một tùy chọn mà không loại bỏ các lựa chọn hiện có.
Làm việc với các điều khiển chỉ đọc hoặc ẩn trên máy chủ Kiểm tra tính khả dụng của điều khiển và trạng thái chỉ đọc trước khi thay đổi hành vi điều khiển.
Tạo cột bắt buộc dựa trên giá trị của cột khác Áp dụng các yêu cầu có điều kiện và xác thực tùy chỉnh dựa trên giá trị của một điều khiển khác.
Hiện hoặc ẩn cột trong danh sách Ẩn cột danh sách hiện đại và tùy chỉnh đầu đề và chú giải công cụ của một cột khác.
Hiện hoặc ẩn bản ghi trong danh sách Ẩn các hàng không hoạt động và phân biệt trực quan các bản ghi mà người dùng hiện tại không thể sửa.

Đặt giá trị tra cứu mô thức từ bản ghi Dataverse

Ví dụ này truy xuất một bản ghi tài khoản với WEB API và sử dụng nó để điền vào một tra cứu mô thức trên một biểu mẫu. Tra cứu mô thức yêu cầu một đối tượng có chứa ID, tên và tên bảng của bản ghi liên quan.

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.');
});

Mẹo

Để tìm điều khiển khi bạn không biết tên lô-gic của nó, form.controls hãy liệt kê và sử dụng phương getName pháp, như trong form.controls.find(control => control.getName() === 'Managing Partner').

Đặt giá trị tra cứu khi tra cứu kết xuất dưới dạng danh sách thả xuống

Cột tra cứu kết xuất dưới dạng hộp thoại mô thức hoặc danh sách thả xuống, tùy thuộc vào cách cấu hình biểu mẫu. Hai điều khiển chấp nhận các giá trị khác nhau trong setValue phương pháp, vì vậy hãy kiểm tra isDropdown thuộc tính trước khi bạn đặt giá trị. Tra cứu thả xuống dự kiến ID của tùy chọn sẽ chọn và tra cứu theo cách thức dự kiến sẽ có một đối tượng.

Quan trọng

Tra cứu thả xuống chỉ chứa các bản ghi mà dạng xem và bộ lọc đã lập cấu hình của nó trở lại. Đặt giá trị thành ID của bản ghi sẵn dùng trong danh sách thả xuống. Trong ví dụ này, lọc truy vấn của bạn để truy vấn chỉ trả về các bản ghi mà tra cứu cung cấp.

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'
        });
    }
});

Đọc và đặt giá trị trong cột lựa chọn đa lựa chọn

Điều khiển danh sách chọn nhiều lựa chọn lưu trữ một mảng số. Ví dụ này thêm một tùy chọn vào vùng chọn hiện tại mà không loại bỏ tùy chọn mà ai đó đã chọn.

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([]);
});

Làm việc với các điều khiển chỉ đọc hoặc ẩn trên máy chủ

Power Pages dụng quyền bảng và siêu dữ liệu biểu mẫu trên máy chủ và API máy khách không thể ghi đè các cài đặt đó. Viết mã phòng thủ để kiểm tra xem điều khiển có tồn tại hay không và liệu điều khiển có ở dạng chỉ đọc trước khi bạn thay đổi điều khiển hay không.

Các hành vi sau đây áp dụng:

  • Cột không có trên biểu mẫu hoặc ai đó không có quyền đọc, sẽ không được kết xuất. Phương getControlByLogicalName pháp trả về undefined cho cột đó, vì vậy hãy kiểm tra kết quả trước khi sử dụng.
  • Khi một điều khiển bị khóa trên máy chủ, chẳng hạn như danh sách chọn nhiều lựa chọn trên một biểu mẫu hoặc trường chỉ đọc, setDisabled(false) phương pháp không có tác dụng.
  • Phương setRequired(false) pháp này không thể tạo cột tùy chọn khi cột được yêu cầu trên máy chủ.
  • Phương setVisible(false) pháp này chỉ ẩn điều khiển trong trình duyệt. Sử dụng các quyền của bảng và bảo mật cột để bảo vệ dữ liệu. Không bao giờ dựa vào việc ẩn điều khiển để bảo mật dữ liệu.
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);
    }
});

Tạo cột bắt buộc dựa trên giá trị của cột khác

Ví dụ này tạo cột bắt buộc chỉ khi ai đó chọn một tùy chọn cụ thể trong cột khác và thêm bộ xác thực tùy chỉnh chạy khi biểu mẫu được gửi đi. Để biết thêm thông tin, hãy xem tham số phương pháp addValidator.

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);
});

Lưu ý

Cột bắt buộc trên máy chủ vẫn được yêu cầu, ngay cả khi bạn gọi setRequired(false).

Hiện hoặc ẩn cột trong danh sách

Ví dụ này ẩn một cột trong danh sách hiện đại và đổi tên một cột khác. Đọc dữ liệu danh sách trong loaded bộ xử lý sự kiện, vì sự kiện lại xảy ra mỗi khi danh sách làm mới, sắp xếp, bộ lọc hoặc dữ liệu trang. Để biết thêm thông tin, hãy xem Liệt kê sự kiện.

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.');
        }
    });
});

Hiện hoặc ẩn bản ghi trong danh sách

Ví dụ này ẩn các bản ghi không hoạt động và tô sáng các bản ghi mà người khác không thể sửa. Việc ẩn một hàng chỉ thay đổi những gì mọi người nhìn thấy trong danh sách; nó không thay đổi dữ liệu hoặc số lượng bản ghi mà máy chủ trả về.

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' });
                }
            }
        });
    });
});

Quan trọng

Dùng các giá trị mà phương pháp getPrivileges trả về để thay đổi cách dữ liệu xuất hiện. Không sử dụng chúng để thực thi bảo mật. Power Pages thực thi quyền bảng trên máy chủ.

  • Last updated on