內容片段選擇器 - 相關屬性 content-fragment-selector-related-properties

微前端內容片段選擇器可讓您瀏覽或搜尋存放庫中的內容片段,並在您的應用程式中使用這些片段。

您可以使用以下屬性來自訂內容片段選擇器的呈現方式及其使用方式。

內容片段選擇器屬性 content-fragment-selector-properties

屬性
類型
必要
預設
說明
ref
FragmentSelectorRef
參考ContentFragmentSelector執行個體,允許存取提供的功能,例如reload
apiKey
字串
API金鑰已於digitalData.page.attributes.apiKey回報給分析。 僅用於追蹤,不適用於資料API呼叫。 若未提供,則是從imsTokenclient_id宣告)衍生而來,遞補為封裝預設值。
imsToken
字串
用於驗證的IMS權杖。 如果未提供,將起始IMS登入流程。
repoId
字串
用於片段選擇器的存放庫ID。 提供後,選取器會自動連線至指定的存放庫,而存放庫下拉式清單會隱藏。 如果未提供,使用者可以從他們有權存取的可用存放庫清單中選取存放庫。
allowedRepositoryIds
字串[]
在內容片段選擇器中篩選存放庫和內容片段的存放庫ID清單。 若提供存放庫ID,存放庫選擇器中只會顯示這些存放庫。 如果未提供或陣列為空,則使用者有權存取的所有存放庫都將可供使用。
defaultRepoId
字串
顯示存放庫選擇器時,預設會選取的存放庫ID。 僅在未提供repoId時使用。 如果設定repoId,則會隱藏存放庫選擇器,並忽略此值。
orgId
字串
用於驗證的組織ID。 如果未提供,使用者可以從他們有權存取的不同組織中選擇存放庫。 如果使用者無權存取任何存放庫或組織,則不會載入內容。
locale
字串
“en-US”
地區設定。
env
字串
部署環境。 檢視允許的環境名稱的Env型別。
filters
Fragmentfilter
{ folder: "/content/dam" }
要套用至內容片段清單的篩選器。 依預設,/content/dam下的片段將會顯示。
repoFilters
記錄<string, FragmentFilterWithReadonlySupport>
依存放庫ID輸入的每個存放庫篩選器會覆寫。
當選擇器公開多個存放庫,但每個存放庫需要不同的篩選器時使用(例如,狀態:一個作者執行個體的草稿,而其他執行個體使用「狀態:已發佈、已修改」)。
當使用中的存放庫有專案時,它會完全取代該存放庫的篩選器(預設值不會合併到),因此每個覆寫都必須宣告它需要的完整篩選器集。 沒有專案的存放庫會回覆為篩選器,因此省略repoFilters會保留現有行為。 當使用者切換存放庫時,會自動重新套用覆寫。 每個專案支援與篩選器相同的唯讀標籤。
isOpen
布林值
false
控制選取器是開啟還是關閉的旗標。
noWrap
布林值
false
決定是否呈現片段選擇器而不使用包裝對話方塊。 設定為true時,片段選擇器會直接內嵌在父容器中。 將選取器整合至自訂配置或工作流程時相當實用。
onSelectionChange
({ contentFragments: ContentFragmentSelection, domainName?: string, tenantInfo?: string, repoId?: string, deliveryRepos?: DeliveryRepository[] }) => void
每當內容片段的選擇變更時,就會觸發回呼函式。 提供目前選取的片段、網域名稱、租使用者資訊、存放庫ID和傳遞存放庫。
onDismiss
() =>無效
執行解除動作時觸發的回呼函式(例如,關閉選取器)。
onSubmit
({ contentFragments: ContentFragmentSelection, domainName?: string, tenantInfo?: string, repoId?: string, deliveryRepos?: DeliveryRepository[] }) => void
使用者確認選取時觸發的回呼函式。 接收選取的內容片段、網域名稱、租使用者資訊、存放庫ID和傳遞存放庫。
theme
“light"或"dark”
片段選擇器的主題。 預設會設定為unifiedShell環境主題。
selectionType
「單一」或「多個」
single
選擇型別可用於限製片段選擇器的選擇。
maxItems
數字
selectionTypemultiple時可選取的專案數上限。 若未指定,則允許無限制的選取。 不適用於單一選取模式。
dialogSize
“fullscreen"或"fullscreenTakeover”
fullscreen
控制對話方塊大小的選用Prop。
runningInUnifiedShell
布林值
DestinationSelector是在UnifiedShell下執行,還是獨立執行。
selectedFragments
ContentFragmentIdentifier[]
[]
選擇器開啟時要預先選取的內容片段的初始選擇。
hipaaEnabled
布林值
false
指出是否已啟用HIPAA規範。
inventoryView
InventoryViewType
table
要用於選擇器的詳細目錄預設檢視型別。
inventoryViewToggleEnabled
布林值
false
表示是否啟用庫存檢視切換,讓使用者在表格檢視和格線檢視之間切換。
selectFields
布林值
false
表示是否啟用欄位選取步驟。 當true時,使用者會挑選要針對每個選取的片段公開哪些欄位,而選取的欄位會在onSelectionChangeonSubmit裝載上以每個片段selectedFields對應的形式傳回。 當false (預設)時,將略過該步驟,並省略每個片段中的selectedFields
variationsFilters
物件
選擇性。
調整變數下拉式清單(不是主要清單 — 使用篩選器)。 今天僅支援狀態,並以「PUBLISHED」作為支援的值(例如{ status: [“PUBLISHED”] })。 其他鍵會被忽略。 省略Prop以顯示所有變數。
rememberState
布林值
false
true時,選擇器會將使用者的作用中篩選器、儲存的搜尋和上次使用的存放庫儲存到IndexedDB,並在下次載入時自動將其復原。 選擇加入 — 現有消費者在省略時不需要變更。
amsRepositories
陣列<{ label: string; value: string; orgId?: string }>
要包含在存放庫選擇器中的AMS存放庫的可選清單。 這些會與探索服務的雲端存放庫串連。 每個專案都可包含多組織使用者的選用orgId。 省略時,會使用頂層orgId prop,然後進行Adobe IMS查閱。 AMS repos一律使用原始imsToken (無雲端權杖交換)。 受限於也提供該prop時的allowedRepositoryIds篩選。

