tencent cloud

人脸核身

Android 自定义能力

下载
聚焦模式
字号
最后更新时间: 2026-10-21 15:59:44
本文档已由 AI 辅助审校

自定义提示与新增语言

自定义提示

如果您需要修改提示语,或者新增其他的语言文件的话,可以按照下面的方式去实现。 SDK 会提供一个翻译文件 custom_strings.xml,里面包含所有卡证核验 SDK 对外可以进行修改的配置文件。
1. 打开主 module(集成 SDK 的 module)工程。
2. 将 custom_strings.xml 添加到对应的语言文件夹下。
3. 修改其中需要自定义的文字内容即可。
4. 打包以后,您修改的内容会自动覆盖原有的内容。
└── src
└── main
├── AndroidManifest.xml
├── assets
├── java
└── res
├── values-zh-rCN
│ └── custom_strings.xml
└── values-zh-rHK
└── custom_strings.xml

新增语言

新增语言文件时,执行以下三步即可实现:
1. 在主 module(集成卡证核验 SDK 的 module)工程里新增对应语言文件夹。
2. 将 custom_strings.xml 拷贝到该语言文件夹下,并修改对应的 value 内容。
└── src
└── main
├── AndroidManifest.xml
├── assets
├── java
└── res
├── values-th-rTH
│ └── custom_strings.xml <<<<<<<<<<< 以泰文为例,values-th-rTH
├── values-zh-rCN
│ └── custom_strings.xml
└── values-zh-rHK
└── custom_strings.xml
3. 在代码里指定对应的语言码即可(以泰文为例)。
cloudConfig.setLanguageStyle(LanguageStyle.CUSTOMIZE_LANGUAGE);
cloudConfig.setLanguageCode("th-TH");


附录 Android 语言码

本文提供以下 Android 的部分语言码,以供参考。
语言码
对应使用的国家或地区
af-ZA
通用荷兰语 - 南非
sq-AL
阿尔巴尼亚语 - 阿尔巴尼亚
ar-DZ
阿拉伯语 - 阿尔及利亚
ar-BH
阿拉伯语 - 巴林
ar-EG
阿拉伯语 - 埃及
ar-IQ
阿拉伯语 - 伊拉克
ar-JO
阿拉伯语 - 约旦
ar-KW
阿拉伯语 - 科威特
ar-LB
阿拉伯语 - 黎巴嫩
ar-LY
阿拉伯语 - 利比亚
ar-MA
阿拉伯语 - 摩洛哥
ar-OM
阿拉伯语 - 阿曼
ar-QA
阿拉伯语 - 卡塔尔
eu-ES
巴斯克语 - 巴斯克
be-BY
Belarusian - 白俄罗斯
bg-BG
保加利亚语 - 保加利亚
ca-ES
加泰罗尼亚语 - 加泰罗尼亚
zh-HK
中文 - 中国香港
zh-MO
中文 - 中国澳门
zh-CN
中文 - 中国
zh-SG
中文 - 新加坡
zh-TW
中文 - 中国台湾
zh-CHS
中文 (简体)
zh-CHT
中文 (繁体)
hr-HR
克罗地亚语 - 克罗地亚
cs-CZ
捷克语 - 捷克
da-DK
丹麦语 - 丹麦
div-MV
迪维希语 - 马尔代夫
nl-BE
荷兰语 - 比利时
nl-NL
荷兰语 - 荷兰
en-AU
英语 - 澳大利亚
en-CA
英语 - 加拿大
en-ZA
英语 - 南非
en-PH
英语 - 菲律宾
en-NZ
英语 - 新西兰
en-GB
英语 - 英国
en-US
英语 - 美国
fa-IR
波斯语 - 伊朗
fi-FI
芬兰语 - 芬兰
fr-FR
法语 - 法国
fr-BE
法语 - 比利时
fr-MC
法语 - 摩纳哥
fr-CH
法语 - 瑞士
gl-ES
加利西亚 - 西班牙
ka-GE
格鲁吉亚语 - 格鲁吉亚
de-DE
德语 - 德国
de-LU
德语 - 卢森堡
de-CH
德语 - 瑞士
el-GR
希腊语 - 希腊
gu-IN
Gujarati - 印度
he-IL
希伯来 - 以色列
hi-IN
北印度语 - 印度
hu-HU
匈牙利语 - 匈牙利
is-IS
冰岛语 - 冰岛
it-IT
意大利语 - 意大利
ja-JP
日语 - 日本
kk-KZ
Kazakh - 哈萨克
kn-IN
卡纳达语 - 印度
ko-KR
韩语 - 韩国
lv-LV
拉脱维亚语 - 拉脱维亚
lt-LT
立陶宛语 - 立陶宛
ms-BN
马来 - 文莱
ms-MY
马来 - 马来西亚
mr-IN
马拉地语 - 印度
mn-MN
蒙古语 - 蒙古
nn-NO
挪威 (Nynorsk)- 挪威
pl-PL
波兰语 - 波兰
pt-BR
葡萄牙 - 巴西
pt-PT
葡萄牙 - 葡萄牙
ro-RO
罗马尼亚语 - 罗马尼亚
sa-IN
梵文 - 印度
ru-RU
俄语 - 俄罗斯
sk-SK
斯洛伐克语 - 斯洛伐克
es-AR
西班牙 - 阿根廷
es-ES
西班牙 - 西班牙
sv-SE
瑞典语 - 瑞典
th-TH
泰语 - 泰国
tr-TR
土耳其语 - 土耳其
uk-UA
乌克兰语 - 乌克兰
ur-PK
Urdu - 巴基斯坦
vi-VN
越南语 - 越南



