imageFeaturePicker (全局取色功能)-ArkTS API-Pen Kit（手写笔服务）-硬件-系统

imageFeaturePicker (全局取色功能)

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

更新时间: 2026-08-29 09:41

全局取色的功能入口类。

起始版本： 5.0.0(12)

导入模块

import { imageFeaturePicker } from '@kit.Penkit';

PickedColorInfo

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

全局取色结果对象，包含取色的基本信息。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Stylus.ColorPicker

起始版本： 5.0.0(12)

展开

名称	类型	只读	可选	说明
color	common2D.Color	否	否	色值。
colorSpace	colorSpaceManager.ColorSpace	否	否	色域空间。
timestamp	number	否	否	时间戳，自系统启动以来经过的时间，单位：ms。
brightness	number	否	是	颜色的亮度，调用pickHdrForResult接口时会返回，单位：nit。默认值：0。起始版本： 26.0.0

pickForResult

Phone5.1.1(19)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

pickForResult(x?: number, y?: number): Promise<PickedColorInfo>

全局取色，不支持实时显示RGB值。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Stylus.ColorPicker

起始版本： 5.0.0(12)

参数：

展开

参数名	类型	必填	说明
x	number	否	取色器初始位置的x轴坐标。取值范围：0~屏幕的实际宽度，取值超出上限取屏幕的实际宽度，单位：px，默认值：100。
y	number	否	取色器初始位置的y轴坐标。取值范围：0~屏幕的实际高度，取值超出上限取屏幕的实际高度，单位：px，默认值：100。

返回值：

展开

类型	说明
Promise<PickedColorInfo>	Promise对象，返回取色执行的结果。该Promise对象用于获取全局取色操作的结果，当取色成功时，会返回一个包含颜色信息的对象。

错误码：

以下错误码的详细介绍请参见ArkTS API 错误码。

展开

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	api is not supported
1013900001	IPC communication failed
1013900002	memory is insufficient
1013900003	service is invalid
1013900004	multi app call
1013900005	background service call

示例：

import { imageFeaturePicker } from '@kit.Penkit';

try {
    // 参数0表示取色器初始位置的x轴坐标和y轴坐标，实际使用时应根据用户交互获取具体坐标。
  imageFeaturePicker.pickForResult(0, 0).then(info => {
    console.info(`info is ${JSON.stringify(info)}`);
  })
} catch (error) {
  console.error(`Failed to pickForResult. code: ${error.code}, message: ${error.message}`);
}

pickForResult

Phone5.1.1(19)+PC/2in15.1.0(18)+Tablet5.1.0(18)+

pickForResult(x?: number, y?: number, showValue?: boolean): Promise<PickedColorInfo>

全局取色，支持实时显示RGB值。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Stylus.ColorPicker

起始版本： 5.1.0(18)

参数：

展开

参数名

类型

必填

说明

number

否

取色器初始位置的x轴坐标。取值范围：0~屏幕的实际宽度，取值超出上限取屏幕的实际宽度，单位：px，默认值：100。

number

否

取色器初始位置的y轴坐标。取值范围：0~屏幕的实际高度，取值超出上限取屏幕的实际高度，单位：px，默认值：100。

showValue

boolean

否

是否显示RGB值。true：显示RGB值，false：不显示RGB值。

默认值：false。

返回值：

展开

类型	说明
Promise<PickedColorInfo>	Promise对象，返回取色执行的结果。该Promise对象用于获取全局取色操作的结果，当取色成功时，会返回一个包含颜色信息的对象。

错误码：

以下错误码的详细介绍请参见ArkTS API 错误码。

展开

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	api is not supported
1013900001	IPC communication failed
1013900002	memory is insufficient
1013900003	service is invalid
1013900004	multi app call
1013900005	background service call

示例：

import { imageFeaturePicker } from '@kit.Penkit';

