自定义外观样式
使用 appearance 参数自定义支付界面的视觉样式和布局，包括主题选择、布局配置和 CSS 样式自定义。
Web/WAP
iOS
Android
Flutter
- 使用 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 代码中覆盖这些变量的值。
颜色变量
尺寸变量
颜色变量用于定义支付元素的整体视觉色彩体系，涵盖内容文字、背景、边框、操作及状态等维度。
内容颜色
背景颜色
边框颜色
操作按钮颜色
状态颜色
尺寸变量规范了支付元素的形体与空间关系，包括圆角、间距及边框粗细的设置。
圆角设置
间距设置
边框粗细
示例
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
}
}
}- 使用 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 变量
Payment Element 支持通过 CSS 对视觉组件进行精细化定制，包括对边框、背景、文本及图标等样式的配置。您需要通过 variables 参数传递 CSS 变量来进行样式自定义。
以下是支持的 CSS 变量及其默认值的参考列表。您可以根据品牌需求，在您的 CSS 代码中覆盖这些变量的值。
颜色变量
尺寸变量
颜色变量用于定义支付元素的整体视觉色彩体系，涵盖内容文字、背景、边框、操作及状态等维度。
内容颜色
背景颜色
边框颜色
操作按钮颜色
状态颜色
尺寸变量规范了支付元素的形体与空间关系，包括圆角、间距及边框粗细的设置。
圆角设置
间距设置
边框粗细
示例
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 布局模式
支付要素收集页面
卡支付相关页面
电子钱包支付页面
地址模块
弹窗
其他（虚拟账户）页面
- 使用 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 变量
Payment Element 支持通过 CSS 对视觉组件进行精细化定制，包括对边框、背景、文本及图标等样式的配置。您需要通过 variables 参数传递 CSS 变量来进行样式自定义。
以下是支持的 CSS 变量及其默认值的参考列表。您可以根据品牌需求，在您的 CSS 代码中覆盖这些变量的值。
颜色变量
尺寸变量
颜色变量用于定义支付元素的整体视觉色彩体系，涵盖内容文字、背景、边框、操作及状态等维度。
内容颜色
背景颜色
边框颜色
操作按钮颜色
状态颜色
尺寸变量规范了支付元素的形体与空间关系，包括圆角、间距及边框粗细的设置。
圆角设置
间距设置
边框粗细
示例
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 布局模式
支付要素收集页面
卡支付相关页面
电子钱包支付页面
地址模块
弹窗
其他（虚拟账户）页面
- 使用 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\"}",
};布局
Payment Element 支持 Accordion（手风琴式）和 Tabs（标签页式）两种布局模式。通过构造 JSON 字符串，为 layout 对象的 type 字段指定一个有效值以设置布局。有效值为：
- "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 变量
Payment Element 支持通过 CSS 对视觉组件进行精细化定制，包括对边框、背景、文本及图标等样式的配置。您需要通过 variables 参数传递 CSS 变量来进行样式自定义。
以下是支持的 CSS 变量及其默认值的参考列表。您可以根据品牌需求，在您的 CSS 代码中覆盖这些变量的值。
颜色变量
尺寸变量
颜色变量用于定义支付元素的整体视觉色彩体系，涵盖内容文字、背景、边框、操作及状态等维度。
内容颜色
背景颜色
边框颜色
操作按钮颜色
状态颜色
尺寸变量规范了支付元素的形体与空间关系，包括圆角、间距及边框粗细的设置。
圆角设置
间距设置
边框粗细
示例
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 布局模式
支付要素收集页面
卡支付相关页面
电子钱包支付页面
地址模块
弹窗
其他（虚拟账户）页面