# 插入批注

## **函数原型**

```php
insertComment(int $row, int $column, string $text): self

insertCommentOpt(int $row, int $column, string $text, array $options): self

showComment(): self
```

### **int $row**

> 单元格所在行

### **int $column**

> 单元格所在列

### **string $text**

> 批注内容

### **array $options**

> 批注扩展选项，所有键均为可选：
>
> * `author` *string* —— 批注作者
> * `font_name` *string* —— 批注字体
> * `font_size` *double* —— 批注字号
> * `color` *int* —— 批注背景色（`0xRRGGBB` 或 `Format::COLOR_*`）
> * `x_offset` *int* —— X 方向像素偏移
> * `y_offset` *int* —— Y 方向像素偏移
> * `x_scale` *double* —— 横向缩放比例
> * `y_scale` *double* —— 纵向缩放比例
> * `width` *double* —— 批注框宽度（像素）
> * `height` *double* —— 批注框高度（像素）
> * `visible` *int* —— 批注显示模式，推荐使用以下常量：
>   * `Excel::COMMENT_DISPLAY_DEFAULT` —— 跟随工作簿全局开关
>   * `Excel::COMMENT_DISPLAY_HIDDEN` —— 仅悬停时显示
>   * `Excel::COMMENT_DISPLAY_VISIBLE` —— 始终常驻显示
> * `start_row` *int* —— 批注框起始行
> * `start_col` *int* —— 批注框起始列

`showComment()` 用于打开整个工作簿的批注默认显示开关，调用一次即可对所有批注生效。

## 示例

```php
$config = [
    'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);

$file = $excel->fileName('tutorial.xlsx')
    ->header(['name', 'score']);

$file->insertText(1, 0, 'viest')
     ->insertText(1, 1, 99)
     ->insertComment(1, 1, '满分接近，继续努力')
     ->insertCommentOpt(1, 0, '主要负责人', [
         'author'    => 'admin',
         'font_name' => 'Arial',
         'font_size' => 10,
         'color'     => \Vtiful\Kernel\Format::COLOR_YELLOW,
         'width'     => 200,
         'height'    => 80,
         'visible'   => \Vtiful\Kernel\Excel::COMMENT_DISPLAY_VISIBLE,
     ])
     ->showComment()
     ->output();
```


---

# 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/cell/insert-comment.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.