ImsAuthProps屬性 imsauthprops-properties

ImsAuthProps屬性定義內容片段選擇器用來取得imsToken的驗證資訊和流程。 藉由設定這些屬性,您可以控制驗證流程應該如何行為並註冊各種驗證事件的接聽程式。

屬性名稱
說明
imsClientId
代表用於驗證目的之IMS使用者端ID的字串值。 此值由Adobe提供,且為您的Adobe AEM CS組織專用。
imsScope
說明用於驗證的範圍。 範圍會決定應用程式對貴組織資源的存取層級。 多個範圍可以用逗號分隔。
redirectUrl
代表驗證後重新導向使用者的URL。 此值通常設定為應用程式目前的URL。 如果未提供redirectUrlImsAuthService將使用用來登入imsClientId的redirectUrl
modalMode
表示驗證流程是否應該顯示在強制回應視窗(快顯視窗)中的布林值。 如果設為true,驗證流程會以快顯視窗顯示。 如果設為false,則驗證流程會以全頁重新載入顯示。 _Note :_若要獲得較好的UX,您可以在使用者停用瀏覽器快顯視窗時動態控制此值。
onImsServiceInitialized
Adobe IMS驗證服務初始化時呼叫的回呼函式。 此函式接受一個引數service,此引數是代表Adobe IMS服務的物件。 如需詳細資訊,請參閱ImsAuthService
onAccessTokenReceived
從Adobe IMS驗證服務收到imsToken時所呼叫的回呼函式。 此函式接受一個引數imsToken,該引數是代表存取權杖的字串。
onAccessTokenExpired
當存取權杖過期時所呼叫的回呼函式。 此函式通常用於觸發新的驗證流程,以取得新的存取權杖。
onErrorReceived
驗證期間發生錯誤時所呼叫的回呼函式。 此函式採用兩個引數:錯誤型別和錯誤訊息。 錯誤型別是代表錯誤型別的字串,而錯誤訊息是代表錯誤訊息的字串。

ImsAuthService屬性 imsauthservice-properties

ImsAuthService類別會處理內容片段選擇器的驗證流程。 其負責從Adobe IMS驗證服務取得imsTokenimsToken用於驗證使用者並授權存取Adobe Experience Manager (AEM) CS存放庫。 ImsAuthService使用ImsAuthProps屬性來控制驗證流程並註冊各種驗證事件的接聽程式。 您可以使用方便的registerContentFragmentSelectorAuthService函式向內容片段選取器註冊ImsAuthService執行個體。 ImsAuthService類別上有以下可用函式。 不過,如果您使用registerContentFragmentSelectorAuthService函式,則不需要直接呼叫這些函式。