自定义 UI 布局

Token 模式(OcrOverseasCloudKit)的采集界面与"全流程接入"模式复用同一套 Activity / Fragment,因此自定义 UI 布局能力在 Token 模式下完全可用,只需把 CustomConfigUi 通过 OcrCloudConfig#setCustomConfigUi 传入即可生效。


1. 获取默认布局文件

SDK 提供默认的竖屏布局 demo_ocr_detect_fragment.xml 和横屏布局 demo_ocr_detect_hor_fragment.xml,集成方可在此基础上进行 UI 修改。

相关资源可以在交付包的 res 文件夹内获取(res/layout/、res/drawable/、res/values/)。
注意:
不要删除或修改默认 view 及其对应的 id,否则 SDK 无法绑定控件,会导致采集界面异常或直接崩溃。可以在默认布局上自由调整位置、样式,也可以新增自己的 view。

2. 布局中必须保留的 view id

竖屏布局(portraitLayoutResId):

view id
控件类型
作用
是否必须
camera_surface_view
TextureView
相机预览
必须
ocr_mask_view
com.tencent.ocr.sdk.component.CameraMaskView
遮罩层与识别框
必须
ocr_tips_tv
com.tencent.ocr.sdk.component.OcrDetectTipsView
实时提示文案
必须
take_picture_button
ImageButton
手动拍照按钮
必须
album_image_button
ImageButton
相册选图按钮
必须
light_image_button
ImageButton
闪光灯按钮
必须
txy_detect_back
ImageView
悬浮返回按钮
必须
txy_action_bar_rl
RelativeLayout
标题栏根布局
使用标题栏时必须
txy_action_left_ib
ImageButton
标题栏返回按钮
使用标题栏时必须
txy_action_title_tv
TextView
标题栏标题文字
使用标题栏时必须
横屏布局(landscapeLayoutResId,需同时设置 isLandscape = true):

view id
控件类型
作用
是否必须
camera_surface_land_view
TextureView
相机预览
必须
ocr_hor_mask_view
com.tencent.ocr.sdk.component.CameraMaskView
遮罩层与识别框
必须
ocr_tips_tv_land
com.tencent.ocr.sdk.component.OcrDetectTipsView
实时提示文案
必须
take_picture_button_land
ImageButton
手动拍照按钮
必须
album_image_button_land
ImageButton
相册选图按钮
必须
txy_ocr_light_off_land
ImageButton
闪光灯按钮
必须
txy_land_back_action_btn
ImageView
返回按钮
必须
txy_action_left_ib
ImageButton
标题栏返回按钮
使用标题栏时必须
txy_action_title_tv
TextView
标题栏标题文字
使用标题栏时必须
说明:
横屏默认布局不包含标题栏,如需标题栏可自行 include 含 txy_action_left_ib / txy_action_title_tv 的子布局。

3. 设置自定义布局

把改造后的布局文件放到自己 module 的 res/layout/ 下,启动前把资源 id 传给 SDK:

CustomConfigUi customConfigUi = new CustomConfigUi();
// 竖屏自定义布局
customConfigUi.setPortraitLayoutResId(R.layout.demo_ocr_detect_fragment);
// 横屏自定义布局(需要同时开启横屏)
customConfigUi.setLandscape(true);
customConfigUi.setLandscapeLayoutResId(R.layout.demo_ocr_detect_hor_fragment);

OcrCloudConfig config = new OcrCloudConfig();
config.setSdkToken(sdkToken);
config.setServerParamInfo(serverParamInfo);
config.setCustomConfigUi(customConfigUi);
OcrOverseasCloudKit.getInstance().startCloudOcr(activity, config, resultListener);

