自定义外观样式

2026-06-26 19:29

使用 appearance 参数自定义支付界面的视觉样式和布局，包括主题选择、布局配置和 CSS 样式自定义。

Web/WAP

iOS

Android

Flutter

首先，选择一个主题。
立即开始使用预构建的主题，选择与您的网站或应用程序最相似的主题。
选择您偏好的布局模式。
从 Accordion 和 Tab 两种布局模式中进行选择。

使用 CSS 对组件进行精细化调整。
如有需要，可以为 Payment Element 中的单个组件指定自定义 CSS 属性。

定制卡品牌样式。
如有需要，可以通过 card 参数配置是否展示卡品牌。

以下是使用 appearance 参数配置界面样式的示例代码：

// 对于 npm 用户 (TypeScript)，请导入枚举。如果是 CDN 或仅使用 JavaScript，请省略此导入
import { AMSElement, ThemeType, PaymentElementLayout } from '@alipay/ams-checkout';

// 选项 1：使用字符串值 (CDN、npm/JavaScript, 或 npm/TypeScript)
elementPayment.mount({
type: 'payment',
appearance: {
  theme: 'night', // 字符串值
  layout: { type: 'accordion' }, // 字符串值
  variables: { ... },
  card: {
		showBrandIcon: false
	}
}
}, '#payment-element');

/*
选项 2：使用枚举（仅适用于 npm 和 TypeScript）
*/
// elementPayment.mount({
//   type: 'payment',
//   appearance: {
//     theme: ThemeType.Night, // TypeScript 枚举
//     layout: { type: PaymentElementLayout.Accordion }, // TypeScript 枚举
//     variables: { ... },
//		 card: {
//  			showBrandIcon: false
//			}
//   }
// }, '#payment-element');

主题

Payment Element 为您提供 6 大预设主题。您可以使用 JavaScript（适用于 CDN 或 npm）或 TypeScript 枚举（仅适用于 npm）来配置 appearance 中的 theme 属性以选择主题。有效值为：

default
：默认主题（白天）
night
：暗黑
nostalgicGray
：怀旧灰
agateGreen
：玛瑙绿
cherryBlossomPink
：樱花粉
gamingPurple
：游戏紫

以下是各主题的界面效果及示例代码：

默认主题（白天）

暗黑

怀旧灰

玛瑙绿

樱花粉

游戏紫

以下是设置默认主题（白天）的示例代码：

appearance: { theme: 'default' }
// TypeScript 枚举: theme: ThemeType.Default

以下是设置暗黑主题的示例代码：

appearance: { theme: 'night' }
// TypeScript 枚举: theme: ThemeType.Night

以下是设置怀旧灰主题的示例代码：

appearance: { theme: 'nostalgicGray' }
// TypeScript 枚举: theme: ThemeType.NostalgicGray

以下是设置玛瑙绿主题的示例代码：

appearance: { theme: 'agateGreen' }
// TypeScript 枚举: theme: ThemeType.AgateGreen

以下是设置樱花粉主题的示例代码：

appearance: { theme: 'cherryBlossomPink' }
// TypeScript 枚举: theme: ThemeType.CherryBlossomPink

以下是设置游戏紫主题的示例代码：

appearance: { theme: 'gamingPurple' }
// TypeScript 枚举: theme: ThemeType.GamingPurple

布局

Payment Element 支持 Accordion（手风琴式）和 Tabs（标签页式）两种布局模式。您可以通过 JavaScript（适用于 CDN 或 npm）或 TypeScript 枚举（仅限 npm）来配置 appearance.layout 对象。有效值为：

accordion
：默认值。手风琴布局。将支付选项垂直堆叠为可折叠的章节，每个章节标题始终可见，点击后展开显示内容。

showRadio：布尔类型。默认值为
true
。用于控制手风琴布局的支付列表中是否显示单选按钮。

tabs
：标签页布局。将支付选项以水平标签页形式排列，点击标签切换内容。

以下是两种模式的界面效果及示例代码：

Accordion

Tabs

