Salesforce LWC學習(六) @salesforce & lightning/ui*Api Reference

上一篇中我們在demo中使用了很多的 @salesforce 以及 lightning/ui*Api的方法，但是很多沒有細節的展開。其實LWC中針對這些module提供了很多好用的方法，下面對這兩種進行詳細介紹。

一. @Salesforce

@salesforce模塊封裝了很多的方法，用於在運行時添加相關的功能。主要方法及使用如下。

1. @salesforce/apex : 此方法用於引入apex的方法，這里的方法包括自定義的方法以及標准的預置的方法，具體操作如下。
1）引入自定義apex類的方法：我們在項目中和后台apex代碼交互，首先需要做的就是使用此標簽引入需要用到的類的方法。

import apexMethod from '@salesforce/apex/Namespace.Classname.apexMethod';
@wire(apexMethod, { apexMethodParams })
propertyOrFunction;

針對此函數相關的變量在上一篇有細節描述，除了引入自定義apex方法以外，還有其他的一些封裝的標准的方法。
2）getSObjectValue(sobject, fieldApiName)：此方法用與從一個object中獲取指定的field的值。這個object是從apex中搜索出來的。
此方法兩個參數，sobject代表從后台apex中搜索出來的數據，fieldApiName為想要查詢字段值的API name。fieldApiName可以是String類型的api name也可以通過@salesforce/schema方式引入進來。我們在搜索時可能獲取父層數據，比如搜索opportunity數據時需要獲取其對應的account的owner信息，此種父查詢展示的最大深度為5層，比如Opportunity.Account.CreatedBy.LastModifiedBy.Name。 
頭部需要引用：import { getSObjectValue } from '@salesforce/apex';然后調用此方法即可。

getSObjectValueDemo.html

<template>
    {accountOwnerName}
</template>

getSObjectValueDemo.js：調用findOpportunity后台方法，此方法搜索了Opportunity的Account.Owner.Name，我們可以使用getSObjectValue獲取其字段結果。

import { LightningElement, wire } from 'lwc';
import findOpportunity from '@salesforce/apex/OpportunityController.findOpportunity';
import { getSObjectValue } from '@salesforce/apex';
import OPPORTUNITY_ACCOUNT_OWNER_NAME from '@salesforce/schema/Opportunity.Account.Owner.Name';
export default class GetSObjectValueDemo extends LightningElement {

    @wire(findOpportunity,{searchKey:'test'})
    opportunityList;

    get accountOwnerName() {
        if(this.opportunityList.data !== undefined) {
            const opportunity = this.opportunityList.data[0];
            return getSObjectValue(opportunity,OPPORTUNITY_ACCOUNT_OWNER_NAME);
        }
        return '';
    }
}

OpportunityController.cls

public with sharing class OpportunityController {
    @AuraEnabled(cacheable=true)
    public static List<Opportunity> findOpportunity(String searchKey){
        String key = '%' + searchKey + '%';
        return [SELECT Id,Account.Owner.Name
                    FROM Opportunity
                    WHERE Name like :key 
                    ORDER BY LastModifiedDate DESC
                    limit 1];
    }
}

3）refreshApex(wiredProperty)：用於使用wire注解情況下針對緩存變量的刷新，此方法只針對緩存變量，其他情況無法使用。

頭部需要引用：import { refreshApex } from '@salesforce/apex';
詳情用法可以查看上一篇。

4）@salesforce/apexContinuation：主要用於長時間運行的callout，此功能后期會單獨描述。

5）@salesforce/label：用於引入custom label。
頭部需要引入：import labelName from '@salesforce/label/labelReference'
其中：
labelName為我們起的名字，后期js以及前台html中用到此custom label的地方需要使用此名字作為引用
labelReference為在我們org中聲明的custom label的label name。引入時需要使用namespace.labelName格式進行引用，如果不是manage package，默認的namespace為c。

因為我們在js中可能獲取多個custom label，所以我們可以封裝在一個label的變量中，通過label.labelName方式獲取。custom label我們聲明的時候會有兩種形式，一種是正常的，另外一種是可以使用{0}{1}這種format的操作的label。針對classic以及lightning aura我們可以很輕易的對format的label進行處理，遺憾的是針對lwc並沒有直接的方式去處理，我們可以使用正則表達式進行函數處理。

stringUtils.js：用於解析字符串中使用{}處理的占位符。

const formatString = (stringForFormat,params) => {
    let str = stringForFormat;
    for (let i = 0; i < params.length; i++) {
        let re = new RegExp('\\{' + i + '\\}', 'gm');
        str = str.replace(re, params[i]);
    }
    return str;
};
export {formatString};

