Cipta dan gunakan aplikasi satu halaman dalam Power Pages

Power Pages menyokong penyepaduan kod aplikasi satu halaman (SPA) yang dicipta dengan alat bantuan AI generasi akan datang, seperti GitHub Copilot. Keupayaan ini membolehkan pembangun membawa pengalaman bahagian hadapan berasaskan komponen moden ke dalam Power Pages dengan menggunakan bahasa semula jadi sebagai antara muka pengekodan.

Dengan membimbing, menguji dan memperhalusi kod yang dijana AI, pembuat boleh mengalihkan tumpuan mereka daripada tugas pelaksanaan berulang kepada orkestrasi peringkat lebih tinggi. Ini memperkasakan pembangunan yang lebih intuitif dan kreatif sambil mengekalkan kualiti dan piawaian gred perusahaan.

Artikel ini menunjukkan kepada anda cara:

• Cipta dan sediakan projek SPA untuk Power Pages dengan menggunakan Power Platform CLI (PAC CLI).
• Muat naik dan muat turun aset kod ke dan dari laman Power Pages anda.
• Sediakan struktur projek yang selamat dan boleh diselenggara.
• Ketahui perbezaan utama antara pelaksanaan Power Pages berasaskan SPA dan tradisional.

Nota

• Tapak SPA ialah tapak Power Pages yang berjalan sepenuhnya dalam penyemak imbas pengguna (pemaparan bahagian pelanggan). Tidak seperti tapak Power Pages tradisional, tapak SPA diuruskan hanya melalui kod sumber dan alat antara muka baris arahan (CLI).
• Penyepaduan Git Power Platform tidak disokong untuk tapak web Aplikasi Single-Page (SPA) dalam Power Pages.

Prasyarat

Sebelum anda memulakan, pastikan anda mempunyai:

• Persekitaran Power Pages dengan keistimewaan admin.
• Power Platform CLI (PAC CLI) versi 1.44.x atau lebih baru dipasang dan disahkan.
• Laman Power Pages pada versi 9.7.4.x atau lebih baru.
• Benarkan muat naik fail JavaScript dalam persekitaran Dataverse.
• Repositori Git tempatan dengan projek bahagian hadapan tersuai anda, seperti React, Angular atau Vue.

Benarkan muat naik fail JavaScript

Secara lalai, sesetengah persekitaran Dataverse menyekat muat naik fail JavaScript (.js). Jika anda menghadapi ralat "Import gagal: Lampiran sama ada bukan jenis yang sah atau terlalu besar. Ia tidak boleh dimuat naik atau dimuat turun.", kemas kini tetapan persekitaran anda untuk membenarkan jenis fail ini.

Untuk melaraskan tetapan dalam pusat pentadbiran Power Platform bagi persekitaran, ikut langkah berikut:

1. Daftar masuk ke pusat pentadbiran Power Platform.
2. Dalam anak tetingkap navigasi, pilih Urus.
3. Dalam anak tetingkap Urus , pilih Persekitaran.
4. Pilih persekitaran.
5. Dalam bar perintah, pilih Tetapan.
6. Kembangkan Produk dan kemudian pilih Privasi + Keselamatan.
7. Dalam bahagian Lampiran Disekat , alih keluar js daripada senarai sambungan fail.
8. Pilih Simpan.

Buat dan gunakan tapak SPA

Power Pages tapak SPA diuruskan menggunakan arahan PAC CLI upload-code-site dan download-code-site. Selepas anda memuat naik tapak, ia muncul dalam Power Pages dalam senarai Tapak tidak aktif. Aktifkan tapak untuk menyediakannya kepada pengguna.

Muat naik tapak SPA

Gunakan arahan pac pages upload-code-site untuk memuat naik sumber tempatan anda dan aset yang disusun ke persekitaran Power Pages anda.

Syntax