appearance: {
  layout: { type: 'accordion' },
  accordion: {
    showRadio: false  // 隐藏单选按钮，默认为 true
  }
}
// TypeScript 枚举: layout: { type: PaymentElementLayout.Accordion }

appearance: { 
layout: { type: 'tabs' } 
}
// TypeScript 枚举: layout: { type: PaymentElementLayout.Tabs }

CSS 变量

Payment Element 支持通过 CSS 对视觉组件进行精细化定制，包括对边框、背景、文本及图标等样式的配置。您需要通过 variables 参数传递 CSS 变量来进行样式自定义。

以下是支持的 CSS 变量及其默认值的参考列表。您可以根据品牌需求，在您的 CSS 代码中覆盖这些变量的值。

颜色变量

尺寸变量

颜色变量用于定义支付元素的整体视觉色彩体系，涵盖内容文字、背景、边框、操作及状态等维度。

内容颜色

背景颜色

边框颜色

操作按钮颜色

状态颜色

变量	默认值	描述	使用场景
content-primary	#2a3a52	主要内容文字颜色	标题、重要文本
content-secondary	#7c8ca3	次要内容文字颜色	描述文本、副标题
content-tertiary	#abb9cc	辅助文字颜色	提示信息、占位符
content-quaternary	#ffffff	反色文字颜色	深色背景上的文字

变量	默认值	描述	使用场景
background-primary	#ffffff	主背景色	页面主背景
background-secondary	#f9fafb	次背景色	卡片、模块背景
background-disable	#fcfcfc	禁用背景色	禁用状态背景
background-transparency	#0000000a	透明背景色	遮罩、浮层背景

变量	默认值	描述	使用场景
border-primary	#cfd8e5	主边框色	主要边框、分割线
border-secondary	#ebebeb	次边框色	次要边框、内部分割线
border-disable	#f5f5f5	禁用边框色	禁用状态的边框

变量	默认值	描述	使用场景
action-normal	#1650ff	按钮正常状态	主要操作按钮
action-hover	#5c85ff	按钮悬停状态	鼠标悬停效果
action-disable	#a2b9ff	按钮禁用状态	不可点击按钮
action-secondary	#f3f6ff	次要按钮背景	次要操作按钮

变量	默认值	描述	使用场景
state-failure	#ff5b4d	失败状态	错误提示、失败状态
state-warning	#ff9f1a	警告状态	警告提示、注意信息
state-success	#00b277	成功状态	成功提示、完成状态
state-info	#6092d8	信息状态	一般信息提示
state-marketing	#ff6060	营销状态	促销、活动提示
state-conventional	#7c8ca3	常规状态	一般、常规说明

尺寸变量规范了支付元素的形体与空间关系，包括圆角、间距及边框粗细的设置。

圆角设置

间距设置

边框粗细

变量	默认值	描述	使用场景
radius-backup	4px	备份圆角	小元素圆角
radius-module	12px	模块圆角	模块容器圆角
radius-component	8px	组件圆角	组件元素圆角
radius-button	12px	按钮圆角	按钮圆角

变量	默认值	描述	使用场景
wrapper-padding	24px	容器内边距	主容器内边距

变量	默认值	描述	使用场景
stroke-default	0.5px	容器未激活边框粗细	支付列表默认边框
stroke-active	1px	容器激活边框粗细	支付列表选中时边框

示例

const appearance = {
theme: "default",
layout: { type: "Accordion" },
variables: {
  "content-primary": "#2a3a52",
  "content-secondary": "#7c8ca3",
  "content-tertiary": "#abb9cc",
  "content-quaternary": "#ffffff",

  "background-primary": "#ffffff",
  "background-secondary": "#f9fafb",
  "background-disable": "#fcfcfc",
  "background-transparency": "#0000000a",

  "border-primary": "#cfd8e5",
  "border-secondary": "#ebebeb",
  "border-disable": "#f5f5f5",

  "action-normal": "#1650ff",
  "action-hover": "#5c85ff",
  "action-disable": "#a2b9ff",
  "action-secondary": "#f3f6ff",

  "state-failure": "#ff5b4d",
  "state-warning": "#ff9f1a",
  "state-success": "#00b277",
  "state-info": "#6092d8",
  "state-marketing": "#ff6060",
  "state-conventional": "#7c8ca3",

  "radius-backup": "4px",
  "radius-module": "12px",
  "radius-component": "8px",
  "radius-button": "12px",

  "wrapper-padding": "24px",

  "stroke-default": "0.5px",
  "stroke-active": "1px",
},
};