getCustomLabelDemo.js：引入方法，針對包含format的字符串進行處理。

import { LightningElement } from 'lwc';
import sampleLabel from '@salesforce/label/c.sample_label';
import sampleLabelWithParam from '@salesforce/label/c.sample_label_with_param';
import {formatString} from 'c/stringUtils';
export default class GetCustomLabelDemo extends LightningElement {

    get formatedSampleLabelWithParam() {
        let paramList = new Array();
        paramList.push('xx');
        return formatString(sampleLabelWithParam,paramList);
    }

    label = {
        sampleLabel
    };
}

getCustomLabelDemo.html：展示兩個custom label

<template>
    {label.sampleLabel}
    <br/>
    {formatedSampleLabelWithParam}
</template>

顯示結果：

6）@salesforce/resourceUrl：引入static resource。頭部根據當前的靜態資源是否在managed package中有兩種引用的方式：

import resourceName from '@salesforce/resourceUrl/resourceReference';
import myResource from '@salesforce/resourceUrl/namespace__resourceReference';

demo如下：

 useStaticResourceDemo.js：引入static resource，在sample目錄下有一個sample.png圖片，前台展示此圖片

import { LightningElement } from 'lwc';
import sampleResource from '@salesforce/resourceUrl/lwc_sample';
export default class UseStaticResourceDemo extends LightningElement {
    pictureSampleURL = sampleResource + '/sample/sample.png';
}

useStaticResourceDemo.html：展示此圖片

<template>
    <img src={pictureSampleURL}/>
</template>

效果展示：

7）@salesforce/schema：引入object以及field的引用。當我們使用LDS或者wire service獲取字段的引用時，官方建議我們使用此種方式而不是字符串方式，詳細使用操作可以查看上一篇博客。

8）@salesforce/user：獲取當前user的信息。通過此引用可以獲取當前user的id 以及當前user是否是一個community guest user。我們通過

import property from '@salesforce/user/property';來引用,property有兩個值：Id / isGuest.下面是一個關於user信息的獲取的demo。

getUserInfoDemo.js

import { LightningElement } from 'lwc';
import Id from '@salesforce/user/Id';
import isGuest from '@salesforce/user/isGuest';
export default class GetUserInfoDemo extends LightningElement {
    userId = Id;
    isGuestUser = isGuest;
}

getUserInfoDemo.html

<template>
    current user Id : {userId}<br/>
    current user is Guest {isGuestUser}
</template>

以上的內容為@salesforce模塊封裝的主要方法，詳情還請自行查看文檔。接下來的幾部分我們講的主要是 lightning/ui*Api部分的wire adapter，其主要是為了擴充LDS標准以外的增強方法。LWC針對數據的操作以及解析如下圖所示。LWC wire adapter以及LDS轉成的都是User Interface API中的內容，所以如果想更好的了解各個wire adapter的使用以及返回類型的詳情還請查看User Interface API。下載地址：https://resources.docs.salesforce.com/220/latest/en-us/sfdc/pdf/api_ui.pdf

二. lightning/uiListApi

此模塊主要用於針對一個list view獲取數據以及metadata。我們針對某個對象數據創建列表視圖時，會進行相關的filter，展示某些固定的列，展示多少數據等操作。使用lightning/uiListApi模塊我們可以通過object的api name等信息便可以獲取到指定的list view的數據。需要注意一點的是，此模塊以及模塊中的方法目前是beta功能。

1. getListUi：此wire adapter方法用於獲取list view中的數據。我們可以通過幾個參數以及幾種形式獲取數據。

1) 使用 object 的api name以及 list view的api name去獲取數據；

import { getListUi } from 'lightning/uiListApi';
@wire(getListUi, { objectApiName: objName, listViewApiName: listViewName })
propertyOrFunction;

其中objName代表想要獲取哪個表的數據，取得是表的api name
listViewName取得是當前表的哪個list view的數據，取得是 list view的api name
2）使用list view的id 獲取數據；

import { getListUi } from 'lightning/uiListApi';
@wire(getListUi, { listViewId:listViewId})
propertyOrFunction;

3）使用object 的api name以及MRU（Most Recently Used）去獲取數據.我們在每個表的list view中都有一個rencent view的視圖，這個是標准的一個視圖，LWC針對此視圖有專門的取法。

import { getListUi, MRU } from 'lightning/uiListApi';
@wire(getListUi, { objectApiName: objectName, listViewApiName: MRU })
propertyOrFunction;

