Antom, leading provider of tailored payment solutions
Contact Us
Log In

自定义外观样式

使用 appearance 参数自定义支付界面的视觉样式和布局，包括主题选择、布局配置和 CSS 样式自定义。
Web/WAP
  1. 首先，选择一个主题。
    立即开始使用预构建的主题，选择与您的网站或应用程序最相似的主题。
  2. 选择您偏好的布局模式。
    从 Accordion 和 Tab 两种布局模式中进行选择。
  1. 使用 CSS 对组件进行精细化调整。
    如有需要，可以为 Payment Element 中的单个组件指定自定义 CSS 属性。
  1. 定制卡品牌样式。
    如有需要，可以通过 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
appearance: {
    layout: { type: 'accordion' },
    accordion: {
      showRadio: false  // 隐藏单选按钮，默认为 true
    }
  }
// TypeScript 枚举: layout: { type: PaymentElementLayout.Accordion }
Tabs
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;
    }
  }
}
iOS
  1. 首先，选择一个主题。
    立即开始使用预构建的主题，选择与您的网站或应用程序最相似的主题。
  2. 选择您偏好的布局模式。
    从 Accordion 和 Tab 两种布局模式中进行选择。
  1. 使用 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
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;
Tabs
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 代码中覆盖这些变量的值。
颜色变量
颜色变量用于定义支付元素的整体视觉色彩体系，涵盖内容文字、背景、边框、操作及状态等维度。
内容颜色
变量
默认值
描述
使用场景
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 布局模式
支付要素收集页面
卡支付相关页面
电子钱包支付页面
地址模块
弹窗
其他（虚拟账户）页面
Android
  1. 首先，选择一个主题。
    立即开始使用预构建的主题，选择与您的网站或应用程序最相似的主题。
  2. 选择您偏好的布局模式。
    从 Accordion 和 Tab 两种布局模式中进行选择。
  1. 使用 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
AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"night\",\"layout\":{\"type":\"Accordion\"}}";
configuration.setOption("appearance", appearance);
Tabs
AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme":\"night\",\"layout\":{\"type\":\"Tabs\"}}";
configuration.setOption("appearance", appearance);

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
容器激活边框粗细
支付列表选中时边框

示例

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 布局模式
支付要素收集页面
卡支付相关页面
电子钱包支付页面
地址模块
弹窗
其他（虚拟账户）页面
Flutter
  1. 首先，选择一个主题。
    立即开始使用预构建的主题，选择与您的网站或应用程序最相似的主题。
  2. 选择您偏好的布局模式。
    从 Accordion 和 Tab 两种布局模式中进行选择。
  1. 使用 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
Map<String, dynamic> amsPaymentElementConfiguration = {
  "appearance":
  "{\"theme\":\"night\",\"layout\":{\"type\":\"Accordion\"}}",
};
Tabs
Map<String, dynamic> amsPaymentElementConfiguration = {
  "appearance":
  "{\"theme\":\"night\",\"layout\":{\"type\":\"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
容器激活边框粗细
支付列表选中时边框

示例

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 布局模式
支付要素收集页面
卡支付相关页面
电子钱包支付页面
地址模块
弹窗
其他（虚拟账户）页面