函式名稱
說明
isSignedInUser
判斷使用者目前是否已登入服務並據此傳回布林值。
getImsToken
擷取目前登入使用者的驗證imsToken,該驗證可用於驗證其他服務的請求,例如產生資產轉譯。
signIn
起始使用者的登入程式。 此函式使用ImsAuthProps在快顯視窗或整頁重新載入中顯示驗證。
signOut
將使用者登出服務,讓其驗證Token失效,並要求他們再次登入以存取受保護的資源。 叫用此函式將會重新載入目前頁面。
refreshToken
重新整理目前登入使用者的驗證Token,避免其到期並確保受保護資源的存取不中斷。 傳回可用於後續請求的新驗證Token。

ContentFragmentSelection型別 contentfragmentselection-type

ContentFragmentSelection型別代表使用者選取片段時,內容片段選擇器傳回的內容片段結構。

型別定義 type-definitions

Contentfragmentselection contentfragmentselection

type ContentFragmentSelection = {
    id: string;
    path: string;
    title: string;
    model: ContentFragmentModel;
    variations: string[];
    status: string;
    publishedBy: string;
    publishedByFullName: string;
    publishedDate: number | undefined;
    modifiedBy: string;
    modifiedByFullName: string;
    modifiedDate: number;
    createdBy: string;
    createdByFullName: string;
    createdDate: number;
    selectedFields?: Record<string, unknown>;
    selectedTemplateId?: string | null;
}[];

Contentfragmentmodel

type ContentFragmentModel = {
    name: string;
    id: string;
    path?: string;
    tagIds?: string[];
};

屬性 properties

ContentFragmentSelection屬性 contentfragmentselection-properties

