# 条件格式

条件格式（Conditional Format）允许根据单元格的值自动应用不同的样式或可视化效果。常见的使用场景包括：

* 突出显示满足某条件的单元格（例如：`数值大于 50` 时填充红色背景）
* 在数值区域内绘制数据条（Data Bar）以直观对比大小
* 使用色阶（Color Scale）渐变显示数据分布
* 使用图标集（Icon Set）标记区间，例如三色交通灯
* 通过文本/日期/重复值/排名等内置规则筛选目标单元格

xlswriter 通过 `Vtiful\Kernel\ConditionalFormat` 类构造一条规则，再调用 `Excel::conditionalFormatCell` 或 `Excel::conditionalFormatRange` 把规则应用到工作表上。

## 函数原型

```php
Excel::conditionalFormatCell(string $rangeA1, \Vtiful\Kernel\ConditionalFormat $cf): self
Excel::conditionalFormatRange(string $rangeA1, \Vtiful\Kernel\ConditionalFormat $cf): self
```

### **string $rangeA1**

> 单元格地址或区域，使用 A1 表示法。例如 `"A1"`、`"A1:A10"`、`"B2:D8"`。

### **\Vtiful\Kernel\ConditionalFormat $cf**

> 通过 `new \Vtiful\Kernel\ConditionalFormat()` 创建并链式配置好的规则对象。直接传入对象本身，无需调用 `toResource()`。

## 快速开始

下面的例子在 `A2:A4` 三个单元格上应用一条「数值大于 50 时填充红底白字」的规则：

```php
$config = ['path' => './tests'];
$excel  = new \Vtiful\Kernel\Excel($config);

$fileObject = $excel->fileName('tutorial.xlsx');
$fileHandle = $fileObject->getHandle();

// 满足条件时使用的样式
$highlight = (new \Vtiful\Kernel\Format($fileHandle))
    ->background(\Vtiful\Kernel\Format::COLOR_RED)
    ->fontColor(\Vtiful\Kernel\Format::COLOR_WHITE)
    ->toResource();

// 构造规则：单元格类型 + 大于 50 + 应用 $highlight
$cf = new \Vtiful\Kernel\ConditionalFormat();
$cf->type(\Vtiful\Kernel\ConditionalFormat::TYPE_CELL)
   ->criteria(\Vtiful\Kernel\ConditionalFormat::CRITERIA_GREATER_THAN)
   ->value(50)
   ->format($highlight);

$fileObject->header(['score'])
    ->data([[10], [60], [80]])
    ->conditionalFormatRange('A2:A4', $cf)
    ->output();
```

## 章节列表

| 页面                                                                  | 内容                |
| ------------------------------------------------------------------- | ----------------- |
| [单元格规则](/zhong-wen-jian-ti/conditional-format/cell.md)              | 在单个单元格上应用条件规则     |
| [区域规则](/zhong-wen-jian-ti/conditional-format/range.md)              | 在一个 A1 区域上应用条件规则  |
| [数据条](/zhong-wen-jian-ti/conditional-format/data-bar.md)            | Data Bar 数据条相关方法  |
| [图标集](/zhong-wen-jian-ti/conditional-format/icons.md)               | Icon Set 图标集相关方法  |
| [多区域](/zhong-wen-jian-ti/conditional-format/multi-range.md)         | 一条规则同时应用到多个不连续区域  |
| [类型常量](/zhong-wen-jian-ti/conditional-format/type-constants.md)     | `TYPE_*` 常量列表     |
| [条件常量](/zhong-wen-jian-ti/conditional-format/criteria-constants.md) | `CRITERIA_*` 常量列表 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xlswriter-docs.viest.me/zhong-wen-jian-ti/conditional-format.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.