除了上述的必傳的參數以外，此適配器方法還提供了其他的可選參數，比如pageSize等。

https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_records_md.htm#request_parameters

https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_mru_list_views_records.htm

import { LightningElement, wire,track } from 'lwc';
import {getListUi} from 'lightning/uiListApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
export default class GetListUIDemo extends LightningElement {
    @track error;
    @track accountList;
    @wire(getListUi,{objectApiName:ACCOUNT_OBJECT,listViewApiName:'AllAccounts',pageSize:100})
    wiredAccountList({error,data}) {
        if(data) {
            this.accountList = data.records.records;
            this.error = undefined;
        } else if(error) {
            this.error = error;
            this.accountList = undefined;
        }
    }
}

getListUIDemo.html

<template>
    <lightning-card title="get list ui demo" icon-name="standard:action_list_component">
 
        <table class="slds-table slds-table_cell-buffer slds-table_bordered">
            <thead>
                <tr class="slds-line-height_reset">
                    <th class="" scope="col">
                        <div class="slds-truncate">Account Id</div>
                    </th>
                    <th class="" scope="col">
                        <div class="slds-truncate">Account Name</div>
                    </th>
                    <th class="" scope="col">
                        <div class="slds-truncate">Type</div>
                    </th>
                    <th class="" scope="col">
                        <div class="slds-truncate">Phone</div>
                    </th>
                </tr>
            </thead>
            <tbody>
                <template if:true={accountList}>
                    <template for:each={accountList} for:item="account">
                        <tr key={account.id}>
                            <td>{account.id}</td>
                            <td> {account.fields.Name.value}</td>
                            <td> {account.fields.Type.value}</td>
                            <td> {account.fields.Phone.value}</td>
                        </tr>
                    </template>
                </template>
                <template if:false={accountList}>
                    List View is not contains any data
                </template>
            </tbody>
        </table>
    </lightning-card>
</template>

結果展示：

 三. lightning/uiObjectInfoApi

此模塊的適配器方法用於獲取object的metadata以及picklist的value。

1. getObjectInfo：使用wire adapter針對指定的object獲取相關的metadata。response包括描述fields/ child relationships / record type/theme metadata信息。下圖可以看到我們demo中用到的獲取Account的getObjectInfo的結構。我們對於apex中的Schema有了解情況下，可以理解成此適配器相當於DescribeSObjectResult以及相關的方法用來獲取相關的metadata信息。demo中我們會演示獲取某個字段的label信息，感興趣的可以自行研究。

 

 getSObjectInfoDemo.js：獲取Account表中的AccountSource的label值

import { LightningElement,wire } from 'lwc';
import { getObjectInfo } from 'lightning/uiObjectInfoApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
export default class GetObjectInfoDemo extends LightningElement {
    @wire(getObjectInfo, { objectApiName: ACCOUNT_OBJECT })
    accountInfo;

    get recordInfo() {
        if(this.accountInfo.data !== undefined) {
            return this.accountInfo.data.fields.AccountSource.label;
        }
        return '';
    }
}

getSObjectInfoDemo.html：展示AccountSource的label值

<template>
    {recordInfo}
</template>

2. getPicklistValues：使用此wire adapter獲取某個 picklist類型字段的picklist value。我們接觸apex知道，picklist 字段獲取可以使用兩種方式，基於record type方式獲取某個record type的picklist values以及獲取picklist類型字段的所有的values。此wire adapter為通過record type獲取values。此wire adapter需要傳兩個參數，第一個參數是object的某個record type id，第二個參數是想要獲取的picklist類型的字段API名稱。

@wire(getPicklistValues, { recordTypeId: recordTypeId, fieldApiName: fieldApiName })
propertyOrFunction;

其中,recordTypeId為我們想要操作的指定record type的ID。我們可以根據getObjectInfo 或者getRecordUi這兩個wire adapter獲取。此變量為必填字段，我們如果想變量改變getPicklistValues動態改變，我們可以使用'$'符號去封裝此變量;fieldApiName為想要查詢字段的API name，這里推薦使用@salesforce/schame去獲取field api的reference。返回的類型有兩種，變量或者是方法，變量封裝data和error兩個子變量，使用方法我們可以將這兩個作為參數進行展示。詳見上篇的propertyOrFunction的使用。

下面的demo我們來獲取account中的industry的picklist values。

getObjectInfoDemo.js：首先我們先使用getObjectInfo獲取Account的schema信息，然后通過getPicklistValues獲取picklist信息，這里使用$作為動態傳參，保證當objectInfo變量先裝載，裝載以后執行getPicklistValues。