屬性
類型
必要
說明
id
字串
內容片段的唯一識別碼
path
字串
DAM中片段的完整路徑(例如,/content/dam/my-project/article-fragment
title
字串
顯示內容片段的標題
model
Contentfragmentmodel
完整內容片段模式資訊
variations
字串[]
此片段可用的變數名稱陣列(例如,["master", "mobile", "tablet"]
status
字串
片段的發佈狀態(例如,「已發佈」、「已修改」、「草稿」、「新增」、「已取消發佈」)
publishedBy
字串
發佈片段之使用者的電子郵件/使用者名稱
publishedByFullName
字串
發佈片段的使用者全名
publishedDate
數字
未定義
modifiedBy
字串
上次修改片段之使用者的電子郵件/使用者名稱
modifiedByFullName
字串
上次修改片段之使用者的全名
modifiedDate
數字
上次修改片段的時間戳記(毫秒)
createdBy
字串
建立片段之使用者的電子郵件/使用者名稱
createdByFullName
字串
建立片段的使用者全名
createdDate
數字
建立片段時的時間戳記(毫秒)
selectedFields
Record<string, unknown>
針對使用者在欄位選取步驟中選取的欄位,欄位名稱→欄位值的對應。 索引鍵是欄位名稱;值反映基礎ContentFragmentField["values"]陣列 — 也就是每個值都是原語模組(string[]boolean[]number[]、…),其元素型別取決於欄位的模型型別。 僅當選擇器以selectFields={true} ​開啟時出現,使用者為此片段選取了至少一個欄位;否則,將省略。
selectedTemplateId
string | null
在快速詳細資料面板的範本選擇器(上游@aem-sites/fragment-selector)中為此片段選擇的HTML範本識別碼。 null表示已明確選取一般(預設)範本 — 轉送的實際選取專案。 未選擇任何專案時,索引鍵是​完全省略 (例如,從未開啟此片段的範本選擇器,或是關閉選擇器的上游功能切換)。

ContentFragmentModel屬性 contentfragmentmodel-properties

屬性
類型
必要
說明
name
字串
內容片段模型的顯示名稱
id
字串
適用於模式的唯一識別碼
path
字串
模型定義的完整路徑(例如,/conf/my-project/settings/dam/cfm/models/article
tagIds
字串[]
與模型相關聯的標籤ID陣列

使用範例 example-usage

基本範例 basic-example

PureJSContentFragmentSelectors.renderContentFragmentSelectorWithAuthFlow(
    container,
    {
        orgId: "YOUR_ORG_ID@AdobeOrg",
        onSubmit: ({ contentFragments, domainName, repoId }) => {
            // contentFragments is of type ContentFragmentSelection
            contentFragments.forEach(fragment => {
                console.log('Fragment ID:', fragment.id);
                console.log('Fragment Path:', fragment.path);
                console.log('Fragment Title:', fragment.title);
                console.log('Model Name:', fragment.model?.name);
                console.log('Model Path:', fragment.model?.path);
                console.log('Variations:', fragment.variations);
                console.log('Status:', fragment.status);
                console.log('Published By:', fragment.publishedBy);
                console.log('Published By Full Name:', fragment.publishedByFullName);
                console.log('Published Date:', new Date(fragment.publishedDate));
                console.log('Modified By:', fragment.modifiedBy);
                console.log('Modified By Full Name:', fragment.modifiedByFullName);
                console.log('Modified Date:', new Date(fragment.modifiedDate));
                console.log('Created By:', fragment.createdBy);
                console.log('Created By Full Name:', fragment.createdByFullName);
                console.log('Created Date:', new Date(fragment.createdDate));
                // Only present when the selector was opened with `selectFields={true}`
                // and the user picked at least one field for this fragment.
                if (fragment.selectedFields) {
                    console.log('Selected Fields:', fragment.selectedFields);
                }
                // Only present when a template was chosen in the Quick Details panel;
                // `null` means the generic (default) template was picked.
                if (fragment.selectedTemplateId !== undefined) {
                    console.log('Selected Template Id:', fragment.selectedTemplateId);
                }
            });
        }
    }
);

完成範例回應 complete-example-response

{
    contentFragments: [
        {
            id: "fragment-uuid-123",
            path: "/content/dam/my-project/article-fragment",
            title: "My Article Fragment",
            model: {
                name: "Article",
                id: "model-id-456",
                path: "/conf/my-project/settings/dam/cfm/models/article",
                tagIds: ["tag:product", "tag:news"]
            },
            variations: ["master", "mobile", "tablet"],
            status: "PUBLISHED",
            publishedBy: "user@adobetest.com",
            publishedByFullName: "John Doe",
            publishedDate: 1765728541321,
            modifiedBy: "editor@adobe.com",
            modifiedByFullName: "Jane Editor",
            modifiedDate: 1765728541320,
            createdBy: "abc12345@adobe.com",
            createdByFullName: "Peter Editor",
            createdDate: 1754035541525,
            // Returned per-fragment when the selector was opened with
            // `selectFields={true}` and the user picked fields for it.
            // Each value mirrors the underlying ContentFragmentField["values"]
            // array — usually a single-element array of the field's primitive
            // type. Multi-valued fields contain multiple entries.
            selectedFields: {
                title: ["My Article Fragment"],
                body: ["Lorem ipsum dolor sit amet…"],
                featured: [true]
            },
            // Returned per-fragment when a template was chosen in the Quick
            // Details panel. `null` means the generic (default) template;
            // omitted entirely when no template was chosen.
            selectedTemplateId: "template-abc-123"
        },
        {
            id: "fragment-uuid-789",
            path: "/content/dam/my-project/blog-post",
            title: "Sample Blog Post",
            model: {
                name: "Blog Post",
                id: "model-id-789",
                path: "/conf/my-project/settings/dam/cfm/models/blog-post",
                tagIds: ["tag:blog"]
            },
            variations: ["master"],
            status: "MODIFIED",
            publishedBy: "user@adobe.com",
            publishedByFullName: "John Doe",
            publishedDate: 1765728541321,
            modifiedBy: "admin@adobe.com",
            modifiedByFullName: "Admin User",
            modifiedDate: 1765728541322,
            createdBy: "admin@adobe.com",
            createdByFullName: "Admin User",
            createdDate: 1754035541525
        }
    ],
    domainName: "author-pXXXXX-eYYYYY.adobeaemcloud.com",
    repoId: "repository-id",
    tenantInfo: "tenant-info"
}

TypeScript整合 typescript-integration

如果您使用TypeScript,則可以從封裝匯入型別:

import type {
    ContentFragmentSelection,
    ContentFragmentModel
} from '@aem-sites/content-fragment-selector';

// Use in your code
const handleSubmit = (data: {
    contentFragments: ContentFragmentSelection
}) => {
    // TypeScript will provide full type checking
    data.contentFragments.forEach(fragment => {
        const title: string = fragment.title;
        const modelName: string = fragment.model.name;
    });
};

Source程式碼參考 source-code-reference

可以在原始程式碼中找到完整的型別定義:

recommendation-more-help
experience-manager-cloud-service-help-main-toc