pac pages upload-code-site `
  --rootPath <local-source-folder> `
  [--compiledPath <build-output-folder>] `
  [--siteName <site-display-name>]

Parameter

Parameter_	Alias	Diperlukan	Perihalan
--rootPath	-rp	Ya	Folder setempat yang mempunyai fail sumber tapak anda
--compiledPath	-cp	Tidak	Laluan ke aset yang disusun, seperti React build
--siteName	-sn	Tidak	Nama paparan untuk laman Power Pages anda

Contoh

pac pages upload-code-site `
  --rootPath "../your-project" `
  --compiledPath "./build" `
  --siteName "Contoso Code Site"

Jika anda tidak mempunyai projek sedia ada, cuba contoh pelaksanaan tapak SPA menggunakan React, Angular dan Vue.

Mentakrifkan parameter muat naik dengan powerpages.config.json

Sesuaikan tingkah laku arahan upload-code-site dengan memasukkan powerpages.config.json fail dalam tapak anda. Letakkan fail konfigurasi ini dalam folder akar tapak. Apabila anda menggunakan muat naik tapak berasaskan konfigurasi, jalankan arahan upload-code-site dengan parameter sahaja rootPath . Perintah secara automatik membaca nilai lain, seperti laluan aset yang disusun dan nama paparan tapak, daripada powerpages.config.json fail. Jika anda menyediakan kedua-dua hujah baris arahan dan nilai konfigurasi, argumen baris arahan akan diutamakan.

Sampel powerpages.config.json:

{
  "siteName": "Contoso Bank",
  "defaultLandingPage": "index.html",
  "compiledPath": "C:\\PowerPages\\your-project\\dist"
}

Muat turun tapak SPA

Gunakan arahan pac pages download-code-site untuk memuat turun kod tapak sedia ada ke direktori tempatan untuk tujuan penyuntingan atau sandaran.

Syntax

pac pages download-code-site `
  [--environment <env-url-or-guid>] `
  --path <local-target-folder> `
  --webSiteId <site-guid> `
  [--overwrite]

Parameter

Parameter_	Alias	Diperlukan	Perihalan
--environment	-env	Tidak	Dataverse persekitaran (GUID atau URL penuh). Lalai kepada profil pengesahan aktif anda
--path	-p	Ya	Direktori tempatan untuk memuat turun kod tapak
--webSiteId	-id	Ya	GUID rekod laman web laman web Power Pages SPA
--overwrite	-o	Tidak	Ganti fail sedia ada dalam direktori sasaran jika ia wujud

Contoh

pac pages download-code-site `
  --environment "https://contoso.crm.dynamics.com" `
  --path "./downloaded-site" `
  --webSiteId "11112222-bbbb-3333-cccc-4444dddd5555" `
  --overwrite

Aktifkan dan uji laman web anda

1. Pergi ke Power Pages.
2. Pilih Tapak tidak aktif, cari tapak anda dan pilih Aktifkan semula.
3. Apabila tapak aktif, pergi ke URL tapak anda untuk menyemak penggunaan.

Petua

Mana-mana arahan kemudian upload-code-site mengemas kini tapak aktif secara automatik.

Struktur dan konfigurasi projek

Susun atur projek yang konsisten membantu memastikan tingkah laku muat naik yang betul.

/your-project
│
├─ src/                       ← Your source code, like React components
├─ build/                     ← Compiled assets, output of the `npm run build` command
├─ powerpages.config.json     ← Optional CLI configuration file
└─ README.md

Gunakan fail pilihan powerpages.config.json untuk menyesuaikan cara arahan berfungsi upload-code-site .

Pengesahan dan kebenaran

Power Pages tapak SPA menggunakan model security yang sama seperti tapak Power Pages tradisional.

Konfigurasikan pembekal identiti

1. Pergi ke Power Pages.
2. Cari tapak anda dan pilih Edit.
3. Pilihpembekal Identiti>.
4. Tambah atau sediakan penyedia identiti, seperti Microsoft Entra ID.
5. Setiap tapak baharu secara automatik mempunyai pembekal Microsoft Entra ID lalai.