以下是对不同界面样式进行自定义的变量设置示意：

Accordion 布局模式

Tabs 布局模式

支付要素收集页面

卡支付相关页面

电子钱包支付页面

地址模块

弹窗

其他（虚拟账户）页面

定制卡品牌样式

在卡支付场景中，卡品牌图标的展示可能影响卡支付信息采集的视觉风格和交互体验。根据不同业务场景的 UI 规范或品牌统一性要求，您可能需要灵活控制是否在支付页面展示这些图标。例如，若希望简化界面元素、避免视觉干扰，或已自行集成卡品牌识别功能，则可选择隐藏默认图标；而在需要明确提示支持的卡品牌时，则可保持默认展示以提升买家的信任感。

通过 appearance 中的 card.showBrandIcon 参数，您可快速控制卡品牌图标的显隐，有效值为：

true
：默认值。支付页面展示卡品牌图标。
false
：支付页面仅保留纯文本输入区域，不展示任何卡品牌图标。

以下是使用 card.showBrandIcon 参数配置卡品牌展示的效果示意及示例代码：

展示卡品牌

不展示卡品牌

使用 card.showBrandIcon 参数的默认值或将其设为

true

以在支付页面展示卡品牌图标：

{
appearance: {
  card: {
    showBrandIcon: true
  }
}
}

将 card.showBrandIcon 参数设为

false

，支付页面仅保留纯文本输入区域，不展示任何卡品牌图标：

{
appearance: {
  card: {
    showBrandIcon: false
  }
}
}

首先，选择一个主题。
立即开始使用预构建的主题，选择与您的网站或应用程序最相似的主题。
选择您偏好的布局模式。
从 Accordion 和 Tab 两种布局模式中进行选择。

使用 CSS 对组件进行精细化调整。
如有需要，可以为 Payment Element 中的单个组件指定自定义 CSS 属性。

主题

Payment Element 为您提供 6 大预设主题。通过向 appearance 配置项传入一个包含 theme 属性的 JSON 字符串来选择主题。有效值为：

"default"
：默认主题（白天）
"night"
：暗黑
"nostalgicGray"
：怀旧灰
"agateGreen"
：玛瑙绿
"cherryBlossomPink"
：樱花粉
"gamingPurple"
：游戏紫

以下是各主题的界面效果及示例代码：

默认主题（白天）

暗黑

怀旧灰

玛瑙绿

樱花粉

游戏紫

以下是设置默认主题（白天）的示例代码：

AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// 需要将 JSON 转换为 JSON 字符串
//    {
//        "theme": "default"
//    }
// == >
//    @"{\"theme\": \"default\"}"

NSString *appearance = @"{\"theme\": \"default\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;

以下是设置暗黑主题的示例代码：

AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// 需要将 JSON 转换为 JSON 字符串
//    {
//        "theme": "night"
//    }
// == >
//    @"{\"theme\": \"night\"}"

NSString *appearance = @"{\"theme\": \"night\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;

以下是设置怀旧灰主题的示例代码：

AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// 需要将 JSON 转换为 JSON 字符串
//    {
//        "theme": "nostalgicGray"
//    }
// == >
//    @"{\"theme\": \"nostalgicGray\"}"

NSString *appearance = @"{\"theme\": \"nostalgicGray\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;

以下是设置玛瑙绿主题的示例代码：

AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// 需要将 JSON 转换为 JSON 字符串
//    {
//        "theme": "agateGreen"
//    }
// == >
//    @"{\"theme\": \"agateGreen\"}"

NSString *appearance = @"{\"theme\": \"agateGreen\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;

以下是设置樱花粉主题的示例代码：

AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// 需要将 JSON 转换为 JSON 字符串
//    {
//        "theme": "cherryBlossomPink"
//    }
// == >
//    @"{\"theme\": \"cherryBlossomPink\"}"

NSString *appearance = @"{\"theme\": \"cherryBlossomPink\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;

以下是设置游戏紫主题的示例代码：

AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// 需要将 JSON 转换为 JSON 字符串
//    {
//        "theme": "gamingPurple"
//    }
// == >
//    @"{\"theme\": \"gamingPurple\"}"

NSString *appearance = @"{\"theme\": \"gamingPurple\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;

布局

Payment Element 支持 Accordion（手风琴式）和 Tabs（标签页式）两种布局模式。您可以通过在 appearance 配置项的 JSON 字符串中定义 layout 对象的 type 属性来设置布局模式。有效值为：

"Accordion"
：默认值。手风琴布局。将支付选项垂直堆叠为可折叠的章节，每个章节标题始终可见，点击后展开显示内容。
"Tabs"
：标签页布局。将支付选项以水平标签页形式排列，点击标签切换内容。

以下是两种模式的界面效果及示例代码：

Accordion

Tabs

AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// 需要将 JSON 转换为 JSON 字符串
//    {
//        "theme": "default",
// 		  "layout": {
//            "type": "Accordion"
//        }
//    }
// == >
//    @"{\"theme\": \"default\",\"layout\": {\"type\": \"Accordion\"}}"

NSString *appearance = @"{\"them\": \"default\",\"layout\": {\"type\": \"Accordion\"}}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;

AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// 需要将 JSON 转换为 JSON 字符串
//    {
//        "theme": "default",
// 		  "layout": {
//            "type": "tabs"
//        }
//    }
// == >
//    @"{\"theme\": \"default\",\"layout\": {\"type\": \"tabs\"}}"

NSString *appearance = @"{\"theme\": \"default\",\"layout\": {\"type\": \"tabs\"}}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;

CSS 变量

以下是支持的 CSS 变量及其默认值的参考列表。您可以根据品牌需求，在您的 CSS 代码中覆盖这些变量的值。

颜色变量

尺寸变量

颜色变量用于定义支付元素的整体视觉色彩体系，涵盖内容文字、背景、边框、操作及状态等维度。

内容颜色

背景颜色

边框颜色

操作按钮颜色

状态颜色

变量	默认值	描述	使用场景
content-primary	#2a3a52	主要内容文字颜色	标题、重要文本
content-secondary	#7c8ca3	次要内容文字颜色	描述文本、副标题
content-tertiary	#abb9cc	辅助文字颜色	提示信息、占位符
content-quaternary	#ffffff	反色文字颜色	深色背景上的文字

变量	默认值	描述	使用场景
background-primary	#ffffff	主背景色	页面主背景
background-secondary	#f9fafb	次背景色	卡片、模块背景
background-disable	#fcfcfc	禁用背景色	禁用状态背景
background-transparency	#0000000a	透明背景色	遮罩、浮层背景

变量	默认值	描述	使用场景
border-primary	#cfd8e5	主边框色	主要边框、分割线
border-secondary	#ebebeb	次边框色	次要边框、内部分割线
border-disable	#f5f5f5	禁用边框色	禁用状态的边框

变量	默认值	描述	使用场景
action-normal	#1650ff	按钮正常状态	主要操作按钮
action-hover	#5c85ff	按钮悬停状态	鼠标悬停效果
action-disable	#a2b9ff	按钮禁用状态	不可点击按钮
action-secondary	#f3f6ff	次要按钮背景	次要操作按钮

变量	默认值	描述	使用场景
state-failure	#ff5b4d	失败状态	错误提示、失败状态
state-warning	#ff9f1a	警告状态	警告提示、注意信息
state-success	#00b277	成功状态	成功提示、完成状态
state-info	#6092d8	信息状态	一般信息提示
state-marketing	#ff6060	营销状态	促销、活动提示
state-conventional	#7c8ca3	常规状态	一般、常规说明

尺寸变量规范了支付元素的形体与空间关系，包括圆角、间距及边框粗细的设置。

圆角设置

间距设置

边框粗细

