IColorScale

Interface IColorScale

public interface IColorScale

表示颜色刻度条件格式规则。

颜色刻度规则会将颜色渐变应用于单元格，以指示其值的相对差异。使用此接口可以访问规则应用到的区域、配置其阈值条件，并在其他条件格式规则之间控制其求值优先级。


 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 IColorScale colorScale = range.getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 colorScale.getColorScaleCriteria().get(0).getFormatColor().setColor(Color.GetRed());
 colorScale.setAppliesTo(worksheet.getRange("B1:B5"));

Method Summary

Modifier and Type

Method

Description

void

delete()

删除此条件格式。

void

fromJson(String json)

从 JSON 字符串生成条件格式。

IRange

getAppliesTo()

返回 IRange 对象，该对象指定格式规则应用到的单元格区域。

IColorScaleCriteria

getColorScaleCriteria()

获取颜色刻度条件集合。

int

getPriority()

返回条件格式规则的优先级值。

boolean

getStopIfTrue()

返回一个布尔值，该值确定如果当前规则的求值结果为 true，是否还应继续对单元格上的其他格式规则求值。

FormatConditionType

getType()

返回此条件格式的类型。

void

setAppliesTo(IRange value)

设置一个 IRange 对象，该对象指定格式规则应用到的单元格区域。

void

setFirstPriority()

将此条件格式规则的优先级值设置为 1，使其在工作表上的所有其他规则之前求值。

void

setLastPriority()

设置此条件格式规则的求值顺序，使其在工作表上的所有其他规则之后求值。

void

setPriority(int value)

设置条件格式规则的优先级值。

String

toJson()

从条件格式生成 JSON 字符串。

Method Details

getAppliesTo

IRange getAppliesTo()
返回 IRange 对象，该对象指定格式规则应用到的单元格区域。
使用 setAppliesTo(IRange) 可以更改与此颜色刻度条件格式规则关联的区域。
```
 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 IColorScale colorScale = range.getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 IRange appliesTo = colorScale.getAppliesTo();
 
```
Returns:

指定格式规则应用到的单元格区域的 IRange 对象。
setAppliesTo

void setAppliesTo(IRange value)
设置一个 IRange 对象，该对象指定格式规则应用到的单元格区域。
使用此方法可以将现有颜色刻度条件格式规则移动到其他区域。
```
 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 IColorScale colorScale = range.getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 colorScale.setAppliesTo(worksheet.getRange("B1:B5"));
 
```
Parameters:

value - 指定格式规则应用到的单元格区域的 IRange 对象。

getColorScaleCriteria

IColorScaleCriteria getColorScaleCriteria()

获取颜色刻度条件集合。

返回 IColorScaleCriteria 对象，它是各个 IColorScaleCriterion 对象的集合。每个条件指定颜色刻度条件格式所用阈值的类型、值和颜色。


 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 IColorScale colorScale = range.getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 IColorScaleCriteria criteria = colorScale.getColorScaleCriteria();
 criteria.get(0).getFormatColor().setColor(Color.GetRed());

Returns:: 颜色刻度条件格式的阈值条件集合。

getPriority

int getPriority()

返回条件格式规则的优先级值。

当工作表中存在多个条件格式规则时，优先级决定求值顺序。较低的优先级值表示该规则会更早求值。

优先级值在工作表内是唯一的。使用 setPriority(int) 更改某条规则的优先级时，工作表上其他规则的优先级值可能会相应移动。


 worksheet.getRange("A1:B5").setValue(new Object[][] {{10, 5}, {30, 15}, {20, 25}, {50, 35}, {40, 45}});
 IColorScale firstRule = worksheet.getRange("A1:A5").getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 IColorScale secondRule = worksheet.getRange("B1:B5").getFormatConditions().addColorScale(ColorScaleType.ThreeColorScale);
 secondRule.setPriority(1);
 int priority = secondRule.getPriority();

Returns:: 条件格式规则的优先级值。

setPriority

void setPriority(int value)

设置条件格式规则的优先级值。