Akses konteks pengguna dalam kod

Dapatkan metadata pengesahan pada klien:

• URL Pihak Berkuasa:

  URL kuasa atau log masuk untuk Microsoft Entra ID ialah:

  https://login.windows.net/<tenantId>
  

• Cari URL Autoriti untuk pembekal identiti lain yang dikonfigurasikan dengan pergi ke tetapan konfigurasi Power Pages><your site>>Keselamatan>Pembekal identiti>.

• Butiran pengguna:

  window["Microsoft"].Dynamic365.Portal.User
  

Sampel aliran Reaksi

import { IconButton, Tooltip } from '@mui/material';
import {
    Login,
    Logout
} from '@mui/icons-material';
import React from 'react';
export const AuthButton = () => {
    const username = (window as any)["Microsoft"]?.Dynamic365?.Portal?.User?.userName ?? "";
    const firstName = (window as any)["Microsoft"]?.Dynamic365?.Portal?.User?.firstName ?? "";
    const lastName = (window as any)["Microsoft"]?.Dynamic365?.Portal?.User?.lastName ?? "";
    const tenantId = (window as any)["Microsoft"]?.Dynamic365?.Portal?.tenant ?? "";
    const isAuthenticated = username !== "";
    const [token, setToken] = React.useState<string>("");

    React.useEffect(() => {
        const fetchAntiForgeryToken = async (): Promise<string> => {
            try {
                const tokenEndpoint = "/_layout/tokenhtml";

                const response = await fetch(tokenEndpoint, {});

                if (response.status !== 200) {
                    throw new Error(`Failed to fetch token: ${response.status}`);
                }

                const tokenResponse = await response.text();                
                const valueString = 'value="';
                const terminalString = '" />';
                const valueIndex = tokenResponse.indexOf(valueString);

                if (valueIndex === -1) {
                    throw new Error('Token not found in response');
                }

                const requestVerificationToken = tokenResponse.substring(
                    valueIndex + valueString.length,
                    tokenResponse.indexOf(terminalString, valueIndex)
                );

                return requestVerificationToken || '';
            } catch (error) {
                console.warn('[Impersonation] Failed to fetch anti-forgery token:', error);
                return '';
            }
        };

        const getToken = async () => {
            try {
                const token = await fetchAntiForgeryToken();
                setToken(token);
            } catch (error) {
                console.error('Error fetching token:', error);
            }
        };
        getToken();
    }, []);

    return (
        <div className="flex items-center gap-4">
            {isAuthenticated ? (
                <>
                    <span className="text-sm">Welcome {firstName + " " + lastName}</span>
                    <Tooltip title="Logout">
                        <IconButton color="primary" onClick={() => window.location.href = "/Account/Login/LogOff?returnUrl=%2F"}>
                            <Logout />
                        </IconButton>
                    </Tooltip>
                </>
            ) : (
                <form action="/Account/Login/ExternalLogin" method="post">
                    <input name="__RequestVerificationToken" type="hidden" value={token} />
                    <Tooltip title="Login">
                        <IconButton name="provider" type="submit" color="primary" value={`https://login.windows.net/${tenantId}/`}>
                            <Login />
                        </IconButton>
                    </Tooltip>
                </form>
            )}
        </div>
    );
};

Gunakan API Web Power Pages

Pembangun boleh memanfaatkan API Web Power Pages untuk memuatkan kandungan ke dalam UI atau untuk mencipta, mengemas kini dan memadamkan rekod. Sebelum menggunakan API ini, pastikan API Web yang diperlukan didayakan dan keizinan jadual dan peranan web yang sesuai dikonfigurasikan dengan betul.