未设置时(保持默认值 CustomConfigUi.INIT_INT_VALUE),SDK 使用内置的默认布局。


4. 操作自定义布局中新增的 view

如果在默认布局上新增了 view 并需要对其进行控制,可以通过 IOcrCloudEventListener#onMainViewCreate 拿到界面根 view 后自行注册事件:

OcrOverseasCloudKit.getInstance().setCloudEventListener(new IOcrCloudEventListener() {
@Override
public void onMainViewCreate(View mainView) {
// 界面创建的回调(主线程)
if (mainView != null) {
Button button = mainView.findViewById(R.id.demo_test_button);
// button 事件的注册与处理,注意 View 的判空!
if (button != null) {
button.setOnClickListener(v -> Log.d(TAG, "click"));
}
}
}

@Override
public void onMainViewDestroy() {
// 界面销毁的回调(主线程),需要在此解除持有,避免内存泄漏
}

@Override
public void onEventParamMap(HashMap<String, Object> map) {
// 额外参数透传
}
});
注意:
Token 模式请使用 OcrOverseasCloudKit#setCloudEventListener,不要使用全流程模式的 OcrSDKKit#setOcrEventListener(Token 模式下 SDK 内部会占用该监听器,业务方设置会被覆盖)。

5. CameraMaskView 属性

CameraMaskView 是识别框与遮罩的主体组件,支持在布局 xml 中直接通过属性配置,目前已支持的属性如下:

属性名
格式
含义
txy_mask_color
color|reference
遮罩层颜色
txy_tip_text
string|reference
识别框上方的提示文本
txy_tip_show
boolean
是否显示上方提示文本
txy_tip_color
color|reference
提示文字颜色
txy_tip_light_color
color|reference
提示文字高亮颜色
txy_tip_error_color
color|reference
提示文字异常状态颜色
txy_tip_size
integer|dimension
提示文字大小
txy_tip_margin
integer|dimension
提示文字底部与识别框的间隔
txy_tip_textStyle
flag
提示文字字体:normal/bold/italic/bold_italic
txy_bottom_tips_txt
string|reference
识别框下方 tips 文本内容
txy_bottom_tip_show
boolean
是否显示下方 tips
txy_bottom_tip_color
color|reference
下方 tips 文字颜色
txy_bottom_tip_size
integer|dimension
下方 tips 文字大小
txy_bottom_tip_margin_top
integer|dimension
下方 tips 与识别框的上间距
txy_bottom_tips_textStyle
flag
下方 tips 字体:normal/bold/italic/bold_italic
txy_line_color
color|reference
识别框边线默认颜色
txy_line_light_color
color|reference
识别框边线选中高亮颜色
txy_line_error_color
color|reference
识别框边线异常状态颜色
txy_line_width
integer|dimension
边线宽度(厚度)
txy_line_length
integer|dimension
边线长度
txy_line_padding
integer|dimension
边线与内部透明方框的间隔
txy_line_margin
integer|dimension
边线与屏幕边框的间隔
txy_front_head_icon
reference
身份证正面人像占位图标
txy_front_head_margin_top
integer|dimension
人像图标的上边距
txy_front_head_margin_right
integer|dimension
人像图标的右边距
txy_back_emblem_icon
reference
身份证反面国徽占位图标
txy_back_emblem_margin_top
integer|dimension
国徽图标的上边距
txy_back_emblem_margin_left
integer|dimension
国徽图标的左边距
txy_maskView_view_type
flag
识别框类型:normal/id_front/id_back/hk_03/hk_18/hk_macao_pass
txy_position_flag
enum
识别框位置:center(居中)/margin(按边距定位)
txy_mask_margin
integer|dimension
仅当 txy_position_flag=margin 时生效,识别框的定位边距
txy_mask_view_use_type
flag
遮罩使用场景:portrait(竖屏)/landscape(横屏)
txy_rect_height_weight_hor
integer
横屏下识别框中间高度所占比例
txy_is_show_scanline
boolean
是否显示内部扫描线
txy_scanline_start_color
color|reference
扫描线起始颜色
txy_scanline_mid_color
color|reference
扫描线过渡颜色
txy_scanline_end_color
color|reference
扫描线结束颜色
txy_scanline_animator_time
integer
扫描线动画一次耗时
txy_scanline_start_color_size_range
integer
起始颜色的覆盖区间
txy_scanline_start_to_mid_color_size_range
integer
起始色到过渡色的渐变区间
注意:
如果 XML 属性与 CustomConfigUi 传入的属性产生冲突,CustomConfigUi 配置的优先级更高(例如 cardFrameColor、titleBarText、isShowTips 等会在界面创建后覆盖 XML 中的取值)。






帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