内容片段选择器——相关属性 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
Record<字符串, 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
“浅色”或“深色”
片段选择器的主题。 默认情况下,它被设置为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 repo始终使用原始imsToken(无云令牌交换)。 遵守allowedRepositoryIds筛选(同时提供该prop)。

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
将用户签出服务,使其身份验证令牌失效,并要求他们再次登录以访问受保护的资源。 调用此函数将重新加载当前页面。
refreshToken
刷新当前登录用户的身份验证令牌,防止该令牌过期,并确保对受保护资源的访问不会中断。 返回可用于后续请求的新身份验证令牌。

内容片段选择类型 contentfragmentselection-type

ContentFragmentSelection类型表示当用户选择片段时,内容片段选择器返回的内容片段的结构。

类型定义 type-definitions

内容片段选择 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;
}[];

内容片段模型

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
内容片段模型
完整内容片段模型信息
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模板的ID。 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