try {
    // 参数0表示取色器初始位置的x轴坐标和y轴坐标，实际使用时应根据用户交互获取具体坐标；true表示显示RGB值。
  imageFeaturePicker.pickForResult(0, 0, true).then(info => {
    console.info(`info is ${JSON.stringify(info)}`);
  })
} catch (error) {
  console.error(`Failed to pickForResult. code: ${error.code}, message: ${error.message}`);
}

pickHdrForResult

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+

pickHdrForResult(x?: number, y?: number): Promise<PickedColorInfo>

全局取色（支持HDR图片），不支持实时显示RGB值。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Stylus.ColorPicker

起始版本： 26.0.0

参数：

展开

参数名	类型	必填	说明
x	number	否	取色器初始位置的x轴坐标。取值范围：0~屏幕的实际宽度，取值超出上限取屏幕的实际宽度，单位：px，默认值：100。
y	number	否	取色器初始位置的y轴坐标。取值范围：0~屏幕的实际高度，取值超出上限取屏幕的实际高度，单位：px，默认值：100。

返回值：

展开

类型	说明
Promise<PickedColorInfo>	Promise对象，返回取色执行的结果。该Promise对象用于获取全局取色操作的结果，当取色成功时，会返回一个包含颜色信息的对象。

错误码：

以下错误码的详细介绍请参见ArkTS API 错误码。

展开

错误码ID	错误信息
801	Capability not supported. The pickHdrForResult function cannot work properly due to limited device capabilities.
1013900001	IPC failed.
1013900002	Insufficient memory.
1013900003	Invalid service.
1013900004	Multi-app calling.
1013900005	Background service calling.

示例：

import { imageFeaturePicker } from '@kit.Penkit';

try {
    // 参数0表示取色器初始位置的x轴坐标和y轴坐标，实际使用时应根据用户交互获取具体坐标。
  imageFeaturePicker.pickHdrForResult(0, 0).then(info => {
    console.info(`info is ${JSON.stringify(info)}`);
  })
} catch (error) {
  console.error(`Failed to pickHdrForResult. code: ${error.code}, message: ${error.message}`);
}

pickHdrForResult

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+

pickHdrForResult(x?: number, y?: number, showValue?: boolean): Promise<PickedColorInfo>

全局取色（支持HDR图片），支持实时显示RGB值。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Stylus.ColorPicker

起始版本： 26.0.0

参数：

展开

参数名

类型

必填

说明

number

否

取色器初始位置的x轴坐标。取值范围：0~屏幕的实际宽度，取值超出上限取屏幕的实际宽度，单位：px，默认值：100。

number

否

取色器初始位置的y轴坐标。取值范围：0~屏幕的实际高度，取值超出上限取屏幕的实际高度，单位：px，默认值：100。

showValue

boolean

否

是否显示RGB值。true：显示RGB值，false：不显示RGB值。

默认值：false。

返回值：

展开

类型	说明
Promise<PickedColorInfo>	Promise对象，返回取色执行的结果。该Promise对象用于获取全局取色操作的结果，当取色成功时，会返回一个包含颜色信息的对象。

错误码：

以下错误码的详细介绍请参见ArkTS API 错误码。

展开

错误码ID	错误信息
801	Capability not supported. The pickHdrForResult function cannot work properly due to limited device capabilities.
1013900001	IPC failed.
1013900002	Insufficient memory.
1013900003	Invalid service.
1013900004	Multi-app calling.
1013900005	Background service calling.

示例：

import { imageFeaturePicker } from '@kit.Penkit';

try {
    // 参数0表示取色器初始位置的x轴坐标和y轴坐标，实际使用时应根据用户交互获取具体坐标；true表示显示RGB值。
  imageFeaturePicker.pickHdrForResult(0, 0, true).then(info => {
    console.info(`info is ${JSON.stringify(info)}`);
  })
} catch (error) {
  console.error(`Failed to pickHdrForResult. code: ${error.code}, message: ${error.message}`);
}