import { LightningElement,wire} from 'lwc';
import { getObjectInfo } from 'lightning/uiObjectInfoApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
import {getPicklistValues} from 'lightning/uiObjectInfoApi';
import ACCOUNT_INDUSTRY_FIELD from '@salesforce/schema/Account.Industry';
export default class GetObjectInfoDemo extends LightningElement {

    @wire(getObjectInfo,{objectApiName:ACCOUNT_OBJECT})
    objectInfo;

    @wire(getPicklistValues,{ recordTypeId: '$objectInfo.data.defaultRecordTypeId', fieldApiName: ACCOUNT_INDUSTRY_FIELD })
    industryList;
}

getObjectInfoDemo.html：使用for:each進行遍歷industry list,使用select option進行展示數據。

<template>
    <lightning-card title="Industry List ">
        <template if:true={industryList.data}>
            <div class="slds-m-around_medium">
                <select>
                    <template for:each={industryList.data.values} for:item="item">
                        <option key={item.value}>{item.label}</option>
                    </template>
                </select>
            </div>
        </template>
    </lightning-card>
</template>

效果如下：

 3. getPicklistValuesByRecordType：此方法用於獲取某個對象，某個record type的所有的picklist 的values，這些picklist values封裝在一個map中。

@wire(getPicklistValuesByRecordType, { objectApiName: objectName, recordTypeId: recordTypeId })
propertyOrFunction

其中objectName為想要獲取的object的所有的picklist values的object api name，此字段必填，推薦使用@salesforce/schema獲取，recordTypeId也是必填字段，獲取方式同上一個wire adapter。我們通過一個例子更好的理解。

getPicklistValuesByRecordTypeDemo.js：用來獲取record type名稱為 Test Record Type的所有的picklist values信息。

import { LightningElement, wire,track } from 'lwc';
import {getObjectInfo} from 'lightning/uiObjectInfoApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
import {getPicklistValuesByRecordType} from 'lightning/uiObjectInfoApi';
export default class GetPicklistValuesByRecordTypeDemo extends LightningElement {
    @track recordTypeId = '';
    @wire(getObjectInfo,{objectApiName:ACCOUNT_OBJECT})
    getObjectInfo({data,error}) {
        if(data) {
            const allRecordTypeInfos = data.recordTypeInfos;
            // eslint-disable-next-line no-console
            console.log(JSON.stringify(allRecordTypeInfos));
            this.recordTypeId = Object.keys(allRecordTypeInfos).find(rti => allRecordTypeInfos[rti].name === 'Test Record Type');
        } else if(error) {
            //TODO
        }
    }

    @wire(getPicklistValuesByRecordType,{ objectApiName: ACCOUNT_OBJECT, recordTypeId: '$recordTypeId'})
    picklistValues;

    get demo() {
        // eslint-disable-next-line no-console
        console.log(JSON.stringify(this.picklistValues));
        return this.recordTypeId;
    }

}

這里我們使用getObjectInfo獲取所有的record type，打印出來的all record type 信息如下所示，我們可以看出來，它的結果集是一個Map，key是record type id，value封裝了相關的細節信息，我們使用Object.key.find來獲取指定名稱的record type id信息。此使用方法是javascript的遍歷map的使用，感興趣的可以自行查看。

 

 通過record type id我們使用getPicklistValuesByRecordType獲取所有的picklist valus，格式的層級模式如下圖所示。

 獲取到層級模式以后，我們對程序進行一下增強，獲取所有的AccountSource的picklist values。

在上面的js方法中添加此方法。

get accountSourcePicklistValues() {
   // eslint-disable-next-line no-console
   console.log(JSON.stringify(this.picklistValues));
   if(this.picklistValues !== undefined && this.picklistValues.data !== undefined) {
       return this.picklistValues.data.picklistFieldValues.AccountSource.values;
    }
    return '';
}

getPicklistValuesByRecordTypeDemo.html

<template>
    <lightning-card title="Account Source List ">
        <template if:true={accountSourcePicklistValues}>
            <div class="slds-m-around_medium">
                <select>
                    <template for:each={accountSourcePicklistValues} for:item="item">
                        <option key={item.value}>{item.label}</option>
                    </template>
                </select>
            </div>
        </template>
    </lightning-card>
</template>

效果展示：

三. lightning/uiRecordApi

此模塊中的wire adapter主要用於進行數據的CRUD。下面列舉幾個主要的方法，其他的方法還請自行查看文檔。

1. getRecord：用於通過record id獲取此id對應的record 信息，詳情用法以及參數介紹參看上一篇，有詳細描述。