当工作表中存在多个条件格式规则时，优先级决定求值顺序。较低的优先级值表示该规则会更早求值。


 worksheet.getRange("A1:B5").setValue(new Object[][] {{10, 5}, {30, 15}, {20, 25}, {50, 35}, {40, 45}});
 IColorScale firstRule = worksheet.getRange("A1:A5").getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 IColorScale secondRule = worksheet.getRange("B1:B5").getFormatConditions().addColorScale(ColorScaleType.ThreeColorScale);
 secondRule.setPriority(1);

Parameters:: value - 条件格式规则的优先级值。

getStopIfTrue

boolean getStopIfTrue()
返回一个布尔值，该值确定如果当前规则的求值结果为 true，是否还应继续对单元格上的其他格式规则求值。
如果此方法返回 true，则对于此颜色刻度规则求值为 true 的单元格，不会对后续条件格式规则求值。如果返回 false，则后续规则可以继续求值。
```
 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 IColorScale colorScale = range.getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 boolean stopIfTrue = colorScale.getStopIfTrue();
 
```
Returns:

如果当前规则求值为 true 后不应继续对单元格上的其他格式规则求值，则为 true；否则为 false。

getType

FormatConditionType getType()

返回此条件格式的类型。

使用此方法可以将条件格式规则类别识别为 FormatConditionType 值。


 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 IColorScale colorScale = range.getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 FormatConditionType type = colorScale.getType();

Returns:: 此条件格式的类型。

delete

void delete()

删除此条件格式。

使用此方法可以从其工作表中移除当前颜色刻度条件格式规则。


 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 IColorScale colorScale = range.getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 colorScale.delete();

setFirstPriority

void setFirstPriority()

将此条件格式规则的优先级值设置为 1，使其在工作表上的所有其他规则之前求值。

使用此方法可以将当前颜色刻度规则移动到工作表条件格式规则中的最高求值优先级。


 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 range.getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 IColorScale colorScale = range.getFormatConditions().addColorScale(ColorScaleType.ThreeColorScale);
 colorScale.setFirstPriority();

setLastPriority

void setLastPriority()

设置此条件格式规则的求值顺序，使其在工作表上的所有其他规则之后求值。

使用此方法可以将当前颜色刻度规则移动到工作表中条件格式规则的最低求值优先级。


 worksheet.getRange("A1:B5").setValue(new Object[][] {
     {10, 20}, {30, 40}, {50, 60}, {70, 80}, {90, 100}
 });
 IColorScale firstRule = worksheet.getRange("A1:A5").getFormatConditions()
     .addColorScale(ColorScaleType.TwoColorScale);
 IColorScale secondRule = worksheet.getRange("B1:B5").getFormatConditions()
     .addColorScale(ColorScaleType.TwoColorScale);
 secondRule.setLastPriority();

fromJson

void fromJson(String json)

从 JSON 字符串生成条件格式。

使用指定的 JSON 内容更新此颜色刻度规则。JSON 通常由 toJson() 从另一个 IColorScale 实例生成。


 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 String json = "{\"ranges\":[{\"row\":0,\"col\":1,\"rowCount\":5,\"colCount\":1}],\"priority\":1,\"ruleType\":10,\"minType\":1,\"minValue\":null,\"minColor\":\"rgb(255,0,0)\",\"maxType\":2,\"maxValue\":null,\"maxColor\":\"rgb(255,239,156)\"}";
 IColorScale colorScale = worksheet.getRange("B1:B5").getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 colorScale.fromJson(json);

Parameters:: json - 定义颜色刻度条件格式的 JSON 字符串。
Throws:: IllegalStateException - 如果 JSON 字符串未描述颜色刻度条件格式。

toJson

String toJson()

从条件格式生成 JSON 字符串。

返回的字符串表示当前颜色刻度条件格式规则，可与 fromJson(String) 一起使用以重新创建该规则。


 IRange range = worksheet.getRange("A1:A5");
 range.setValue(new Object[][] {{10}, {30}, {50}, {70}, {90}});
 IColorScale colorScale = range.getFormatConditions().addColorScale(ColorScaleType.TwoColorScale);
 String json = colorScale.toJson();

Returns:: 条件格式 JSON 字符串。