变量	默认值	描述	使用场景
radius-backup	4px	备份圆角	小元素圆角
radius-module	12px	模块圆角	模块容器圆角
radius-component	8px	组件圆角	组件元素圆角
radius-button	12px	按钮圆角	按钮圆角

变量	默认值	描述	使用场景
wrapper-padding	24px	容器内边距	主容器内边距

变量	默认值	描述	使用场景
stroke-default	0.5px	容器未激活边框粗细	支付列表默认边框
stroke-active	1px	容器激活边框粗细	支付列表选中时边框

示例

NSString *appearance = @"{\
\n  \"theme\": \"default\",\
\n  \"layout\": {\
\n    \"type\": \"Accordion\"\
\n  },\
\n  \"variables\": {\
\n    \"content-primary\": \"#2a3a52\",\
\n    \"content-secondary\": \"#7c8ca3\",\
\n    \"content-tertiary\": \"#abb9cc\",\
\n    \"content-quaternary\": \"#ffffff\",\
\n\
\n    \"background-primary\": \"#ffffff\",\
\n    \"background-secondary\": \"#f9fafb\",\
\n    \"background-disable\": \"#fcfcfc\",\
\n    \"background-transparency\": \"#0000000a\",\
\n\
\n    \"border-primary\": \"#cfd8e5\",\
\n    \"border-secondary\": \"#ebebeb\",\
\n    \"border-disable\": \"#f5f5f5\",\
\n\
\n    \"action-normal\": \"#1650ff\",\
\n    \"action-hover\": \"#5c85ff\",\
\n    \"action-disable\": \"#a2b9ff\",\
\n    \"action-secondary\": \"#f3f6ff\",\
\n\
\n    \"state-failure\": \"#ff5b4d\",\
\n    \"state-warning\": \"#ff9f1a\",\
\n    \"state-success\": \"#00b277\",\
\n    \"state-info\": \"#6092d8\",\
\n    \"state-marketing\": \"#ff6060\",\
\n    \"state-conventional\": \"#7c8ca3\",\
\n\
\n    \"radius-backup\": \"4px\",\
\n    \"radius-module\": \"12px\",\
\n    \"radius-component\": \"8px\",\
\n    \"radius-button\": \"12px\",\
\n\
\n    \"wrapper-padding\": \"24px\",\
\n\
\n    \"stroke-default\": \"0.5px\",\
\n    \"stroke-active\": \"1px\"\
\n  }\
\n}";

以下是对不同界面样式进行自定义的变量设置示意：

Accordion 布局模式

Tabs 布局模式

支付要素收集页面

卡支付相关页面

电子钱包支付页面

地址模块

弹窗

其他（虚拟账户）页面

首先，选择一个主题。
立即开始使用预构建的主题，选择与您的网站或应用程序最相似的主题。
选择您偏好的布局模式。
从 Accordion 和 Tab 两种布局模式中进行选择。

使用 CSS 对组件进行精细化调整。
如有需要，可以为 Payment Element 中的单个组件指定自定义 CSS 属性。

主题

Payment Element 为您提供 6 大预设主题。通过构造 JSON 字符串设置 appearance 配置对象的 theme 属性以选择主题。有效值为：

"default"
：默认主题（白天）
"night"
：暗黑
"nostalgicGray"
：怀旧灰
"agateGreen"
：玛瑙绿
"cherryBlossomPink"
：樱花粉
"gamingPurple"
：游戏紫

以下是各主题的界面效果及示例代码：

默认主题（白天）

暗黑

怀旧灰

玛瑙绿

樱花粉

游戏紫

以下是设置默认主题（白天）的示例代码：

AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"default\"}";
configuration.setOption("appearance", appearance);

以下是设置暗黑主题的示例代码：

AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"night\"}";
configuration.setOption("appearance", appearance);

以下是设置怀旧灰主题的示例代码：

AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"nostalgicGray\"}";
configuration.setOption("appearance", appearance);

以下是设置玛瑙绿主题的示例代码：

AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"agateGreen\"}";
configuration.setOption("appearance", appearance);

以下是设置樱花粉主题的示例代码：

AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"cherryBlossomPink\"}";
configuration.setOption("appearance", appearance);

以下是设置游戏紫主题的示例代码：

AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"gamingPurple\"}";
configuration.setOption("appearance", appearance);

布局

Payment Element 支持 Accordion（手风琴式）和 Tabs（标签页式）两种布局模式。通过构造 JSON 字符串，为 layout 对象的 type 字段指定一个有效值以设置布局。有效值为：

"Accordion"
：默认值。手风琴布局。将支付选项垂直堆叠为可折叠的章节，每个章节标题始终可见，点击后展开显示内容。
"Tabs"
：标签页布局。将支付选项以水平标签页形式排列，点击标签切换内容。

以下是两种模式的界面效果及示例代码：

Accordion

Tabs

AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"night\",\"layout\":{\"type":\"Accordion\"}}";
configuration.setOption("appearance", appearance);

AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme":\"night\",\"layout\":{\"type\":\"Tabs\"}}";
configuration.setOption("appearance", appearance);

CSS 变量

以下是支持的 CSS 变量及其默认值的参考列表。您可以根据品牌需求，在您的 CSS 代码中覆盖这些变量的值。

颜色变量

尺寸变量

颜色变量用于定义支付元素的整体视觉色彩体系，涵盖内容文字、背景、边框、操作及状态等维度。

内容颜色

背景颜色

边框颜色

操作按钮颜色

状态颜色

变量	默认值	描述	使用场景
content-primary	#2a3a52	主要内容文字颜色	标题、重要文本
content-secondary	#7c8ca3	次要内容文字颜色	描述文本、副标题
content-tertiary	#abb9cc	辅助文字颜色	提示信息、占位符
content-quaternary	#ffffff	反色文字颜色	深色背景上的文字

变量	默认值	描述	使用场景
background-primary	#ffffff	主背景色	页面主背景
background-secondary	#f9fafb	次背景色	卡片、模块背景
background-disable	#fcfcfc	禁用背景色	禁用状态背景
background-transparency	#0000000a	透明背景色	遮罩、浮层背景

变量	默认值	描述	使用场景
border-primary	#cfd8e5	主边框色	主要边框、分割线
border-secondary	#ebebeb	次边框色	次要边框、内部分割线
border-disable	#f5f5f5	禁用边框色	禁用状态的边框

变量	默认值	描述	使用场景
action-normal	#1650ff	按钮正常状态	主要操作按钮
action-hover	#5c85ff	按钮悬停状态	鼠标悬停效果
action-disable	#a2b9ff	按钮禁用状态	不可点击按钮
action-secondary	#f3f6ff	次要按钮背景	次要操作按钮

变量	默认值	描述	使用场景
state-failure	#ff5b4d	失败状态	错误提示、失败状态
state-warning	#ff9f1a	警告状态	警告提示、注意信息
state-success	#00b277	成功状态	成功提示、完成状态
state-info	#6092d8	信息状态	一般信息提示
state-marketing	#ff6060	营销状态	促销、活动提示
state-conventional	#7c8ca3	常规状态	一般、常规说明

尺寸变量规范了支付元素的形体与空间关系，包括圆角、间距及边框粗细的设置。

圆角设置

间距设置

边框粗细

变量	默认值	描述	使用场景
radius-backup	4px	备份圆角	小元素圆角
radius-module	12px	模块圆角	模块容器圆角
radius-component	8px	组件圆角	组件元素圆角
radius-button	12px	按钮圆角	按钮圆角

变量	默认值	描述	使用场景
wrapper-padding	24px	容器内边距	主容器内边距

变量	默认值	描述	使用场景
stroke-default	0.5px	容器未激活边框粗细	支付列表默认边框
stroke-active	1px	容器激活边框粗细	支付列表选中时边框

示例

