用戶端 API 表單、分頁與區段

使用 Power Pages 客戶端 API 表單、分頁、區塊及控制項來檢查和管理頁面元素。 本參考文獻說明可用的集合、屬性及控制可見性、數值與多步驟導航的方法。

$pages.currentPage.forms

該 $pages.currentPage.forms 合集包含處理頁面表單元素的方法。

$pages.currentPage.forms 方法

利用這些方法列出表單並取得特定的表單實例。

方法	Returns	描述
getAll	IForm[]	回傳所有新增到目前頁面的表單。
getFormById(id: string)	IForm	透過 HTML 元素 ID 檢索表單。
getFormByName(name: string)	IForm	透過名稱檢索表單。

$pages.currentPage.forms 方法範例

這些範例展示了如何取得所有表單，並依 ID 或姓名檢索特定表單。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let forms = $pages.currentPage.forms.getAll();
    let form1 = $pages.currentPage.forms.getFormById('form_#1');
    let form2 = $pages.currentPage.forms.getFormByName('form_name')
});

IForm 介面

介面 IForm 代表一個控制項與分頁的容器。

IForm 性質

以下屬性描述表單及其包含的控制項和分頁。

財產	類型	描述
id	字串	表格的識別碼。
name	字串	表單的名稱。
controls	束[]	所有控制都放在表格上。
tabs	標籤[]	所有分頁都在表格上。
isMultiStep	布爾	若形式為多步，則為真;否則，則為錯誤。 參見 多步驟形式。

IForm 方法

利用這些方法查詢表單的可見性，並切換是否可見。

方法	Returns	描述
getVisible	boolean	若形式可見，則返回真;否則，則為錯誤。
setVisible(isVisible: boolean)	void	設定表單的可見度。
getHtmlElement	HTMLElement	回傳表單底層的 HTML 元素。
getControlByLogicalName(logicalName: string)	控制 | undefined	回傳具有指定邏輯名稱的表單控制項，例如欄位結構名稱。 當沒有控制點匹配時，回傳未定義。

IForm 範例

以下範例依 ID 檢索表單，並記錄其可見性、控制項數量及分頁數。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let form = $pages.currentPage.forms.getFormById('form_#1');

    console.log(`Form id: ${form.id} has ${form.controls.length} controls.`);

    if (form.getVisible()) {
        console.log('Form is currently visible.');
    }
    let tabs = form.tabs;
    console.log(`Form has ${tabs.length} tabs.`);

    // Look up a control by its logical name.
    let nameControl = form.getControlByLogicalName('fullname');
    if (nameControl) {
        nameControl.setValue('Jane Doe');
    }
});

多步驟表單

多步驟表單是一種容器，可以容納多個基本表單。

多步形式性質

以下屬性適用於多步驟表單容器，並描述目前啟動步驟中可用的內容。

財產	類型	描述
id	字串	多步驟表單的 ID。
controls	束[]	所有控制項都在當前步驟。
tabs	標籤[]	目前步驟中的所有分頁。
isMultiStep	布爾	若形式為多步，則為真;否則，則為錯誤。
nextButton	JQuery 元素	代表下一個按鈕（若不存在則為空物件）。
previousButton	JQuery 元素	代表前一個按鈕（若缺少則為空物件）。

多步驟形式方法

利用這些方法檢查可見性，並以多步驟形式在步驟間切換。

Name	Returns	描述
getVisible	boolean	若形式可見，則返回真;否則，則為錯誤。
setVisible(isVisible: boolean)	void	設定表單的可見度。
hasNextStep	boolean	若存在下一步，則返回真;否則，則為錯誤。
hasPreviousStep	boolean	若存在前一步，則返回為真;否則，則為錯誤。
goToNextStep	void	引導他進入下一步;若無下一步，則提交表單。
goToPreviousStep	void	切換到前一步驟;若不存在例外，則拋出例外。
getControlByLogicalName(logicalName: string)	控制 | undefined	回傳當前步驟中具有指定邏輯名稱的控制項，例如欄位結構名稱。 當沒有控制點匹配時，回傳未定義。

多步驟形式範例

此範例展示了如何檢索多步驟表單、檢查並推進下一步。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let form = $pages.currentPage.forms.getFormById('multiform_#1');
    console.log(`Form id: ${form.id} has ${form.controls.length} controls.`);

    if (form.getVisible()) {
        console.log('Form is currently visible.');
    }

    let tabs = form.tabs;
    console.log(`Form has ${tabs.length} tabs.`);

    form.goToNextStep();
});

Tab

A Tab 包含表單中的一個或多個區段。

Tab Sections 屬性

分頁內有多個 區塊 。

制表法

使用這些方法檢查分頁的可見性、取得名稱，並切換是否可見。

方法	Returns	描述
getVisible	boolean	如果標籤是可見的，則會回傳為真;否則，則為錯誤。
getName	string	傳回索引標籤的名稱。
setVisible(isVisible: boolean)	void	設定分頁的可見性。

Tab 範例

此範例會取得表單、列舉其分頁，並記錄第一個分頁名稱。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let form = $pages.currentPage.forms.getFormById('form_#1');
    let tabs = form.tabs;
    console.log(`Form has ${tabs.length} tabs.`);
    console.log(`First tab is named: ${tabs[0].getName()}`);
});

章節

區段在分頁內將控制群組。

剖面 Controls 性質

區段內有一系列 控制項 。

剖面方法

利用這些方法讀取區名並控制其可見性。

方法	Returns	描述
getVisible	boolean	若該截面可見，則返回為真;否則，則為錯誤。
getName	string	回傳區名。
setVisible(isVisible: boolean)	void	設定該區段的可見度。

剖面範例

此範例從表單的第一個分頁擷取區段並記錄基本細節。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let form = $pages.currentPage.forms.getFormById('form_#1');
    let sections = form.tabs[0].sections;
    console.log(`Tab has ${sections.length} section(s).`);
    console.log(`First section is named: ${sections[0].getName()}`);
});

管理

A Control 代表單一形態元素。 使用 常見的控制方法 來取得或更新其值、可見性、所需狀態與停用狀態，並新增用戶端驗證功能。 值類型與額外成員依 控制類型而異。

相關資訊

• 用戶端 API 概述
• 用戶端 API 範例