// Create query to get all cards from Dataverse
const fetchCards = async () => {
    const response = await fetch("/_api/cr7ae_creditcardses");
    const data = await response.json();
    const cards = data.value;
    const returnData = [];

    // Loop through the cards and get the name and id of each card
    for (let i = 0; i < cards.length; i++) {
        const card = cards[i];
        const cardName = card.cr7ae_name;
        const cardId = card.cr7ae_creditcardsid;
        const features = card.cr7ae_features
            ?.split(',')
            .map((feature: string) => feature.trim());
        const type = card.cr7ae_type;
        const image = card.cr7ae_image;
        const category = card.cr7ae_category
            ?.split(',')
            .map((cat: string) => cat.trim());
        
        // ...additional processing/pushing to returnData...
    }

    return returnData;
};

Sediakan pembangunan tempatan dengan mendayakan panggilan API Web daripada localhost menggunakan pengesahan Microsoft Entra ID

Pembangun memerlukan kitaran lelaran yang lebih pantas, penyahpepijatan tempatan dan keupayaan muat semula panas semasa membina aplikasi. SPA menyokong aliran kerja ini dengan mendayakan panggilan API Web selamat daripada localhost menggunakan pengesahan v1 Microsoft Entra ID (Azure AD).

Persediaan ini membolehkan anda:

• Jalankan apl anda secara setempat dengan sokongan pengesahan penuh.
• Gunakan alat pembangunan moden seperti Vite untuk muat semula panas dan maklum balas pantas.
• Elakkan isu CORS apabila memanggil API Web Power Pages.
• Mempercepatkan pembangunan tanpa menggunakan perubahan pada portal.

Konfigurasi ini membolehkan pengalaman pembangunan tempatan yang produktif untuk SPA, membolehkan pembangun membina, menguji dan mengulangi dengan cepat dengan akses API penuh dan sokongan pengesahan.

Penting

• Gunakan titik akhir Microsoft Entra v1 sahaja untuk pengesahan.
• Pengesahan pembawa hanya disokong dalam portal versi 9.7.6.6 atau lebih baru.
• Gunakan seting ini hanya dalam persekitaran pembangunan.

Langkah-langkah konfigurasi

1. Dayakan pengesahan SPA

   1. Dalam https://portal.azure.com, buka apl Microsoft Entra yang didaftarkan untuk portal anda.
   2. Dayakan pengesahan Aplikasi Satu Halaman (SPA).
   3. Tambah localhost sebagai URI ubah hala menggunakan konfigurasi platform aplikasi Halaman tunggal . Rujuk Cara menambah URI ubah hala dalam permohonan anda untuk maklumat lanjut.
      • Ubah hala URI:http://localhost:<port>/ .

2. Tambah tetapan tapak

   • Tambahkan tetapan site ini dalam Power Pages:

   Authentication/BearerAuthentication/Enabled = true
   Authentication/BearerAuthentication/Protocol = OpenIdConnect
   Authentication/BearerAuthentication/Provider = AzureAD
   

3. Gunakan ADAL.js untuk log masuk

   • Laksanakan log masuk bahagian pelanggan menggunakan ADAL.js.

   Nota

   MSAL.js tidak serasi kerana Power Pages menggunakan titik akhir v1 Microsoft Entra, manakala MSAL menggunakan v2. Format penerbit berbeza antara versi.

4. Tambah pengepala kebenaran

   • Sertakan pengepala ini dalam semua permintaan API Web:

   Authorization: Bearer <id_token>
   

5. Tetapkan keterlihatan tapak kepada Awam

   • Tetapan ini membolehkan localhost mengakses tapak untuk tujuan pembangunan dan ujian.

6. Konfigurasikan proksi pembangunan

   • Jika anda menggunakan Vite, tambahkan ini untuk vite.config.js mengelakkan isu CORS:

   export default defineConfig({
     plugins: [react()],
     server: {
       proxy: {
         '/_api': {
           target: 'https://site-foo.powerappsportals.com',
           changeOrigin: true,
           secure: true
         }
       }
     }
   });
   

Perbezaan daripada tapak Power Pages sedia ada

Jadual berikut meringkaskan perbezaan utama antara tapak SPA yang dicipta dengan ciri ini dan tapak Power Pages tradisional:

Ciri	Tingkah laku tapak SPA
Muat semula bahagian pelayan	Sentiasa mengembalikan halaman akar tapak dan penghala bahagian klien memaparkan sub-laluan.
Konflik laluan	Laluan bahagian pelanggan diutamakan, dan penyegaran keras kembali ke akar.
Ruang kerja halaman	Ruang kerja halaman tidak disokong. Gunakan penghalaan pelanggan dan halaman laman klien. Untuk keselamatan peringkat halaman, semak peranan web yang diperuntukkan dengan objek pengguna global dan render UI secara bersyarat.
Ruang kerja gaya	Penggayaan dengan ruang kerja gaya tidak disokong. Gunakan penggayaan rangka kerja anda, seperti CSS, CSS-dalam-JS atau kelas utiliti.
Penyetempatan	Sokongan bahasa tunggal. Laksanakan pemuatan sumber bahagian pelanggan.
Templat cecair	Kod cecair dan templat Cecair tidak disokong. Akses data dengan menggunakan enjin templat rangka kerja anda dan API Web.

FAQ

Apakah sokongan yang tersedia untuk ujian unit dan penyepaduan?

Pada masa ini, tiada sokongan terbina dalam untuk ujian unit dan penyepaduan. Pembuat harus menulis dan melaksanakan ujian ini secara tempatan atau dalam saluran paip CI/CD mereka.

Adakah terdapat sokongan untuk Power Fx penyepaduan menggunakan WebAssembly?

Keupayaan ini tidak disokong pada masa ini.

Adakah kod sumber tersedia dalam Power Pages?

Pada masa ini, pembuat boleh membina tapak web menggunakan TypeScript atau GitHub Copilot Agent. Fail JavaScript dan CSS yang disusun boleh diakses dan boleh diedit dalam Visual Studio Code. Walau bagaimanapun, penyuntingan fail HTML secara langsung dan meluas tidak disokong pada masa ini.

Bolehkah saya mencipta komponen secara luaran menggunakan ciri ini dan membawanya ke tapak Power Pages?

Tidak, anda tidak boleh membawa komponen yang dijana luaran ke laman Power Pages sedia ada menggunakan ciri ini.

Bolehkah saya menambah komponen di luar kotak seperti senarai dan borang?

Menambah komponen di luar kotak seperti senarai dan borang tidak disokong pada masa ini. Walau bagaimanapun, anda boleh membina borang dan senarai tersuai menggunakan rangka kerja React dan API Web.

Bagaimanakah kawalan sumber berfungsi?

Pembangun boleh menggunakan Power Platform penyepaduan Git untuk kawalan sumber. Walau bagaimanapun, hanya fail web yang disusun ditambahkan pada repositori, bukan kod sumber penuh.

Adakah laman web ini menyokong SEO?

Oleh kerana laman web SPA dibina dengan rangka kerja React dan menggunakan rendering sisi pelanggan, sokongan SEO adalah terhad.

Apakah sokongan keselamatan dan tadbir urus Power Pages yang ditawarkan oleh tapak SPA?

Power Pages menguatkuasakan keizinan jadual dan peranan web keselamatan pada panggilan API Web, memastikan capaian data sejajar dengan peranan pengguna. Gunakan window["Microsoft"].Dynamic365.Portal.User objek untuk mendapatkan semula sifat pengguna asas dan menyesuaikan pengalaman berdasarkan persona pengguna.

Selain itu, tapak SPA menyokong:

• Konfigurasi tapak awam dan swasta
• Tetapan tadbir urus, termasuk kawalan ke atas capaian data tanpa nama
• Konfigurasi pembekal pengesahan

Ciri-ciri ini membantu memastikan penyepaduan komponen tersuai yang selamat dan patuh dalam Power Pages.

Maklumat berkaitan

• Microsoft Power Platform CLI
• Tutorial: Gunakan CLI Microsoft Power Platform dengan Power Pages
• Gunakan sambungan Kod Visual Studio