@wire(getRecord, { recordId: string, fields: string[], optionalFields?: string[])
propertyOrFunction

@wire(getRecord, { recordId: string, layoutTypes: string[],
                   modes?: string[], optionalFields?: string[])
propertyOrFunction

2. getRecordUi：使用此wire adapter可以針對一條或者多條記錄獲取其對應的page layout，metadata以及在UI上面的數據信息。我們上面也講過如果想要獲取record type id也可以使用此wire adapter。

@wire(getRecordUi, { recordIds: string, layoutTypes: string,
                       modes: string, optionalFields?: string[] })
propertyOrFunction;

  @wire(getRecordUi, { recordIds: string[], layoutTypes: string[], 
                       modes: string[], optionalFields?: string[] })
propertyOrFunction;

可以看到參數和getRecord很相似，返回的對象為Record UI對象以及error兩個。我們可以在User Interface中封裝的Record UI查看返回的結構以及如何獲取需要的內容信息。返回的層級結構以及信息如下圖所示，我們只需要根據不同的取值需要獲取不同的值即可。

3. getFieldValue(record,field)：此方法用於獲取記錄中指定field API對應的value。需要注意的是，他獲取的永遠是API value。此方法的demo在上一篇有介紹，可以查看上一篇。

4. getFieldDisplayValue(record,field)：此方法相對上一個方法的區別為此方法獲取的是展示的value。比如一個picklist字段，我們有國際化操作，針對picklist value可能是英文，但是我們對其中文進行translation，那么針對語言為中文的客戶，getFieldValue獲取的是picklist 的value，即英文的值，getFieldDisplayValue獲取的是中文的值。

 getFieldDisplayValueDemo.js：此方法用於獲取Account Source的value以及display value

import { LightningElement,api, wire } from 'lwc';
import {getRecord} from 'lightning/uiRecordApi';
import {getFieldValue} from 'lightning/uiRecordApi';
import {getFieldDisplayValue} from 'lightning/uiRecordApi';
import ACCOUNT_ACCOUNT_SOURCE from '@salesforce/schema/Account.AccountSource';
export default class GetFieldDisplayValueDemo extends LightningElement {
    @api recordId;

    @wire(getRecord,{recordId:'$recordId',fields:[ACCOUNT_ACCOUNT_SOURCE]})
    account;

    get accountSourceValue() {
        if(this.account.data !== undefined) {
            return getFieldValue(this.account.data,ACCOUNT_ACCOUNT_SOURCE);
        }
        return '';
    }

    get accountSourceDisplayValue() {
        if(this.account.data !== undefined) {
            return getFieldDisplayValue(this.account.data,ACCOUNT_ACCOUNT_SOURCE);
        }
        return '';
    }
}

getFieldDisplayValueDemo.html

<template>
    value : {accountSourceValue}<br/>
    label : {accountSourceDisplayValue}
</template>

效果展示

5. createRecord(recordInput: Record)：此方法用於創建一條記錄，其中Record我們需要使用wire service提供的generateRecordInputForCreate(record,objectInfo) 這個wire adapter去實例化一個Record。返回類型為一個Promise，即當前的這個Record，包括當前記錄的page layout中的信息。使用createRecord以及使用updateRecord這兩個方法前需要先思考是否可以使用lightning-record-form以及lightning-record-edit-form去搞定。搞定不了情況下在使用wire adapter。此wire adapter官方提供了簡單的demo，查看此鏈接便可以更好的了解此wire adapter：https://developer.salesforce.com/docs/component-library/documentation/lwc/lwc.data_salesforce_write

6. updateRecord(recordInput, clientOptions)：同上方法，用於編輯一條記錄，參數中的recordInput需要使用wire service提供的generateRecordInputForUpdate(record,objectInfo)去搞定，還是和上面的一樣，如果實在搞定不了在使用此方法，否則盡量別用。

7. deleteRecord(recordId)：用於刪除一條記錄，傳入當前的record id即可實現刪除操作。方法為void類型，沒有返回內容。

總結：篇中簡單的整理了一些針對@salesforce 以及 lightning/record*Api模塊的方法，細節的方法描述還請自行查看官方文檔以及User Interface API。其實除了這兩個module，LWC還提供了很多好用的module，比如lightning/platformShowToastEvent用於展示toast信息等等，還要靠小伙伴自己挖掘。另外需要注意的一點的是，針對wire service的這些wire adapter，如果可以使用lightning:record-form相關的搞定，能不用盡量不用，標准功能搞定不了在考慮使用。篇中有錯誤地方歡迎指出，有不懂的歡迎提問。