內容片段選擇器 - 相關屬性 content-fragment-selector-related-properties
微前端內容片段選擇器可讓您瀏覽或搜尋存放庫中的內容片段,並在您的應用程式中使用這些片段。
您可以使用以下屬性來自訂內容片段選擇器的呈現方式及其使用方式。
內容片段選擇器屬性 content-fragment-selector-properties
屬性
類型
必要
預設
說明
refFragmentSelectorRef
否
參考
ContentFragmentSelector執行個體,允許存取提供的功能,例如reload。apiKey字串
否
API金鑰已於
digitalData.page.attributes.apiKey回報給分析。 僅用於追蹤,不適用於資料API呼叫。 若未提供,則是從imsToken (client_id宣告)衍生而來,遞補為封裝預設值。imsToken字串
否
用於驗證的IMS權杖。 如果未提供,將起始IMS登入流程。
repoId字串
否
用於片段選擇器的存放庫ID。 提供後,選取器會自動連線至指定的存放庫,而存放庫下拉式清單會隱藏。 如果未提供,使用者可以從他們有權存取的可用存放庫清單中選取存放庫。
allowedRepositoryIds字串[]
否
在內容片段選擇器中篩選存放庫和內容片段的存放庫ID清單。 若提供存放庫ID,存放庫選擇器中只會顯示這些存放庫。 如果未提供或陣列為空,則使用者有權存取的所有存放庫都將可供使用。
defaultRepoId字串
否
顯示存放庫選擇器時,預設會選取的存放庫ID。 僅在未提供
repoId時使用。 如果設定repoId,則會隱藏存放庫選擇器,並忽略此值。orgId字串
否
用於驗證的組織ID。 如果未提供,使用者可以從他們有權存取的不同組織中選擇存放庫。 如果使用者無權存取任何存放庫或組織,則不會載入內容。
locale字串
否
“en-US”
地區設定。
env字串
否
部署環境。 檢視允許的環境名稱的
Env型別。filtersFragmentfilter
否
{ 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數字
否
當
selectionType為multiple時可選取的專案數上限。 若未指定,則允許無限制的選取。 不適用於單一選取模式。dialogSize“fullscreen"或"fullscreenTakeover”
否
fullscreen控制對話方塊大小的選用Prop。
runningInUnifiedShell布林值
否
DestinationSelector是在UnifiedShell下執行,還是獨立執行。
selectedFragmentsContentFragmentIdentifier[]
否
[]選擇器開啟時要預先選取的內容片段的初始選擇。
hipaaEnabled布林值
否
false指出是否已啟用HIPAA規範。
inventoryViewInventoryViewType
否
table要用於選擇器的詳細目錄預設檢視型別。
inventoryViewToggleEnabled布林值
否
false表示是否啟用庫存檢視切換,讓使用者在表格檢視和格線檢視之間切換。
selectFields布林值
否
false表示是否啟用欄位選取步驟。 當
true時,使用者會挑選要針對每個選取的片段公開哪些欄位,而選取的欄位會在onSelectionChange和onSubmit裝載上以每個片段selectedFields對應的形式傳回。 當false (預設)時,將略過該步驟,並省略每個片段中的selectedFields。variationsFilters物件
否
選擇性。
調整變數下拉式清單(不是主要清單 — 使用篩選器)。 今天僅支援狀態,並以「PUBLISHED」作為支援的值(例如{ status: [“PUBLISHED”] })。 其他鍵會被忽略。 省略Prop以顯示所有變數。
調整變數下拉式清單(不是主要清單 — 使用篩選器)。 今天僅支援狀態,並以「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。 如果未提供
redirectUrl,ImsAuthService將使用用來登入imsClientId的redirectUrlmodalMode表示驗證流程是否應該顯示在強制回應視窗(快顯視窗)中的布林值。 如果設為
true,驗證流程會以快顯視窗顯示。 如果設為false,則驗證流程會以全頁重新載入顯示。 _Note :_若要獲得較好的UX,您可以在使用者停用瀏覽器快顯視窗時動態控制此值。onImsServiceInitializedAdobe IMS驗證服務初始化時呼叫的回呼函式。 此函式接受一個引數
service,此引數是代表Adobe IMS服務的物件。 如需詳細資訊,請參閱ImsAuthService。onAccessTokenReceived從Adobe IMS驗證服務收到
imsToken時所呼叫的回呼函式。 此函式接受一個引數imsToken,該引數是代表存取權杖的字串。onAccessTokenExpired當存取權杖過期時所呼叫的回呼函式。 此函式通常用於觸發新的驗證流程,以取得新的存取權杖。
onErrorReceived驗證期間發生錯誤時所呼叫的回呼函式。 此函式採用兩個引數:錯誤型別和錯誤訊息。 錯誤型別是代表錯誤型別的字串,而錯誤訊息是代表錯誤訊息的字串。
ImsAuthService屬性 imsauthservice-properties
ImsAuthService類別會處理內容片段選擇器的驗證流程。 其負責從Adobe IMS驗證服務取得imsToken。 imsToken用於驗證使用者並授權存取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字串
是
顯示內容片段的標題
modelContentfragmentmodel
是
完整內容片段模式資訊
variations字串[]
是
此片段可用的變數名稱陣列(例如,
["master", "mobile", "tablet"])status字串
是
片段的發佈狀態(例如,「已發佈」、「已修改」、「草稿」、「新增」、「已取消發佈」)
publishedBy字串
是
發佈片段之使用者的電子郵件/使用者名稱
publishedByFullName字串
是
發佈片段的使用者全名
publishedDate數字
未定義
是
modifiedBy字串
是
上次修改片段之使用者的電子郵件/使用者名稱
modifiedByFullName字串
是
上次修改片段之使用者的全名
modifiedDate數字
是
上次修改片段的時間戳記(毫秒)
createdBy字串
是
建立片段之使用者的電子郵件/使用者名稱
createdByFullName字串
是
建立片段的使用者全名
createdDate數字
是
建立片段時的時間戳記(毫秒)
selectedFieldsRecord<string, unknown>否
針對使用者在欄位選取步驟中選取的欄位,欄位名稱→欄位值的對應。 索引鍵是欄位名稱;值反映基礎
ContentFragmentField["values"]陣列 — 也就是每個值都是原語模組(string[]、boolean[]、number[]、…),其元素型別取決於欄位的模型型別。 僅當選擇器以selectFields={true} 和開啟時出現,使用者為此片段選取了至少一個欄位;否則,將省略。selectedTemplateIdstring | 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
可以在原始程式碼中找到完整的型別定義:
- 位置:
packages/@aem-sites/content-fragment-selector/src/types/index.ts - 存放庫: sites-content-fragment-selector
相關資源 related-resources
recommendation-more-help
experience-manager-cloud-service-help-main-toc