String appearance =
"{\n" +
"  \"theme\": \"default\",\n" +
"  \"layout\": {\n" +
"    \"type\": \"Accordion\"\n" +
"  },\n" +
"  \"variables": {\n" +
"    \"content-primary\": \"#2a3a52\",\n" +
"    \"content-secondary\": \"#7c8ca3\",\n" +
"    \"content-tertiary\": \"#abb9cc\",\n" +
"    \"content-quaternary\": \"#ffffff\",\n" +
"\n" +
"    \"background-primary\": \"#ffffff\",\n" +
"    \"background-secondary\": \"#f9fafb\",\n" +
"    \"background-disable\": \"#fcfcfc\",\n" +
"    \"background-transparency\": \"#0000000a\",\n" +
"\n" +
"    \"border-primary\": \"#cfd8e5\",\n" +
"    \"border-secondary\": \"#ebebeb\",\n" +
"    \"border-disable\": \"#f5f5f5\",\n" +
"\n" +
"    \"action-normal\": \"#1650ff\",\n" +
"    \"action-hover\": \"#5c85ff\",\n" +
"    \"action-disable\": \"#a2b9ff\",\n" +
"    \"action-secondary\": \"#f3f6ff\",\n" +
"\n" +
"    \"state-failure\": \"#ff5b4d\",\n" +
"    \"state-warning\": \"#ff9f1a\",\n" +
"    \"state-success\": \"#00b277\",\n" +
"    \"state-info\": \"#6092d8\",\n" +
"    \"state-marketing\": \"#ff6060\",\n" +
"    \"state-conventional\": \"#7c8ca3\",\n" +
"\n" +
"    \"radius-backup\": \"4px\",\n" +
"    \"radius-module\": \"12px\",\n" +
"    \"radius-component\": \"8px\",\n" +
"    \"radius-button\": \"12px\",\n" +
"\n" +
"    \"wrapper-padding\": \"24px\",\n" +
"\n" +
"    \"stroke-default\": \"0.5px\",\n" +
"    \"stroke-active\": \"1px\"\n" +
"  }\n" +
"}";

以下是对不同界面样式进行自定义的变量设置示意：

Accordion 布局模式

Tabs 布局模式

支付要素收集页面

卡支付相关页面

电子钱包支付页面

地址模块

弹窗

其他（虚拟账户）页面

首先，选择一个主题。
立即开始使用预构建的主题，选择与您的网站或应用程序最相似的主题。
选择您偏好的布局模式。
从 Accordion 和 Tab 两种布局模式中进行选择。

使用 CSS 对组件进行精细化调整。
如有需要，可以为 Payment Element 中的单个组件指定自定义 CSS 属性。

主题

Payment Element 为您提供 6 大预设主题。通过构造 JSON 字符串设置 appearance 配置对象的 theme 属性以选择主题。有效值为：

"default"
：默认主题（白天）
"night"
：暗黑
"nostalgicGray"
：怀旧灰
"agateGreen"
：玛瑙绿
"cherryBlossomPink"
：樱花粉
"gamingPurple"
：游戏紫

以下是各主题的界面效果及示例代码：

默认主题（白天）

暗黑

怀旧灰

玛瑙绿

樱花粉

游戏紫

以下是设置默认主题（白天）的示例代码：

Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"default\"}",
};

以下是设置暗黑主题的示例代码：

Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"night\"}",
};

以下是设置怀旧灰主题的示例代码：

Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"nostalgicGray\"}",
};

以下是设置玛瑙绿主题的示例代码：

Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"agateGreen\"}",
};

以下是设置樱花粉主题的示例代码：

Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"cherryBlossomPink\"}",
};

以下是设置游戏紫主题的示例代码：

Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"gamingPurple\"}",
};

布局

"Accordion"
：默认值。手风琴布局。将支付选项垂直堆叠为可折叠的章节，每个章节标题始终可见，点击后展开显示内容。
"Tabs"
：标签页布局。将支付选项以水平标签页形式排列，点击标签切换内容。

以下是两种模式的界面效果及示例代码：

Accordion

Tabs

Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance":
"{\"theme\":\"night\",\"layout\":{\"type\":\"Accordion\"}}",
};

Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance":
"{\"theme\":\"night\",\"layout\":{\"type\":\"Tabs\"}}",
};

CSS 变量

以下是支持的 CSS 变量及其默认值的参考列表。您可以根据品牌需求，在您的 CSS 代码中覆盖这些变量的值。

