本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 品牌编辑器与自定义托管登录
<a name="managed-login-brandingeditor"></a>

品牌编辑器是托管登录网页的可视化设计和编辑工具。该工具已内置到 Amazon Cognito 控制台中。在品牌编辑器中，您首先会看到登录页面的预览，并可选择进入快速设置选项，或包含高级选项的详细视图。您可以修改和预览样式参数或添加自定义背景图像和徽标。您还可以配置浅色模式和深色模式。

![\[Amazon Cognito 用户池品牌编辑器可视化编辑器的预览图。\]](http://docs.amazonaws.cn/cognito/latest/developerguide/images/hosted-ui-customization-editor-preview.png)


首先，创建一种可以应用于用户池或应用程序客户端的样式。

**开始使用品牌编辑器**

1. 在**域**选项卡中[创建域](cognito-user-pools-assign-domain.md)，或者更新现有域。在**品牌版本**下，将您的域设置为使用**托管登录**。

1. 如有任何现有应用程序客户端样式，则将其删除。

   1. 在**应用程序客户端**菜单中，选择您的应用程序客户端。

   1. 在**托管登录样式**下，选择分配给您的应用程序客户端的样式。

   1. 选择**删除样式**。确认您的选择。

1. 导航到用户池中的**托管登录**菜单。如果您没有此功能，请按照提示选择一个包含托管登录的[功能计划](cognito-sign-in-feature-plans.md)。如果您只想查看品牌编辑器而不进行任何更改，也可以选择**预览此功能**。

1. 在**样式**下，选择**创建样式**。

1. 选择要为其分配样式的应用程序客户端，然后选择**创建**。您还可以新建应用程序客户端。

1. Amazon Cognito 控制台将启动品牌编辑器。

1. 选择要开始编辑的选项卡，或者选择**启动编辑器**并进入[快速设置](#branding-designer-quick-setup)。可以看到以下选项卡：  
**预览**  
查看您当前的选择在托管登录页面中的实际效果。  
**基础**  
设置整体主题，配置指向外部身份提供者的链接，并设置表单字段的样式。  
**组件**  
配置页眉、页脚及各个 UI 元素的样式。

1. 要选择初始设置，请进入快速设置。选择**更改设置类别**，然后选择**快速设置**。选择**继续**后，品牌编辑器将启动，其中包含一组可配置的基本选项。

## 文本和本地化
<a name="branding-designer-loc"></a>

您无法在品牌编辑器中修改或本地化文本。请改为在分发给用户的 URL 中添加 `lang` 查询参数。此参数会使您的托管登录页面本地化为多种可用语言之一。有关更多信息，请参阅 [托管登录本地化](cognito-user-pools-managed-login.md#managed-login-localization)。

## 快速设置
<a name="branding-designer-quick-setup"></a>

**启动品牌编辑器**按钮会加载一个可视化编辑器，用于配置您的托管登录页面，您可在其中选择多种主要自定义选项。在您进行选择时，Amazon Cognito 会在预览窗口中呈现托管登录页面的更改。要返回详细设置菜单，请选择**更改设置类别**按钮。

**整体外观和风格应该如何？**  
为托管登录页面配置基本主题设置。    
**显示模式**  
为托管登录选择浅色模式、深色模式或自适应体验。自适应设置会在 Amazon Cognito 呈现托管登录页面时，遵循用户的浏览器偏好。当您选择浏览器自适应模式时，可以为浅色模式和深色模式选择不同的颜色和徽标图像。  
**Spacing**  
设置页面中元素之间的默认间距。  
**边框圆角**  
设置元素外边框的圆角程度。

**页面背景应呈现什么效果？**    
**背景类型**  
**显示图像**复选框用于指定您是希望使用背景图像，还是设置纯色背景。  

1. 要使用图像，请选择**显示图像**，然后为浅色模式和深色模式分别选择背景图像。您还可以为图像未覆盖的背景区域分别设置深色模式和浅色模式的**页面背景颜色**。

1. 要使用纯色背景，请取消选择**显示图像**，然后选择浅色模式和深色模式的**页面背景颜色**。

**表单应呈现什么效果？**  
为托管登录的表单元素配置设置。表单项的示例包括登录和验证码提示。    
**水平对齐**  
设置表单字段的水平对齐方式。  
**表单徽标**  
设置徽标图像的位置。  
**徽标图像**  
选择要包含在浅色和深色模式的表单元素中的徽标图像文件。要上传图像，请选择**徽标图像**下拉列表，选择**添加新资产**，然后添加徽标文件。  
**主要品牌颜色**  
为浅色模式和深色模式设置主题颜色。此颜色将作为背景色应用于所有归类为主要元素的元素。

**页眉应呈现什么效果？**  
选择是否要在托管登录页面中添加页眉。页眉可以包含徽标图像。    
**页眉徽标**  
设置徽标图像在页眉中的位置。  
**徽标图像**  
选择徽标位置，以及要添加在页眉中的徽标图像文件。要上传图像，请选择**徽标图像**下拉列表，选择**添加新资产**，然后添加徽标文件。  
**页眉背景颜色**  
为页眉的背景设置浅色模式和深色模式颜色。

## 详细设置
<a name="branding-designer-advanced"></a>

在详细设置视图中，您可以修改**基础**和**组件**中的各个组件。**预览**选项卡会根据当前上下文和您的自定义设置，显示托管登录页面的预览效果。

![\[托管登录组件详细配置的 Amazon Web Services 管理控制台 屏幕截图。\]](http://docs.amazonaws.cn/cognito/latest/developerguide/images/hosted-ui-customization-console-preview.png)


要进入组件的可视化编辑器，请在组件对应的磁贴中选择编辑图标。在主题 Studio 编辑器中，您可以使用**更改设置类别**按钮在组件之间切换。

### 基础
<a name="branding-designer-advanced-foundation"></a>

**应用程序样式**  
配置托管登录的基本设置。此类别包含整体主题、文本间距以及页眉和页脚的设置。

**显示模式**  
为托管登录页面选择浅色模式、深色模式或自适应体验。当您选择浏览器自适应模式时，可以为浅色模式和深色模式选择不同的颜色和徽标图像。

**Spacing**  
设置页面中元素之间的默认间距。

**身份验证行为**  
为将您的用户连接到外部身份提供商的按钮配置样式（IdPs）。本节包含**域搜索输入**选项，启用后，托管登录会提示用户输入电子邮件地址，并将其与对应的 [SAML 身份提供者标识符](cognito-user-pools-managing-saml-idp-naming.md)进行匹配。

**表单行为**  
配置输入表单的样式：输入的位置、颜色和元素的对齐方式。

### 组件
<a name="branding-designer-advanced-components"></a>

**按钮**  
Amazon Cognito 在托管登录页面上呈现的按钮样式。

**分隔线**  
托管登录元素之间分隔线和边界的样式，例如输入表单与外部提供商登录选择器之间的分隔。

**下拉菜单**  
下拉菜单的样式。

**网页图标**  
Amazon Cognito 为选项卡和书签图标提供的图像的样式。

**焦点环**  
当前选中输入框的高亮样式。

**表单容器**  
包围表单的元素的样式。

**全局页脚**  
Amazon Cognito 在托管登录页面底部显示的页脚样式。

**全局页眉**  
Amazon Cognito 在托管登录页面顶部显示的页眉样式。

**指示**  
错误和成功消息的样式。

**选项控件**  
复选框、多选框和其他输入提示的样式。

**页面背景**  
托管登录页面整体背景的样式。

**输入**  
表单字段输入提示的样式。

**Link**  
托管登录页面中超链接的样式。

**页面文本**  
页内文本的样式。

**字段文本**  
表单输入框周围文本的样式。

## 托管登录品牌的 API 和 SDK 操作
<a name="branding-designer-api"></a>

您还可以使用 API 操作[CreateManagedLoginBranding](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html)和将品牌应用于托管登录风格[UpdateManagedLoginBranding](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_UpdateManagedLoginBranding.html)。这些操作非常适合为另一个应用程序客户端或用户池创建完全相同或稍作修改版的品牌样式。使用 API 操作查询现有样式的托管登录品牌 [DescribeManagedLoginBranding](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_DescribeManagedLoginBranding.html)，然后根据需要修改输出并将其应用于其他资源。

`UpdateManagedLoginBranding` 操作不会更改您的样式应用到的应用程序客户端。它仅会更新分配给应用程序客户端的现有样式。要完全替换应用程序客户端的样式，请删除现有样式，[DeleteManagedLoginBranding](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_DeleteManagedLoginBranding.html)然后使用指定新样式`CreateManagedLoginBranding`。在 Amazon Cognito 控制台中，情况也是如此：必须先删除现有样式，然后创建新样式。

在 API 或 SDK 请求中设置托管登录品牌时，需要将您的设置嵌入到一个 JSON 文件中，并将该文件转换为 `Document` 数据类型。下面提供了关于可添加的图像以及如何生成编程式请求以配置品牌样式的指导。

### 图像资产
<a name="branding-designer-api-assets"></a>

[CreateManagedLoginBranding](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html)并[UpdateManagedLoginBranding](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_UpdateManagedLoginBranding.html)包括一个`Assets`参数。该参数是一个采用 base64 编码二进制格式的图像文件数组。

**注意**  
对于通过编程方式创建或更新品牌样式的请求，请求大小不得超过 2 MB。您请求中的资产可能会使请求超过此限制。如果是这种情况，请将其拆分为多个 `UpdateManagedLoginBranding` 请求，每组参数的大小均不超过最大请求限制。这些部分更新请求不会将未指定的参数重置为默认值，因此您可以安全地发送它们，而不会影响现有的设置。

有些资产对您可提交的文件类型有限制。


****  

| 资产 | 接受的文件扩展名 | 
| --- | --- | 
| FAVICON\$1ICO | ico | 
| FAVICON\$1SVG | svg | 
| EMAIL\$1GRAPHIC | png、svg、jpeg | 
| SMS\$1GRAPHIC | png、svg、jpeg | 
| AUTH\$1APP\$1GRAPHIC | png、svg、jpeg | 
| PASSWORD\$1GRAPHIC | png、svg、jpeg | 
| PASSKEY\$1GRAPHIC | png、svg、jpeg | 
| PAGE\$1HEADER\$1LOGO | png、svg、jpeg | 
| PAGE\$1HEADER\$1BACKGROUND | png、svg、jpeg | 
| PAGE\$1FOOTER\$1LOGO | png、svg、jpeg | 
| PAGE\$1FOOTER\$1BACKGROUND | png、svg、jpeg | 
| PAGE\$1BACKGROUND | png、svg、jpeg | 
| FORM\$1BACKGROUND | png、svg、jpeg | 
| FORM\$1LOGO | png、svg、jpeg | 
| IDP\$1BUTTON\$1ICON | ico、svg | 

SVG 类型的文件支持以下属性和元素。

------
#### [ Attributes ]

```
accent-height, accumulate, additivive, alignment-baseline, ascent, attributename, attributetype, azimuth, basefrequency, baseline-shift, begin, bias, by, class, clip, clip-path, clip-rule, color, color-interpolation, color-interpolation-filters, color-profile, color-rendering, cx, cy, d, dx, dy, diffuseconstant, direction, display, divisor, dur, edgemode, elevation, end, fill, fill-opacity, fill-rule, filter, filterunits, flood-color, flood-opacity, font-family, font-size, font-size-adjust, font-stretch, font-style, font-variant, font-weight, fx, fy, g1, g2, glyph-name, glyphref, gradientunits, gradienttransform, height, href, id, image-rendering, in, in2, k, k1, k2, k3, k4, kerning, keypoints, keysplines, keytimes, lang, lengthadjust, letter-spacing, kernelmatrix, kernelunitlength, lighting-color, local, marker-end, marker-mid, marker-start, markerheight, markerunits, markerwidth, maskcontentunits, maskunits, max, mask, media, method, mode, min, name, numoctaves, offset, operator, opacity, order, orient, orientation, origin, overflow, paint-order, path, pathlength, patterncontentunits, patterntransform, patternunits, points, preservealpha, preserveaspectratio, r, rx, ry, radius, refx, refy, repeatcount, repeatdur, restart, result, rotate, scale, seed, shape-rendering, specularconstant, specularexponent, spreadmethod, stddeviation, stitchtiles, stop-color, stop-opacity, stroke-dasharray, stroke-dashoffset, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-opacity, stroke, stroke-width, style, surfacescale, tabindex, targetx, targety, transform, text-anchor, text-decoration, text-rendering, textlength, type, u1, u2, unicode, values, viewbox, visibility, vert-adv-y, vert-origin-x, vert-origin-y, width, word-spacing, wrap, writing-mode, xchannelselector, ychannelselector, x, x1, x2, xmlns, y, y1, y2, z, zoomandpan
```

------
#### [ Elements ]

```
svg, a, altglyph, altglyphdef, altglyphitem, animatecolor, animatemotion, animatetransform, audio, canvas, circle, clippath, defs, desc, ellipse, filter, font, g, glyph, glyphref, hkern, image, line, lineargradient, marker, mask, metadata, mpath, path, pattern, polygon, polyline, radialgradient, rect, stop, style, switch, symbol, text, textpath, title, tref, tspan, video, view, vkern, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDistantLight, feFlood, feFuncA, feFuncB, feFuncG, feFuncR, feGaussianBlur, feMerge, feMergeNode, feMorphology, feOffset, fePointLight, feSpecularLighting, feSpotLight, feTile, feTurbulence
```

------

### 托管登录品牌操作的工具
<a name="branding-designer-api-tools"></a>

对于托管登录品牌设置对象，Amazon Cognito 管理有一个 [JSON Schema 格式](https://json-schema.org/docs)的文件。以下是以编程方式更新品牌样式的步骤。

**在用户池 API 中更新品牌**

1. 在 Amazon Cognito 控制台中，从用户池的**托管登录**菜单中创建默认的托管登录品牌样式。将其分配给应用程序客户端。

1. 记录您为其创建样式的应用程序客户端的 ID，例如 `1example23456789`。

1. 使用设置为的 [DescribeManagedLoginBrandingByClient](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_DescribeManagedLoginBrandingByClient.html)API 请求检索品牌风格的`ReturnMergedResources`设置`true`。以下是一个示例 请求正文。

   ```
   {
      "ClientId": "1example23456789",
      "ReturnMergedResources": true,
      "UserPoolId": "us-east-1_EXAMPLE"
   }
   ```

1. 使用您的自定义设置修改 `DescribeManagedLoginBrandingByClient` 的输出。

   1. 响应正文包裹在一个 `ManagedLoginBranding` 元素中，该元素不属于创建和更新操作的语法部分。需要移除这个 JSON 对象的顶层结构。

   1. 要替换图像，请将 `Bytes` 值替换为每个图像文件的 Base64 编码二进制数据。

   1. 要更新设置，请修改 `Settings` 对象的输出，并将其包含在下一次请求中。Amazon Cognito 会忽略 `Settings` 对象中任何未包含在 API 响应所返回的架构中的值。

1. 在[CreateManagedLoginBranding](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html)或[UpdateManagedLoginBranding](https://docs.amazonaws.cn/)请求中使用更新的响应正文。如果请求大小超过 2 MB，请将其拆分为多个请求。这些操作采用 `PATCH` 模式，除非您另行指定，否则原始设置将保持不变。