颜色变量

尺寸变量

颜色变量用于定义支付元素的整体视觉色彩体系，涵盖内容文字、背景、边框、操作及状态等维度。

内容颜色

背景颜色

边框颜色

操作按钮颜色

状态颜色

变量	默认值	描述	使用场景
content-primary	#2a3a52	主要内容文字颜色	标题、重要文本
content-secondary	#7c8ca3	次要内容文字颜色	描述文本、副标题
content-tertiary	#abb9cc	辅助文字颜色	提示信息、占位符
content-quaternary	#ffffff	反色文字颜色	深色背景上的文字

变量	默认值	描述	使用场景
background-primary	#ffffff	主背景色	页面主背景
background-secondary	#f9fafb	次背景色	卡片、模块背景
background-disable	#fcfcfc	禁用背景色	禁用状态背景
background-transparency	#0000000a	透明背景色	遮罩、浮层背景

变量	默认值	描述	使用场景
border-primary	#cfd8e5	主边框色	主要边框、分割线
border-secondary	#ebebeb	次边框色	次要边框、内部分割线
border-disable	#f5f5f5	禁用边框色	禁用状态的边框

变量	默认值	描述	使用场景
action-normal	#1650ff	按钮正常状态	主要操作按钮
action-hover	#5c85ff	按钮悬停状态	鼠标悬停效果
action-disable	#a2b9ff	按钮禁用状态	不可点击按钮
action-secondary	#f3f6ff	次要按钮背景	次要操作按钮

变量	默认值	描述	使用场景
state-failure	#ff5b4d	失败状态	错误提示、失败状态
state-warning	#ff9f1a	警告状态	警告提示、注意信息
state-success	#00b277	成功状态	成功提示、完成状态
state-info	#6092d8	信息状态	一般信息提示
state-marketing	#ff6060	营销状态	促销、活动提示
state-conventional	#7c8ca3	常规状态	一般、常规说明

尺寸变量规范了支付元素的形体与空间关系，包括圆角、间距及边框粗细的设置。

圆角设置

间距设置

边框粗细

变量	默认值	描述	使用场景
radius-backup	4px	备份圆角	小元素圆角
radius-module	12px	模块圆角	模块容器圆角
radius-component	8px	组件圆角	组件元素圆角
radius-button	12px	按钮圆角	按钮圆角

变量	默认值	描述	使用场景
wrapper-padding	24px	容器内边距	主容器内边距

变量	默认值	描述	使用场景
stroke-default	0.5px	容器未激活边框粗细	支付列表默认边框
stroke-active	1px	容器激活边框粗细	支付列表选中时边框

示例

Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": """
{
"theme": "default",
"layout": {
  "type": "Accordion"
},
"variables": {
  "content-primary": "#2a3a52",
  "content-secondary": "#7c8ca3",
  "content-tertiary": "#abb9cc",
  "content-quaternary": "#ffffff",

  "background-primary": "#ffffff",
  "background-secondary": "#f9fafb",
  "background-disable": "#fcfcfc",
  "background-transparency": "#0000000a",

  "border-primary": "#cfd8e5",
  "border-secondary": "#ebebeb",
  "border-disable": "#f5f5f5",

  "action-normal": "#1650ff",
  "action-hover": "#5c85ff",
  "action-disable": "#a2b9ff",
  "action-secondary": "#f3f6ff",

  "state-failure": "#ff5b4d",
  "state-warning": "#ff9f1a",
  "state-success": "#00b277",
  "state-info": "#6092d8",
  "state-marketing": "#ff6060",
  "state-conventional": "#7c8ca3",

  "radius-backup": "4px",
  "radius-module": "12px",
  "radius-component": "8px",
  "radius-button": "12px",

  "wrapper-padding": "24px",

  "stroke-default": "0.5px",
  "stroke-active": "1px"
}
}
"""
};

以下是对不同界面样式进行自定义的变量设置示意：

Accordion 布局模式

Tabs 布局模式

支付要素收集页面

卡支付相关页面

电子钱包支付页面

地址模块

弹窗

其他（虚拟账户）页面