@thinkfree.dev/tfo-sdk 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -2,15 +2,10 @@
2
2
  * Thinkfree Office SDK — Type Definitions
3
3
  *
4
4
  * Bundled type definitions for the word / cell / show modules.
5
+ * Every proxy method crosses a postMessage bridge and returns a Promise.
5
6
  * ⚠️ AUTO-GENERATED — DO NOT EDIT.
6
- */
7
- /**
8
- * Thinkfree Office SDK Type Definitions
9
7
  *
10
- * ⚠️ AUTO-GENERATED — DO NOT EDIT.
11
- * 오피스 구현 저장소(비공개)의 API JSDoc 에서 생성된다 — 수정은 원본 JSDoc 에서.
12
- *
13
- * Generated: 2026-09-22
8
+ * Generated: 2026-09-30
14
9
  */
15
10
  /** 선 대시(점선) 스타일 (OOXML a:prstDash). */
16
11
  declare const LineDash: {
@@ -398,84 +393,118 @@ declare const ShapeZOrder: {
398
393
  };
399
394
  type ShapeZOrder = typeof ShapeZOrder[keyof typeof ShapeZOrder];
400
395
  /**
401
- * addChart/setType 의 chartType. 단순 (type, range) 생성이 가능한 20종만 있으며,
402
- * 그 밖의 종류는 CHART_TYPE_UNSUPPORTED 로 거부된다.
396
+ * 차트를 추가하는 메서드와 `Chart.setType` 에 넘기는 차트 종류다.
397
+ *
398
+ * 데이터 범위 하나로 만들 수 있는 20종만 있다. getType 은 파일에서 읽은 100% 누적 막대형·거품형 차트에 여기에 없는 그 종류의 이름을, 그 밖에 여기에 없는 종류에 "unknown" 을 반환한다.
403
399
  */
404
400
  declare const ChartType: {
401
+ /** 묶은 세로 막대형 */
405
402
  readonly clusteredColumn: "clustered_column";
403
+ /** 누적 세로 막대형 */
406
404
  readonly stackedColumn: "stacked_column";
405
+ /** 3차원 묶은 세로 막대형 */
407
406
  readonly _3dClusteredColumn: "3d_clustered_column";
407
+ /** 3차원 누적 세로 막대형 */
408
408
  readonly _3dStackedColumn: "3d_stacked_column";
409
+ /** 묶은 가로 막대형 */
409
410
  readonly clusteredBar: "clustered_bar";
411
+ /** 누적 가로 막대형 */
410
412
  readonly stackedBar: "stacked_bar";
413
+ /** 3차원 묶은 가로 막대형 */
411
414
  readonly _3dClusteredBar: "3d_clustered_bar";
415
+ /** 3차원 누적 가로 막대형 */
412
416
  readonly _3dStackedBar: "3d_stacked_bar";
417
+ /** 꺾은선형 */
413
418
  readonly line: "line";
419
+ /** 원형 */
414
420
  readonly pie: "pie";
421
+ /** 3차원 원형 */
415
422
  readonly _3dPie: "3d_pie";
423
+ /** 쪼개진 원형 */
416
424
  readonly explodedPie: "exploded_pie";
425
+ /** 3차원 쪼개진 원형 */
417
426
  readonly _3dExplodedPie: "3d_exploded_pie";
427
+ /** 분산형 */
418
428
  readonly scatter: "scatter";
429
+ /** 영역형 */
419
430
  readonly area: "area";
431
+ /** 누적 영역형 */
420
432
  readonly stackedArea: "stacked_area";
433
+ /** 3차원 영역형 */
421
434
  readonly _3dArea: "3d_area";
435
+ /** 3차원 누적 영역형 */
422
436
  readonly _3dStackedArea: "3d_stacked_area";
437
+ /** 도넛형 */
423
438
  readonly doughnut: "doughnut";
439
+ /** 방사형 */
424
440
  readonly radar: "radar";
425
441
  };
426
442
  type ChartType = typeof ChartType[keyof typeof ChartType];
427
- /** setGridLine 의 gridType. "none" 은 해당 축 눈금선 숨김. */
443
+ /** `Chart.setGridLine` 의 `gridType` 에 넘기는 눈금선 종류다. getGridLine 도 같은 값을 반환한다. */
428
444
  declare const ChartGridLineType: {
445
+ /** 그 축의 눈금선을 숨긴다 */
429
446
  readonly none: "none";
447
+ /** 주 눈금선만 표시한다 */
430
448
  readonly major: "major";
449
+ /** 보조 눈금선만 표시한다 */
431
450
  readonly minor: "minor";
451
+ /** 주 눈금선과 보조 눈금선을 함께 표시한다 */
432
452
  readonly majorMinor: "major_minor";
433
453
  };
434
454
  type ChartGridLineType = typeof ChartGridLineType[keyof typeof ChartGridLineType];
435
- /** setAxisTitle/setGridLine 의 axis — 대상 축을 가리킨다. */
455
+ /** `Chart.setAxisTitle`·`Chart.setGridLine` 과 그 조회 메서드의 `axis` 에 넘기는 대상 축이다. */
436
456
  declare const ChartAxis: {
457
+ /** 가로축 */
437
458
  readonly horizontal: "horizontal";
459
+ /** 세로축 */
438
460
  readonly vertical: "vertical";
439
461
  };
440
462
  type ChartAxis = typeof ChartAxis[keyof typeof ChartAxis];
441
- /** setLegendPosition 의 position. "none" 은 범례 숨김. */
463
+ /** `Chart.setLegendPosition` 에 넘기는 범례 위치다. getLegendPosition 도 같은 값을 반환한다. */
442
464
  declare const ChartLegendPosition: {
465
+ /** 범례를 숨긴다 */
443
466
  readonly none: "none";
467
+ /** 차트 아래쪽 */
444
468
  readonly bottom: "bottom";
469
+ /** 차트 오른쪽 위 모서리 */
445
470
  readonly topRight: "top_right";
471
+ /** 차트 위쪽 */
446
472
  readonly top: "top";
473
+ /** 차트 오른쪽 */
447
474
  readonly right: "right";
475
+ /** 차트 왼쪽 */
448
476
  readonly left: "left";
449
477
  };
450
478
  type ChartLegendPosition = typeof ChartLegendPosition[keyof typeof ChartLegendPosition];
451
479
  /**
452
- * setDataLabelPosition 의 position. "none" 은 숨김.
453
- * 차트 타입별 유효 위치는 부분집합이며 위반 시 CHART_DATALABEL_POSITION_INVALID.
480
+ * `Chart.setDataLabelPosition` 에 넘기는 데이터레이블 위치다. getDataLabelPosition 도 같은 값을 반환하며, 데이터레이블이 아예 없는 차트 종류(표면형)는 null 이다.
481
+ *
482
+ * 데이터레이블 설정은 2차원 차트(원형 대 원형·주식형·표면형 제외)에서만 쓸 수 있고, 3차원 차트는 현재 지원하지 않는다. 쓸 수 있는 위치는 차트 종류마다 다르며 값마다 적었다.
454
483
  */
455
484
  declare const ChartDataLabelPosition: {
485
+ /** 데이터레이블 없음. 설정하면 데이터레이블을 없애고, 조회 결과로는 데이터레이블이 설정되지 않았다는 뜻이다 */
456
486
  readonly none: "none";
487
+ /** 데이터 요소의 가운데. 원형·막대형·꺾은선형·분산형에서 쓸 수 있다 */
457
488
  readonly center: "center";
489
+ /** 데이터 요소 안쪽의 끝. 원형·막대형에서 쓸 수 있다 */
458
490
  readonly insideEnd: "inside_end";
491
+ /** 데이터 요소 안쪽의 축 쪽 끝. 막대형에서 쓸 수 있다 */
459
492
  readonly insideBase: "inside_base";
493
+ /** 데이터 요소 바깥쪽의 끝. 원형·묶은 막대형에서 쓸 수 있다 */
460
494
  readonly outsideEnd: "outside_end";
495
+ /** 차트가 자리를 정한다. 원형·도넛형·영역형·방사형에서 쓸 수 있다 */
461
496
  readonly bestFit: "best_fit";
497
+ /** 데이터 요소의 왼쪽. 꺾은선형·분산형에서 쓸 수 있다 */
462
498
  readonly left: "left";
499
+ /** 데이터 요소의 오른쪽. 꺾은선형·분산형에서 쓸 수 있다 */
463
500
  readonly right: "right";
501
+ /** 데이터 요소의 위쪽. 꺾은선형·분산형에서 쓸 수 있다 */
464
502
  readonly top: "top";
503
+ /** 데이터 요소의 아래쪽. 꺾은선형·분산형에서 쓸 수 있다 */
465
504
  readonly bottom: "bottom";
466
505
  };
467
506
  type ChartDataLabelPosition = typeof ChartDataLabelPosition[keyof typeof ChartDataLabelPosition];
468
507
 
469
- /**
470
- * Thinkfree Office SDK Type Definitions
471
- *
472
- * ⚠️ AUTO-GENERATED — DO NOT EDIT.
473
- * 오피스 구현 저장소(비공개)의 API JSDoc 에서 생성된다 — 수정은 원본 JSDoc 에서.
474
- *
475
- * proxy 메서드는 postMessage bridge 를 거치므로 Promise 를 반환한다.
476
- * Generated: 2026-09-22
477
- */
478
-
479
508
  declare namespace Word {
480
509
  /**
481
510
  * 삽입 위치 — 기준 객체(receiver)를 기준으로 어디에 넣을지. insert 계열의 옵션 `position` 값.
@@ -523,17 +552,6 @@ declare namespace Word {
523
552
  readonly END: "end";
524
553
  };
525
554
  type SelectionMode = typeof SelectionMode[keyof typeof SelectionMode];
526
- /**
527
- * RangeBuilder.fromView() 인자 타입.
528
- * View 환경에서 어떤 정보를 ModelRange로 변환할지 결정한다.
529
- */
530
- const ViewContextType: {
531
- /** 현재 커서 (selection.getModelRange(false)) */
532
- readonly CURSOR: "cursor";
533
- /** 현재 선택 영역 (selection.getModelRange(true)) */
534
- readonly SELECTION: "selection";
535
- };
536
- type ViewContextType = typeof ViewContextType[keyof typeof ViewContextType];
537
555
  /** 문서 구조 조회 타입 필터 — getStructure({ type }) / get_document_structure 의 type 값. */
538
556
  const StructureFilter: {
539
557
  /** 표 */
@@ -542,33 +560,6 @@ declare namespace Word {
542
560
  readonly LIST: "list";
543
561
  };
544
562
  type StructureFilter = typeof StructureFilter[keyof typeof StructureFilter];
545
- /**
546
- * WordRange 가 "무엇을 가리키는지" 적어 두는 방식(종류).
547
- *
548
- * OFFSET 만 좌표를 직접 들고 있고, 나머지는 대상의 id·이름만 들고 있다가 **쓸 때 위치를 찾는다**
549
- * — 그래서 선택 영역이 바뀌거나 편집으로 표시가 밀려도 항상 지금 위치를 가리킨다.
550
- */
551
- const RangeKind: {
552
- /** 단락 ID + 글자 위치를 직접 지정(좌표를 들고 있음 — 이후 편집으로 어긋날 수 있다) */
553
- readonly OFFSET: "offset";
554
- /** 영역의 어느 부분인지로 지정(맨앞/맨끝/전체 등 — RangePosition) */
555
- readonly RANGE_POSITION: "rangePosition";
556
- /** 화면의 선택 영역/커서(쓸 때마다 현재 선택을 다시 읽는다) */
557
- readonly VIEW: "view";
558
- /** 그 댓글이 달린 본문 구간 */
559
- readonly COMMENT: "comment";
560
- /** 각주/미주 표시가 놓인 자리 */
561
- readonly NOTE: "note";
562
- /** 책갈피 표시가 놓인 자리(글자 한 칸) */
563
- readonly BOOKMARK: "bookmark";
564
- /** 도형·이미지가 놓인 자리(글자 한 칸 — floating 이면 앵커 자리) */
565
- readonly SHAPE: "shape";
566
- /** 하이퍼링크의 표시 텍스트 구간(앞뒤 마커는 제외 — 링크를 유지한 채 글자만 다룬다) */
567
- readonly HYPERLINK: "hyperlink";
568
- /** 변경 추적 항목이 차지하는 구간 */
569
- readonly CHANGE_TRACKING: "changeTracking";
570
- };
571
- type RangeKind = typeof RangeKind[keyof typeof RangeKind];
572
563
  /**
573
564
  * WordBody.search()/WordRange.search() 로 찾을 수 있는 특수 문자(눈에 보이지 않는 비-텍스트 런) 종류.
574
565
  * Word 찾기/바꾸기의 "특수 문자"에 대응 — 텍스트 검색(search)이 문자로 매칭하지 못하는 요소를 종류로 지목해 위치(Range)를 얻는다.
@@ -1216,8 +1207,8 @@ declare namespace Word {
1216
1207
  /** 링크 readback */
1217
1208
  hyperlink: {
1218
1209
  url: string;
1219
- tooltip: string;
1220
- linkType: string;
1210
+ tooltip: string | null;
1211
+ linkType: HyperlinkType;
1221
1212
  anchor?: string;
1222
1213
  } | null;
1223
1214
  /** 텍스트 영역 보유 여부(텍스트박스) */
@@ -1274,6 +1265,26 @@ declare namespace Word {
1274
1265
  /** key of the style for the next paragraph (if any) */
1275
1266
  next?: string;
1276
1267
  }
1268
+ interface ChartFormatInfo {
1269
+ /** 차트 종류. 값은 getType 과 같다 */
1270
+ type: ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown";
1271
+ /** 차트 제목. 설정하지 않았으면 빈 문자열이다 */
1272
+ title: string;
1273
+ /** 범례 위치 */
1274
+ legendPosition: ChartLegendPosition;
1275
+ /** 데이터레이블 위치. null 은 그 차트 종류에 데이터레이블이 아예 없다는 뜻이다(표면형) */
1276
+ dataLabelPosition: ChartDataLabelPosition | null;
1277
+ /** 축별 축 제목. null 은 그 차트 종류에 해당 축의 제목이 아예 없다는 뜻이다 */
1278
+ axisTitle: {
1279
+ horizontal: string | null;
1280
+ vertical: string | null;
1281
+ };
1282
+ /** 축별 눈금선. null 은 그 차트 종류에 해당 축의 눈금선이 아예 없다는 뜻이고, "none" 은 쓸 수는 있지만 꺼져 있다는 뜻이다 */
1283
+ gridLine: {
1284
+ horizontal: ChartGridLineType | null;
1285
+ vertical: ChartGridLineType | null;
1286
+ };
1287
+ }
1277
1288
  /**
1278
1289
  * The entry point to the document. Navigate to the body and sections, find document elements, and change document-wide settings.
1279
1290
  * - Use getBody() and getSection() to access the body and sections, and to get paragraphs, tables, shapes, charts, bookmarks, and more.
@@ -1385,21 +1396,6 @@ declare namespace Word {
1385
1396
  * @returns true if on, false if off
1386
1397
  */
1387
1398
  isChangeTrackingEnabled(): Promise<boolean>;
1388
- /**
1389
- * Saves the document.
1390
- * - Does nothing if there are no edits or a save is already in progress.
1391
- */
1392
- save(): Promise<void>;
1393
- /**
1394
- * Downloads the document in its original format.
1395
- */
1396
- download(): Promise<void>;
1397
- /**
1398
- * Prints the current document.
1399
- * - Uses browser printing on desktop Chrome and Edge; in other environments, converts to PDF and downloads it.
1400
- * - Does nothing if printing is disabled for the document.
1401
- */
1402
- print(): Promise<void>;
1403
1399
  /**
1404
1400
  * Changes the view zoom.
1405
1401
  *
@@ -1515,8 +1511,13 @@ declare namespace Word {
1515
1511
  *
1516
1512
  * @returns footnote/endnote list
1517
1513
  * @example
1518
- * word.getNotes().forEach(note => console.log(note.getBody().getText())); // get footnote/endnote content
1519
- * word.getFootnotes().forEach(note => note.delete()); // delete all footnotes
1514
+ * for (const note of await doc.getNotes()) {
1515
+ * const body = await note.getBody();
1516
+ * console.log(await body.getText()); // get footnote/endnote content
1517
+ * }
1518
+ * for (const note of await doc.getFootnotes()) {
1519
+ * await note.delete(); // delete all footnotes
1520
+ * }
1520
1521
  */
1521
1522
  getNotes(): Promise<WordNote[]>;
1522
1523
  /**
@@ -1884,7 +1885,7 @@ declare namespace Word {
1884
1885
  * @returns number of actual replacements (0 if no match)
1885
1886
  * @throws {Error} if findText is empty
1886
1887
  * @example
1887
- * doc.getBody().replaceAll("hello", "HI").replacedCount; // replacement count
1888
+ * const { replacedCount } = await body.replaceAll("hello", "HI"); // replacement count
1888
1889
  * doc.getBody().replaceAll("Draft", "Final", { caseSensitive: true }); // case-sensitive
1889
1890
  * doc.getSection().getHeader().replaceAll("v1", "v2"); // replace only in the header area
1890
1891
  * doc.getFootnotes()[0].getBody().replaceAll("insert", "update"); // replace only within the footnote content
@@ -2660,7 +2661,7 @@ declare namespace Word {
2660
2661
  * @returns list handle; null if the paragraph is not a list item
2661
2662
  * @throws {Error} if the paragraph does not exist in the document
2662
2663
  * @example
2663
- * const list = para.getList();
2664
+ * const list = await para.getList();
2664
2665
  * if (list) {
2665
2666
  * list.setLevel(IndentType.INDENT); // one level deeper
2666
2667
  * list.restartNumbering(); // restart numbering from this paragraph
@@ -3108,15 +3109,20 @@ declare namespace Word {
3108
3109
  /**
3109
3110
  * Inserts a text box into the paragraph of the range.
3110
3111
  *
3111
- * @param options - text box creation options (an omitted size axis defaults to 100; text is the initial content)
3112
+ * @param options - text box insertion options
3113
+ * @param options.width - width (pt) (default: 75)
3114
+ * @param options.height - height (pt) (default: 75)
3115
+ * @param options.text - initial content text
3112
3116
  * @returns creation result (shape: shape object / storyId: text box area ID / paragraphId: first paragraph ID)
3113
3117
  * @throws {Error} if width/height are not positive or text is not a string
3114
3118
  * @example
3115
3119
  * range.insertTextbox({ text: "Notice" }); // insert a text box
3116
3120
  * range.insertTextbox({ width: 200, height: 100, text: "Description" }); // specify size and content
3117
3121
  */
3118
- insertTextbox(options?: Size & {
3119
- text?: String;
3122
+ insertTextbox(options?: {
3123
+ width?: number;
3124
+ height?: number;
3125
+ text?: string;
3120
3126
  }): Promise<{
3121
3127
  shape: WordShape;
3122
3128
  storyId: string;
@@ -3881,9 +3887,9 @@ declare namespace Word {
3881
3887
  */
3882
3888
  interface WordChart extends WordShape {
3883
3889
  /**
3884
- * 차트 종류를 반환한다. ChartType 에 없는 종류는 "unknown" 을 반환한다.
3890
+ * 차트 종류를 반환한다. 파일에서 읽은 100% 누적 막대형·거품형 차트는 ChartType 에 없는 그 종류의 이름을, 그 밖에 ChartType 에 없는 종류는 "unknown" 을 반환한다.
3885
3891
  */
3886
- getType(): Promise<string>;
3892
+ getType(): Promise<ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown">;
3887
3893
  /**
3888
3894
  * 이 차트를 편집할 수 있는지 반환한다. 외부 데이터를 소스로 하는 차트는 조회만 되고 편집은 되지 않는다.
3889
3895
  */
@@ -3903,9 +3909,9 @@ declare namespace Word {
3903
3909
  */
3904
3910
  getLegendPosition(): Promise<ChartLegendPosition>;
3905
3911
  /**
3906
- * 데이터레이블 위치를 반환한다. 데이터레이블을 표시하지 않는 차트는 "none" 을 반환한다.
3912
+ * 데이터레이블 위치를 반환한다. 데이터레이블이 설정되지 않은 차트는 "none" 이고, 데이터레이블을 갖지 않는 차트 종류(표면형)는 null 을 반환한다.
3907
3913
  */
3908
- getDataLabelPosition(): Promise<ChartDataLabelPosition>;
3914
+ getDataLabelPosition(): Promise<ChartDataLabelPosition | null>;
3909
3915
  /**
3910
3916
  * 지정한 축의 눈금선 종류를 반환한다. 눈금선을 꺼 둔 축은 "none" 이고, 그 축의 눈금선을 갖지 않는 차트 종류(원형 계열·도넛은 양축, 방사형은 세로축)는 null 을 반환한다.
3911
3917
  *
@@ -3913,22 +3919,9 @@ declare namespace Word {
3913
3919
  */
3914
3920
  getGridLine(axis: ChartAxis): Promise<ChartGridLineType | null>;
3915
3921
  /**
3916
- * 차트의 서식 상태를 한 번에 반환한다. 각 값은 이름이 같은 조회 메서드와 같은 규약을 따른다. axisTitle 과 gridLine 의 null 은 그 차트 종류에 해당 축의 제목·눈금선이 아예 없다는 뜻이고, "none" 은 쓸 수는 있지만 꺼져 있다는 뜻이다.
3917
- */
3918
- getChartInfo(): Promise<{
3919
- type: string;
3920
- title: string;
3921
- legendPosition: ChartLegendPosition;
3922
- dataLabelPosition: ChartDataLabelPosition;
3923
- axisTitle: {
3924
- horizontal: string | null;
3925
- vertical: string | null;
3926
- };
3927
- gridLine: {
3928
- horizontal: ChartGridLineType | null;
3929
- vertical: ChartGridLineType | null;
3930
- };
3931
- }>;
3922
+ * 차트의 서식 상태를 한 번에 반환한다. 각 값은 이름이 같은 조회 메서드와 같다.
3923
+ */
3924
+ getChartInfo(): Promise<ChartFormatInfo>;
3932
3925
  /**
3933
3926
  * 차트 종류를 바꾼다. 지금 종류와 같은 값을 넘기면 아무것도 바뀌지 않는다.
3934
3927
  *
@@ -3942,16 +3935,17 @@ declare namespace Word {
3942
3935
  */
3943
3936
  setStyle(style: number): Promise<void>;
3944
3937
  /**
3945
- * 차트 제목을 설정한다.
3938
+ * 차트 제목을 설정한다. 빈 문자열을 넘기면 제목을 비운다.
3946
3939
  *
3947
- * @param title - 차트에 표시할 제목
3940
+ * @param title - 차트에 표시할 제목. 255자까지 지원한다
3948
3941
  */
3949
3942
  setTitle(title: string): Promise<void>;
3950
3943
  /**
3951
3944
  * 지정한 축의 제목을 설정한다. 축 제목은 원형 계열·도넛·방사형을 뺀 차트 종류에서 지원한다.
3945
+ * 빈 문자열을 넘기면 축 제목을 비운다.
3952
3946
  *
3953
3947
  * @param axis - 제목을 설정할 축(가로축 또는 세로축)
3954
- * @param title - 축에 표시할 제목
3948
+ * @param title - 축에 표시할 제목. 255자까지 지원한다
3955
3949
  */
3956
3950
  setAxisTitle(axis: ChartAxis, title: string): Promise<void>;
3957
3951
  /**
@@ -3961,15 +3955,16 @@ declare namespace Word {
3961
3955
  */
3962
3956
  setLegendPosition(position: ChartLegendPosition): Promise<void>;
3963
3957
  /**
3964
- * 데이터레이블 위치를 설정한다. "none" 을 넘기면 데이터레이블을 숨긴다.
3965
- * 쓸 수 있는 위치는 차트 종류마다 다르며, "none" 은 모든 종류에서 쓸 수 있다.
3958
+ * 데이터레이블 위치를 설정한다. "none" 을 넘기면 데이터레이블을 없앤다.
3959
+ * 데이터레이블 설정은 2차원 차트(원형 대 원형·주식형·표면형 제외)에서만 쓸 수 있고, 3차원 차트는 현재 지원하지 않는다.
3960
+ * 쓸 수 있는 위치는 차트 종류마다 다르다.
3966
3961
  *
3967
3962
  * @param position - 데이터레이블을 놓을 자리
3968
3963
  */
3969
3964
  setDataLabelPosition(position: ChartDataLabelPosition): Promise<void>;
3970
3965
  /**
3971
3966
  * 지정한 축의 눈금선을 설정한다. "none" 을 넘기면 그 축의 눈금선을 숨긴다.
3972
- * 그 축의 눈금선을 갖지 않는 차트 종류(원형 계열·도넛은 양축, 방사형은 세로축)는 "none" 을 포함해 어떤 값을 넘겨도 오류가 발생한다.
3967
+ * 눈금선은 그 축의 눈금선을 갖는 차트 종류에서 지원한다(원형 계열·도넛은 양축, 방사형은 세로축이 없다).
3973
3968
  *
3974
3969
  * @param axis - 눈금선을 설정할 축(가로축 또는 세로축)
3975
3970
  * @param gridType - 표시할 눈금선 종류
@@ -4047,7 +4042,13 @@ declare namespace Word {
4047
4042
  * @returns destination url
4048
4043
  * @throws {Error} if no hyperlink with the given ID exists
4049
4044
  * @example
4050
- * word.getHyperlinks().filter(link => link.getUrl().startsWith("http://")); // pick out insecure links
4045
+ * const insecure = [];
4046
+ * for (const link of await doc.getHyperlinks()) {
4047
+ * const url = await link.getUrl();
4048
+ * if (url.startsWith("http://")) {
4049
+ * insecure.push(link); // pick out insecure links
4050
+ * }
4051
+ * }
4051
4052
  */
4052
4053
  getUrl(): Promise<string>;
4053
4054
  /**
@@ -4276,1490 +4277,1641 @@ declare namespace Word {
4276
4277
  }
4277
4278
  }
4278
4279
 
4279
- /**
4280
- * Thinkfree Office SDK Type Definitions
4281
- *
4282
- * ⚠️ AUTO-GENERATED — DO NOT EDIT.
4283
- * 오피스 구현 저장소(비공개)의 API JSDoc 에서 생성된다 — 수정은 원본 JSDoc 에서.
4284
- *
4285
- * proxy 메서드는 postMessage bridge 를 거치므로 Promise 를 반환한다.
4286
- * Generated: 2026-09-22
4287
- */
4288
-
4289
4280
  declare namespace Cell {
4290
4281
  /**
4291
- * `Range.setHorizontalAlign` 에 넘기는 셀 가로 정렬이다.
4292
- *
4293
- * 지정하지 않은 셀은 데이터 종류에 따라 그려진다(문자는 왼쪽, 숫자는 오른쪽). 조회는 명시 지정된 값만 돌려주므로 기본 상태에서는 값이 없다.
4282
+ * Horizontal cell alignment passed to `Range.setHorizontalAlign`.
4283
+ * A cell without an explicit alignment is drawn according to its data type (text on the left, numbers on the right). Getters return only explicitly set values, so a cell in its default state has no value.
4294
4284
  */
4295
4285
  const HorizontalAlign: {
4286
+ /** Left alignment. */
4296
4287
  readonly LEFT: "left";
4288
+ /** Center alignment. */
4297
4289
  readonly CENTER: "center";
4290
+ /** Right alignment. */
4298
4291
  readonly RIGHT: "right";
4292
+ /** Justified. */
4299
4293
  readonly JUSTIFY: "justify";
4294
+ /** Distributed. */
4300
4295
  readonly DISTRIBUTED: "distributed";
4301
4296
  };
4302
4297
  type HorizontalAlign = typeof HorizontalAlign[keyof typeof HorizontalAlign];
4303
4298
  /**
4304
- * `Range.setVerticalAlign` 에 넘기는 셀 세로 정렬이다.
4305
- *
4306
- * 지정하지 않은 셀은 아래쪽으로 그려진다. 조회는 명시 지정된 값만 돌려준다.
4299
+ * Vertical cell alignment passed to `Range.setVerticalAlign`.
4300
+ * A cell without an explicit alignment is drawn at the bottom. Getters return only explicitly set values.
4307
4301
  */
4308
4302
  const VerticalAlign: {
4303
+ /** Top alignment. */
4309
4304
  readonly TOP: "top";
4305
+ /** Center alignment. */
4310
4306
  readonly CENTER: "center";
4307
+ /** Bottom alignment. */
4311
4308
  readonly BOTTOM: "bottom";
4309
+ /** Justified. */
4312
4310
  readonly JUSTIFY: "justify";
4313
4311
  };
4314
4312
  type VerticalAlign = typeof VerticalAlign[keyof typeof VerticalAlign];
4315
4313
  /**
4316
- * `Range.setBorder` 의 첫 인자로 넘기는 테두리 적용 위치다.
4317
- *
4318
- * 값은 모델 어휘(`Constants.ot.BORDER_TYPE_*`)와 같은 문자열이다.
4314
+ * Border position passed as the type argument to `Range.setBorder`.
4315
+ * The values are the same strings as the model vocabulary (`Constants.ot.BORDER_TYPE_*`).
4319
4316
  */
4320
4317
  const BorderType: {
4321
- /** 바깥 네 변과 내부 선 전체 */
4318
+ /** All four outer edges and all inner lines. */
4322
4319
  readonly ALL: "all";
4323
- /** 바깥 네 변 */
4320
+ /** The four outer edges. */
4324
4321
  readonly RECTANGLE: "rectangle";
4325
- /** 내부의 가로선과 세로선 */
4322
+ /** Inner horizontal and vertical lines. */
4326
4323
  readonly CROSS: "cross";
4327
- /** 위쪽 변 */
4324
+ /** Top edge. */
4328
4325
  readonly TOP: "top";
4329
- /** 아래쪽 변 */
4326
+ /** Bottom edge. */
4330
4327
  readonly BOTTOM: "bottom";
4331
- /** 왼쪽 변 */
4328
+ /** Left edge. */
4332
4329
  readonly LEFT: "left";
4333
- /** 오른쪽 변 */
4330
+ /** Right edge. */
4334
4331
  readonly RIGHT: "right";
4335
- /** 내부의 세로선 */
4332
+ /** Inner vertical lines. */
4336
4333
  readonly CENTER: "center";
4337
- /** 내부의 가로선 */
4334
+ /** Inner horizontal lines. */
4338
4335
  readonly MIDDLE: "middle";
4339
- /** 방향이 정해지지 않아 테두리가 그려지지 않는다. 대각선은 DIAGONAL_UP·DIAGONAL_DOWN·DIAGONAL_CROSS 로 지정한다 */
4336
+ /** Draws no border because no direction is specified. Specify a diagonal with DIAGONAL_UP, DIAGONAL_DOWN, or DIAGONAL_CROSS. */
4340
4337
  readonly DIAGONAL: "diagonal";
4341
- /** 각 셀의 왼쪽 아래에서 오른쪽 위로 긋는 대각선 */
4338
+ /** Diagonal line from the bottom-left to the top-right of each cell. */
4342
4339
  readonly DIAGONAL_UP: "diagonal_up";
4343
- /** 각 셀의 왼쪽 위에서 오른쪽 아래로 긋는 대각선 */
4340
+ /** Diagonal line from the top-left to the bottom-right of each cell. */
4344
4341
  readonly DIAGONAL_DOWN: "diagonal_down";
4345
- /** 각 셀의 대각선 두 방향 */
4342
+ /** Both diagonal lines of each cell. */
4346
4343
  readonly DIAGONAL_CROSS: "diagonal_cross";
4347
- /** 테두리 제거. 선 스타일과 색은 무시된다 */
4344
+ /** Removes borders. The line style and color are ignored. */
4348
4345
  readonly NONE: "none";
4349
4346
  };
4350
4347
  type BorderType = typeof BorderType[keyof typeof BorderType];
4351
4348
  /**
4352
- * `Range.setBorder` 의 두 번째 인자로 넘기는 테두리 선 스타일이다. 생략하면 `THIN` 이다.
4353
- *
4354
- * 값은 렌더러가 아는 선 스타일 전부(`view/util/borderStyleUtils.js` 의 우선순위 목록 · 조건부 서식이 쓰는 `controller/dxfStyle.js` 의 `CF_PROFILE.border.styles`)와 같아야 한다. 목록 밖의 문자열은 검증 없이 저장되고 화면에는 테두리가 지정한 모양으로 그려지지 않는다.
4355
- * 생성기가 객체 리터럴만 읽으므로 그 목록에서 파생할 수 없다. 대신 dispatch 테스트가 어긋남을 잡는다.
4349
+ * Border line style passed as the lineStyle argument to `Range.setBorder`. If omitted, `THIN` is used.
4350
+ * The values must match every line style the renderer supports (the priority list in `view/util/borderStyleUtils.js` and `CF_PROFILE.border.styles` in `controller/dxfStyle.js`, used by conditional formatting). A value not in this list is rejected with an error, and if a value the renderer does not support is added to this list, the border is not drawn in the specified style.
4351
+ * Because the generator reads only object literals, this list cannot be derived from those lists. Instead, dispatch tests catch any mismatch.
4356
4352
  */
4357
4353
  const BorderLineStyle: {
4354
+ /** Hairline. */
4358
4355
  readonly HAIR: "hair";
4356
+ /** Thin solid line. */
4359
4357
  readonly THIN: "thin";
4358
+ /** Medium solid line. */
4360
4359
  readonly MEDIUM: "medium";
4360
+ /** Thick solid line. */
4361
4361
  readonly THICK: "thick";
4362
+ /** Double line. */
4362
4363
  readonly DOUBLE: "double";
4364
+ /** Thin dotted line. */
4363
4365
  readonly DOTTED: "dotted";
4366
+ /** Thin dashed line. */
4364
4367
  readonly DASHED: "dashed";
4368
+ /** Thin dash-dot line. */
4365
4369
  readonly DASH_DOT: "dashDot";
4370
+ /** Thin dash-dot-dot line. */
4366
4371
  readonly DASH_DOT_DOT: "dashDotDot";
4372
+ /** Medium dashed line. */
4367
4373
  readonly MEDIUM_DASHED: "mediumDashed";
4374
+ /** Medium dash-dot line. */
4368
4375
  readonly MEDIUM_DASH_DOT: "mediumDashDot";
4376
+ /** Medium dash-dot-dot line. */
4369
4377
  readonly MEDIUM_DASH_DOT_DOT: "mediumDashDotDot";
4378
+ /** Medium slanted dash-dot line. */
4370
4379
  readonly SLANT_DASH_DOT: "slantDashDot";
4380
+ /** No line. In setBorder, clears the existing lines at the position specified by type. */
4371
4381
  readonly NONE: "none";
4372
4382
  };
4373
4383
  type BorderLineStyle = typeof BorderLineStyle[keyof typeof BorderLineStyle];
4374
- /** `Range.sort` 와 `Filter.sort` 에 넘기는 정렬 방향이다. */
4384
+ /**
4385
+ * Sort order passed to `Range.sort` and `Filter.sort`.
4386
+ * Text is compared case-insensitively, and numbers stored as text are treated as text. Empty cells are always placed last, regardless of the order.
4387
+ */
4375
4388
  const SortOrder: {
4389
+ /** Ascending. Numbers come before text. */
4376
4390
  readonly ASCENDING: "asc";
4391
+ /** Descending. Text comes before numbers. */
4377
4392
  readonly DESCENDING: "desc";
4378
4393
  };
4379
4394
  type SortOrder = typeof SortOrder[keyof typeof SortOrder];
4380
- /**
4381
- * `Range.setHyperlink` 의 `options.type` 에 넘기는 하이퍼링크 종류다.
4382
- *
4383
- * `BOOK` 은 같은 문서 안의 위치로 이동하는 링크이며 `location` 에 시트·범위를 준다.
4384
- */
4395
+ /** Hyperlink type passed as `type` to `Range.setHyperlink`. */
4385
4396
  const HyperlinkType: {
4397
+ /** Link that opens a web address. */
4386
4398
  readonly WEB: "web";
4399
+ /** Link that opens a new email to an email address. */
4387
4400
  readonly EMAIL: "email";
4401
+ /** Link that moves to a location in the same document. Pass a sheet and range in location. */
4388
4402
  readonly BOOK: "book";
4389
4403
  };
4390
4404
  type HyperlinkType = typeof HyperlinkType[keyof typeof HyperlinkType];
4391
4405
  /**
4392
- * `Range.setDataValidation` 의 `rule.type` 에 넘기는 데이터 유효성 규칙 종류다.
4393
- *
4394
- * `ANY` 는 입력을 제한하지 않고 안내 메시지만 붙이는 종류이므로 수식이 필요 없다.
4395
- * `LIST` 는 `formula1` 에 콤마 목록(`=` 없이) 또는 단일 열·행 범위 참조(`=` 필수)를 받고, `CUSTOM` 은 불리언 수식을 받는다. 나머지는 `operator` 와 짝으로 경계값을 받는다.
4406
+ * Data validation rule type passed as `rule.type` to `Range.setDataValidation`.
4407
+ * Types other than `ANY`, `LIST`, and `CUSTOM` take boundary values paired with `operator`.
4396
4408
  */
4397
4409
  const DataValidationType: {
4410
+ /** Does not restrict input and only attaches an input message. No formula is needed. */
4398
4411
  readonly ANY: "any";
4412
+ /** Accepts only values in a list. Pass a comma-separated list or a reference to a single-column or single-row range in formula1. */
4399
4413
  readonly LIST: "list";
4414
+ /** Accepts whole numbers only. */
4400
4415
  readonly WHOLE: "whole";
4416
+ /** Accepts numbers, including decimals. */
4401
4417
  readonly DECIMAL: "decimal";
4418
+ /** Accepts dates. */
4402
4419
  readonly DATE: "date";
4420
+ /** Accepts times. */
4403
4421
  readonly TIME: "time";
4422
+ /** Restricts input by text length. */
4404
4423
  readonly TEXT_LENGTH: "textLength";
4424
+ /** Accepts only input for which the Boolean formula in formula1 is true. */
4405
4425
  readonly CUSTOM: "custom";
4406
4426
  };
4407
4427
  type DataValidationType = typeof DataValidationType[keyof typeof DataValidationType];
4408
4428
  /**
4409
- * `Range.setDataValidation` 의 `rule.operator` 에 넘기는 데이터 유효성 비교 연산자다.
4410
- *
4411
- * 숫자·날짜·시간·길이 종류에서만 쓴다. `BETWEEN`/`NOT_BETWEEN` 은 `formula2` 로 두 번째 경계를 함께 받는다.
4429
+ * Data validation comparison operator passed as `rule.operator` to `Range.setDataValidation`.
4430
+ * Used only with the number, date, time, and length types. `BETWEEN`/`NOT_BETWEEN` also take the second boundary in `formula2`.
4412
4431
  */
4413
4432
  const DataValidationOperator: {
4433
+ /** Accepts only values greater than or equal to formula1 and less than or equal to formula2. */
4414
4434
  readonly BETWEEN: "between";
4435
+ /** Accepts only values less than formula1 or greater than formula2. */
4415
4436
  readonly NOT_BETWEEN: "notBetween";
4437
+ /** Accepts only values equal to formula1. */
4416
4438
  readonly EQUAL: "equal";
4439
+ /** Accepts only values not equal to formula1. */
4417
4440
  readonly NOT_EQUAL: "notEqual";
4441
+ /** Accepts only values less than formula1. */
4418
4442
  readonly LESS_THAN: "lessThan";
4443
+ /** Accepts only values less than or equal to formula1. */
4419
4444
  readonly LESS_THAN_OR_EQUAL: "lessThanOrEqual";
4445
+ /** Accepts only values greater than formula1. */
4420
4446
  readonly GREATER_THAN: "greaterThan";
4447
+ /** Accepts only values greater than or equal to formula1. */
4421
4448
  readonly GREATER_THAN_OR_EQUAL: "greaterThanOrEqual";
4422
4449
  };
4423
4450
  type DataValidationOperator = typeof DataValidationOperator[keyof typeof DataValidationOperator];
4424
- /**
4425
- * `Range.setDataValidation` 의 `rule.errorStyle` 에 넘기는 데이터 유효성 위반 시 오류 표시 방식이다. 생략하면 `STOP` 이다.
4426
- *
4427
- * `STOP` 은 입력을 거부하고, `WARNING`/`INFORMATION` 은 경고 후 입력을 허용한다.
4428
- */
4451
+ /** Error alert style for data validation violations, passed as `rule.errorStyle` to `Range.setDataValidation`. If omitted, `STOP` is used. */
4429
4452
  const DataValidationErrorStyle: {
4453
+ /** Rejects input that does not match the rule. */
4430
4454
  readonly STOP: "stop";
4455
+ /** Shows a warning and allows the input if the user accepts. */
4431
4456
  readonly WARNING: "warning";
4457
+ /** Shows an information message and allows the input unless the user cancels. */
4432
4458
  readonly INFORMATION: "information";
4433
4459
  };
4434
4460
  type DataValidationErrorStyle = typeof DataValidationErrorStyle[keyof typeof DataValidationErrorStyle];
4435
4461
  /**
4436
- * `Range.addConditionalFormat` 의 `rule.type` 에 넘기는 조건부 서식 규칙 종류다.
4437
- *
4438
- * `CELL_IS` 는 `operator` + 경계값, `EXPRESSION` 은 불리언 수식, 텍스트 계열은 비교 문자열, `TOP10` 은 순위(`rank`), `TIME_PERIOD` 는 기간 토큰을 함께 받는다. 여기까지는 수식 계열로 강조 서식을 `style` 로 직접 지정한다.
4439
- *
4440
- * `COLOR_SCALE`/`DATA_BAR`/`ICON_SET` 은 시각 규칙이라 `style` 을 받지 않고 색 목록 또는 프리셋 식별자와 임계값(`cfvo`)으로 서술한다.
4462
+ * Conditional format rule type passed as `rule.type` to `Range.addConditionalFormat`.
4463
+ * `COLOR_SCALE`, `DATA_BAR`, and `ICON_SET` are visual rules that draw cells according to their values, so they do not take `style`. The other types apply the highlight format in `style` to cells that meet the condition.
4441
4464
  */
4442
4465
  const ConditionalFormatRuleType: {
4466
+ /** Compares the cell value with boundary values using operator. */
4443
4467
  readonly CELL_IS: "cellIs";
4468
+ /** Cells for which the formula in formula1 is true. */
4444
4469
  readonly EXPRESSION: "expression";
4470
+ /** Cells that contain the string in text. */
4445
4471
  readonly CONTAINS_TEXT: "containsText";
4472
+ /** Cells that do not contain the string in text. */
4446
4473
  readonly NOT_CONTAINS_TEXT: "notContainsText";
4474
+ /** Cells that begin with the string in text. */
4447
4475
  readonly BEGINS_WITH: "beginsWith";
4476
+ /** Cells that end with the string in text. */
4448
4477
  readonly ENDS_WITH: "endsWith";
4478
+ /** Cells that are empty or contain only spaces. */
4449
4479
  readonly CONTAINS_BLANKS: "containsBlanks";
4480
+ /** Cells that contain a character other than a space. */
4450
4481
  readonly NOT_CONTAINS_BLANKS: "notContainsBlanks";
4482
+ /** Cells whose value is an error. */
4451
4483
  readonly CONTAINS_ERRORS: "containsErrors";
4484
+ /** Cells whose value is not an error. */
4452
4485
  readonly NOT_CONTAINS_ERRORS: "notContainsErrors";
4486
+ /** Cells whose value ranks within the top rank in the applied range. If bottom is set, picks from the smallest values instead. */
4453
4487
  readonly TOP10: "top10";
4488
+ /** Cells whose value is above the average of the applied range. */
4454
4489
  readonly ABOVE_AVERAGE: "aboveAverage";
4490
+ /** Cells whose value is below the average of the applied range. */
4455
4491
  readonly BELOW_AVERAGE: "belowAverage";
4492
+ /** Cells whose value appears more than once in the applied range. */
4456
4493
  readonly DUPLICATE_VALUES: "duplicateValues";
4494
+ /** Cells whose value appears only once in the applied range. */
4457
4495
  readonly UNIQUE_VALUES: "uniqueValues";
4496
+ /** Cells whose date falls within the period in timePeriod. */
4458
4497
  readonly TIME_PERIOD: "timePeriod";
4498
+ /** Fills cells with the scale colors in colors according to their values. */
4459
4499
  readonly COLOR_SCALE: "colorScale";
4500
+ /** Draws a bar in each cell according to its value. The bar appearance is set by the dataBar preset. */
4460
4501
  readonly DATA_BAR: "dataBar";
4502
+ /** Adds an icon from iconSet to each cell according to its value. */
4461
4503
  readonly ICON_SET: "iconSet";
4462
4504
  };
4463
4505
  type ConditionalFormatRuleType = typeof ConditionalFormatRuleType[keyof typeof ConditionalFormatRuleType];
4464
4506
  /**
4465
- * `cellIs` 규칙의 `operator` 에 넘기는 조건부 서식 비교 연산자다.
4466
- *
4467
- * `BETWEEN`/`NOT_BETWEEN` 은 `formula2` 로 두 번째 경계를 함께 받는다.
4507
+ * Conditional format comparison operator passed as `operator` in a `cellIs` rule.
4508
+ * `BETWEEN`/`NOT_BETWEEN` also take the second boundary in `formula2`, and the smaller of the two boundaries is treated as the lower boundary.
4509
+ * Text values are compared with each other case-insensitively.
4468
4510
  */
4469
4511
  const ConditionalFormatOperator: {
4512
+ /** Cells whose value is equal to formula1. */
4470
4513
  readonly EQUAL: "equal";
4514
+ /** Cells whose value is not equal to formula1. */
4471
4515
  readonly NOT_EQUAL: "notEqual";
4516
+ /** Cells whose value is between the two boundaries. The boundary values are included. */
4472
4517
  readonly BETWEEN: "between";
4518
+ /** Cells whose value is outside the two boundaries. The boundary values are not included. */
4473
4519
  readonly NOT_BETWEEN: "notBetween";
4520
+ /** Cells whose value is greater than formula1. */
4474
4521
  readonly GREATER_THAN: "greaterThan";
4522
+ /** Cells whose value is greater than or equal to formula1. */
4475
4523
  readonly GREATER_THAN_OR_EQUAL: "greaterThanOrEqual";
4524
+ /** Cells whose value is less than formula1. */
4476
4525
  readonly LESS_THAN: "lessThan";
4526
+ /** Cells whose value is less than or equal to formula1. */
4477
4527
  readonly LESS_THAN_OR_EQUAL: "lessThanOrEqual";
4478
4528
  };
4479
4529
  type ConditionalFormatOperator = typeof ConditionalFormatOperator[keyof typeof ConditionalFormatOperator];
4480
4530
  /**
4481
- * 규칙 종류가 `timePeriod` 일 때 `rule.timePeriod` 에 넘기는 기간 토큰이다.
4482
- *
4483
- * 기준일은 문서를 여는 시점의 오늘 날짜이므로 규칙이 가리키는 셀 집합은 날짜가 바뀌면 달라진다.
4531
+ * Period token passed as `rule.timePeriod` when the rule type is `timePeriod`.
4532
+ * The reference date is today's date at the time the document is opened, so the set of cells the rule applies to changes when the date changes. A week runs from Sunday to Saturday.
4484
4533
  */
4485
4534
  const ConditionalFormatTimePeriod: {
4535
+ /** Yesterday. */
4486
4536
  readonly YESTERDAY: "yesterday";
4537
+ /** Today. */
4487
4538
  readonly TODAY: "today";
4539
+ /** Tomorrow. */
4488
4540
  readonly TOMORROW: "tomorrow";
4541
+ /** The last 7 days, including today. */
4489
4542
  readonly LAST_7_DAYS: "last7Days";
4543
+ /** Last week. */
4490
4544
  readonly LAST_WEEK: "lastWeek";
4545
+ /** This week. */
4491
4546
  readonly THIS_WEEK: "thisWeek";
4547
+ /** Next week. */
4492
4548
  readonly NEXT_WEEK: "nextWeek";
4549
+ /** Last month. */
4493
4550
  readonly LAST_MONTH: "lastMonth";
4551
+ /** This month. */
4494
4552
  readonly THIS_MONTH: "thisMonth";
4553
+ /** Next month. */
4495
4554
  readonly NEXT_MONTH: "nextMonth";
4496
4555
  };
4497
4556
  type ConditionalFormatTimePeriod = typeof ConditionalFormatTimePeriod[keyof typeof ConditionalFormatTimePeriod];
4498
- /**
4499
- * `cfvo[].type` 에 넘기는 조건부 서식 시각 규칙 임계값의 기준이다.
4500
- *
4501
- * `NUM`/`PERCENT`/`PERCENTILE`/`FORMULA` 는 `formula` 로 값을 함께 받고, `MIN`/`MAX` 는 범위의 최소·최대를 쓴다. `AUTO_MIN`/`AUTO_MAX` 는 데이터 막대 프리셋의 기본 임계값이라 조회에만 나오고 입력은 받지 않는다.
4502
- */
4557
+ /** Threshold type for conditional format visual rules, passed as `cfvo[].type`. */
4503
4558
  const ConditionalFormatValueType: {
4559
+ /** Number given in formula. */
4504
4560
  readonly NUM: "num";
4561
+ /** Minimum value in the range. */
4505
4562
  readonly MIN: "min";
4563
+ /** Maximum value in the range. */
4506
4564
  readonly MAX: "max";
4565
+ /** Percentage, where the span from the minimum to the maximum is 100. Give the value in formula. */
4507
4566
  readonly PERCENT: "percent";
4567
+ /** Percentile. Give the value in formula. */
4508
4568
  readonly PERCENTILE: "percentile";
4569
+ /** Result of the formula given in formula. */
4509
4570
  readonly FORMULA: "formula";
4571
+ /** Default minimum threshold of a data bar preset. Appears only in getter results and is not accepted as input. */
4510
4572
  readonly AUTO_MIN: "autoMin";
4573
+ /** Default maximum threshold of a data bar preset. Appears only in getter results and is not accepted as input. */
4511
4574
  readonly AUTO_MAX: "autoMax";
4512
4575
  };
4513
4576
  type ConditionalFormatValueType = typeof ConditionalFormatValueType[keyof typeof ConditionalFormatValueType];
4514
4577
  /**
4515
- * `Filter.applyFilter` 의 `criteria.filterType` 에 넘기는 필터 조건 종류다.
4516
- *
4517
- * 종류에 따라 criteria 의 나머지 필드가 달라진다. `VALUES` 는 표시할 값 목록을, `CUSTOM` 은 조건식 1~2개를, `TOP10` 은 개수나 비율을, `DYNAMIC` 은 평균 기준 토큰을 함께 받는다.
4518
- *
4519
- * `Filter.getInfo` 의 `columns[].filterType` 도 같은 어휘다. 단 단일 `EQUAL` 조건으로 적용한 `CUSTOM` 은 모델에서 값 목록으로 저장되어 조회 시 `VALUES` 로 나온다.
4578
+ * Filter criteria type passed as `criteria.filterType` to `Filter.applyFilter`.
4579
+ * The remaining fields of criteria depend on the type.
4580
+ * `columns[].filterType` of `Filter.getInfo` uses the same values. However, `CUSTOM` applied with a single `EQUAL` condition is returned as `VALUES`.
4520
4581
  */
4521
4582
  const FilterType: {
4583
+ /** Keeps only rows whose value is in the list of values to show. */
4522
4584
  readonly VALUES: "values";
4585
+ /** Keeps only rows that match one or two conditions. */
4523
4586
  readonly CUSTOM: "custom";
4587
+ /** Keeps only rows picked from the largest or smallest values by count or percentage. */
4524
4588
  readonly TOP10: "top10";
4589
+ /** Keeps only rows picked relative to the column average. The criterion is a FilterDynamicType value. */
4525
4590
  readonly DYNAMIC: "dynamic";
4526
4591
  };
4527
4592
  type FilterType = typeof FilterType[keyof typeof FilterType];
4528
4593
  /**
4529
- * `custom` criteria 의 `conditions[].operator` 에 넘기는 사용자 지정 필터 조건식의 연산자다.
4530
- *
4531
- * `EQUAL` 은 단일 조건에서만 쓸 수 있다(두 조건 조합에서는 지원하지 않는다).
4532
- * "사이"·"사이 제외" 는 별도 연산자가 아니라 두 조건의 AND·OR 조합으로 표현한다.
4594
+ * Operator of a custom filter condition, passed as `conditions[].operator` in `custom` criteria.
4595
+ * `EQUAL` can be used only in a single condition (it is not supported in a combination of two conditions).
4596
+ * "Between" and "not between" are not separate operators. Express them as an AND or OR combination of two conditions.
4597
+ * Text is compared case-insensitively, with leading and trailing spaces removed.
4598
+ * `BEGINS_WITH`, `ENDS_WITH`, `CONTAINS`, and their negated forms do not support wildcards (`*`, `?`). Number cells and empty cells are filtered out by the positive forms and kept by the negated forms.
4533
4599
  */
4534
4600
  const FilterOperator: {
4601
+ /** Rows whose value is equal to value. */
4535
4602
  readonly EQUAL: "equal";
4603
+ /** Rows whose value is not equal to value. Rows with an empty cell are also kept. */
4536
4604
  readonly NOT_EQUAL: "notEqual";
4605
+ /** Rows whose value is greater than value. */
4537
4606
  readonly GREATER_THAN: "greaterThan";
4607
+ /** Rows whose value is greater than or equal to value. */
4538
4608
  readonly GREATER_OR_EQUAL: "greaterOrEqual";
4609
+ /** Rows whose value is less than value. */
4539
4610
  readonly LESS_THAN: "lessThan";
4611
+ /** Rows whose value is less than or equal to value. */
4540
4612
  readonly LESS_OR_EQUAL: "lessOrEqual";
4613
+ /** Rows that begin with value. */
4541
4614
  readonly BEGINS_WITH: "beginsWith";
4615
+ /** Rows that do not begin with value. */
4542
4616
  readonly NOT_BEGINS_WITH: "notBeginsWith";
4617
+ /** Rows that end with value. */
4543
4618
  readonly ENDS_WITH: "endsWith";
4619
+ /** Rows that do not end with value. */
4544
4620
  readonly NOT_ENDS_WITH: "notEndsWith";
4621
+ /** Rows that contain value. */
4545
4622
  readonly CONTAINS: "contains";
4623
+ /** Rows that do not contain value. */
4546
4624
  readonly NOT_CONTAINS: "notContains";
4547
4625
  };
4548
4626
  type FilterOperator = typeof FilterOperator[keyof typeof FilterOperator];
4549
- /** `dynamic` criteria 의 `type` 에 넘기는 동적 필터의 기준이다. */
4627
+ /** Dynamic filter criterion passed as `type` in `dynamic` criteria. */
4550
4628
  const FilterDynamicType: {
4629
+ /** Rows whose value is above the column average. */
4551
4630
  readonly ABOVE_AVERAGE: "aboveAverage";
4631
+ /** Rows whose value is below the column average. */
4552
4632
  readonly BELOW_AVERAGE: "belowAverage";
4553
4633
  };
4554
4634
  type FilterDynamicType = typeof FilterDynamicType[keyof typeof FilterDynamicType];
4555
4635
  interface RangeCoords {
4556
- /** 영역이 시작하는 행(0-based) */
4636
+ /** row where the range starts (0-based) */
4557
4637
  row1: number;
4558
- /** 영역이 시작하는 열(0-based) */
4638
+ /** column where the range starts (0-based) */
4559
4639
  col1: number;
4560
- /** 영역이 끝나는 행(0-based). col2 와 함께 생략하면 row1·col1 이 가리키는 단일 셀이 된다 */
4640
+ /** row where the range ends (0-based). If omitted together with col2, the range is the single cell at row1 and col1 */
4561
4641
  row2?: number;
4562
- /** 영역이 끝나는 열(0-based). row2 와 함께 생략하면 row1·col1 이 가리키는 단일 셀이 된다 */
4642
+ /** column where the range ends (0-based). If omitted together with row2, the range is the single cell at row1 and col1 */
4563
4643
  col2?: number;
4564
4644
  }
4565
4645
  interface SheetRangeCoords {
4646
+ /** sheet index (0-based) */
4566
4647
  sheetIndex: number;
4648
+ /** row where the range starts (0-based) */
4567
4649
  row1: number;
4650
+ /** column where the range starts (0-based) */
4568
4651
  col1: number;
4652
+ /** row where the range ends (0-based) */
4569
4653
  row2: number;
4654
+ /** column where the range ends (0-based) */
4570
4655
  col2: number;
4571
4656
  }
4572
4657
  interface CommandResult {
4573
- /** 이번 실행을 되돌릴 수 있는지 여부 */
4658
+ /** whether this operation can be undone */
4574
4659
  undoable: boolean;
4575
- /** 되돌리기 기록이 모두 지워졌는지 여부 */
4660
+ /** whether the undo history was cleared */
4576
4661
  undoBufferCleared: boolean;
4577
4662
  }
4578
4663
  interface SheetSummary {
4664
+ /** sheet name */
4579
4665
  name: string;
4580
- /** 활성 시트 여부 */
4666
+ /** whether the sheet is the active sheet */
4581
4667
  active: boolean;
4582
4668
  }
4583
4669
  interface SheetRef {
4584
- /** 0-based 시트 인덱스 */
4670
+ /** sheet index (0-based) */
4585
4671
  sheetIndex: number;
4672
+ /** sheet name */
4586
4673
  sheetName: string;
4587
4674
  }
4588
4675
  interface DocumentProperties {
4589
- /** 문서를 만든 애플리케이션 이름 ("Cell" 등) */
4676
+ /** name of the application that created the document (such as "Cell") */
4590
4677
  application: string | undefined;
4591
- /** 문서 작성자 */
4678
+ /** author of the document */
4592
4679
  creator: string | undefined;
4593
- /** 문서 생성 일시. 날짜 문자열이거나 epoch 밀리초다 */
4680
+ /** date and time the document was created. A date string or epoch milliseconds */
4594
4681
  created: string | number | undefined;
4595
- /** 마지막 저장 일시. created 와 같은 형식 */
4682
+ /** date and time the document was last saved. Same format as created */
4596
4683
  lastModified: string | number | undefined;
4597
- /** 문서 포맷 ("xlsx", "ods", "xls") */
4684
+ /** document format ("xlsx", "ods", "xls") */
4598
4685
  fileType: string;
4599
- /** 문서 로캘 ("ko_KR") */
4686
+ /** document locale ("ko_KR") */
4600
4687
  locale: string;
4601
4688
  }
4602
4689
  interface FreezePanes {
4603
- /** 고정된 상단 행 수. 고정하지 않았으면 0 이다 */
4690
+ /** number of frozen rows at the top. 0 if not frozen */
4604
4691
  rows: number;
4605
- /** 고정된 좌측 열 수. 고정하지 않았으면 0 이다 */
4692
+ /** number of frozen columns on the left. 0 if not frozen */
4606
4693
  cols: number;
4607
4694
  }
4608
4695
  interface SheetInfo {
4609
- /** 시트 이름 */
4696
+ /** sheet name */
4610
4697
  name: string;
4611
- /** 숨김 여부 */
4698
+ /** whether the sheet is hidden */
4612
4699
  hidden: boolean;
4613
- /** 탭 색("#RRGGBB"). 색을 지정하지 않았으면 빈 문자열 */
4700
+ /** tab color ("#RRGGBB"). An empty string if no color is set */
4614
4701
  tabColor: string;
4615
- /** 값이나 셀 서식이 있는 범위(A1 표기). 값도 셀 서식도 없는 시트에서는 null */
4702
+ /** range that contains values or cell formats (A1 notation). null for a sheet with no values or cell formats */
4616
4703
  usedRange: string | null;
4617
- /** 선택 영역(A1 표기) */
4704
+ /** selection (A1 notation) */
4618
4705
  selection: string;
4619
- /** 틀 고정 상태 */
4706
+ /** freeze panes state */
4620
4707
  freezePanes: FreezePanes;
4621
- /** 눈금선 표시 여부 */
4708
+ /** whether gridlines are shown */
4622
4709
  gridlinesVisible: boolean;
4623
- /** 화면 확대 배율(1 이 100%) */
4710
+ /** zoom factor (1 is 100%) */
4624
4711
  zoom: number;
4625
4712
  }
4626
4713
  interface SelectionInfo {
4627
- /** 시트 이름 */
4714
+ /** sheet name */
4628
4715
  sheet: string;
4629
- /** A1 표기 문자열 */
4716
+ /** A1 notation string */
4630
4717
  selection: string;
4631
4718
  }
4632
4719
  interface AddChartOptions {
4633
- /** 시리즈 방향. rows 는 행 하나가 시리즈 하나, columns 는 열 하나가 시리즈 하나이며, 생략하면 데이터 모양에 따라 정한다. 분산형·거품형은 방향을 지정할 수 없다 */
4720
+ /** series direction. With rows, each row is one series, and with columns, each column is one series. If omitted, the direction is determined by the shape of the data. The direction cannot be specified for scatter and bubble charts */
4634
4721
  seriesBy?: "auto" | "rows" | "columns";
4635
4722
  }
4636
4723
  interface ChartInfo {
4637
- /** 차트를 식별하는 고유 ID */
4724
+ /** unique ID that identifies the chart */
4638
4725
  oid: string;
4639
- /** 차트 종류 */
4640
- type: ChartType;
4641
- /** 차트 제목 */
4726
+ /** chart type. Same value as getType */
4727
+ type: ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown";
4728
+ /** chart title */
4642
4729
  title: string;
4643
- /** 범례 위치 */
4730
+ /** legend position */
4644
4731
  legendPosition: ChartLegendPosition;
4645
- /** 데이터레이블 위치 */
4646
- dataLabelPosition: ChartDataLabelPosition;
4647
- /** 축별 축 제목. null 은 그 차트 종류에 해당 축의 제목이 아예 없다는 뜻이다 */
4732
+ /** data label position. null means the chart type has no data labels */
4733
+ dataLabelPosition: ChartDataLabelPosition | null;
4734
+ /** axis title for each axis. null means the chart type has no title for that axis */
4648
4735
  axisTitle: {
4649
4736
  horizontal: string | null;
4650
4737
  vertical: string | null;
4651
4738
  };
4652
- /** 축별 눈금선. null 은 그 차트 종류에 해당 축의 눈금선이 아예 없다는 뜻이고, "none" 은 쓸 수는 있지만 꺼져 있다는 뜻이다 */
4739
+ /** gridlines for each axis. null means the chart type has no gridlines for that axis, and "none" means gridlines are available but turned off */
4653
4740
  gridLine: {
4654
4741
  horizontal: ChartGridLineType | null;
4655
4742
  vertical: ChartGridLineType | null;
4656
4743
  };
4657
- /** 데이터 범위. 시트명을 포함한 A1 표기다("Sheet1!A1:C5"). 하나의 사각 범위로 묶이지 않으면 null */
4744
+ /** data range, in A1 notation including the sheet name ("Sheet1!A1:C5"). null if it cannot be combined into a single rectangular range */
4658
4745
  range: string | null;
4659
4746
  }
4660
4747
  interface ConditionalFormatPriorityMove {
4661
- /** 옮길 규칙의 현재 우선순위 */
4748
+ /** current priority of the rule to move */
4662
4749
  priority: number;
4663
- /** 옮겨 놓을 우선순위 */
4750
+ /** priority to move the rule to */
4664
4751
  to: number;
4665
4752
  }
4666
4753
  interface ConditionalFormatRangeSet {
4667
- /** 대상 규칙의 현재 우선순위 */
4754
+ /** current priority of the target rule */
4668
4755
  priority: number;
4669
- /** 바꿀 적용 영역. 콤마로 이어 붙인 A1 표기 문자열("A1:B2,D4:E5")로도 지정할 수 있으며, 문자열 배열과 빈 배열은 받지 않는다 */
4756
+ /** new applied ranges. A comma-separated A1 notation string ("A1:B2,D4:E5") is also accepted. Arrays of strings and empty arrays are not accepted */
4670
4757
  ranges: string | RangeCoords[];
4671
4758
  }
4672
4759
  interface ConditionalFormatUpdate {
4673
- /** 삭제할 규칙의 우선순위 목록 */
4760
+ /** priorities of the rules to delete */
4674
4761
  deletes?: number[];
4675
- /** 규칙별로 바꿀 적용 영역 */
4762
+ /** new applied ranges for each rule */
4676
4763
  setRanges?: ConditionalFormatRangeSet[];
4677
- /** 우선순위 이동. 한 번에 한 건만 지정할 수 있다 */
4764
+ /** priority move. Only one move can be specified at a time */
4678
4765
  movePriority?: ConditionalFormatPriorityMove;
4679
4766
  }
4680
4767
  interface ConditionalFormatFont {
4681
- /** 굵게 여부 */
4768
+ /** whether the font is bold */
4682
4769
  bold?: boolean;
4683
- /** 기울임 여부 */
4770
+ /** whether the font is italic */
4684
4771
  italic?: boolean;
4685
- /** 취소선 여부 */
4772
+ /** whether strikethrough is applied */
4686
4773
  strikethrough?: boolean;
4687
- /** 밑줄 종류 */
4774
+ /** underline type */
4688
4775
  underline?: "single" | "double" | "singleAccounting" | "doubleAccounting" | "none";
4689
- /** 글꼴 색 "#RRGGBB" */
4776
+ /** font color "#RRGGBB" */
4690
4777
  color?: string;
4691
- /** 글꼴 크기(pt). 현재는 조회만 지원한다 */
4778
+ /** font size (pt). Currently read-only */
4692
4779
  size?: number;
4693
- /** 글꼴 이름. 현재는 조회만 지원한다 */
4780
+ /** font name. Currently read-only */
4694
4781
  name?: string;
4695
4782
  }
4696
4783
  interface ConditionalFormatGradientStop {
4697
- /** 0~1 사이의 위치 */
4784
+ /** position between 0 and 1 */
4698
4785
  position: number;
4699
- /** 그 위치의 색 "#RRGGBB" */
4786
+ /** color at that position "#RRGGBB" */
4700
4787
  color: string;
4701
4788
  }
4702
4789
  interface ConditionalFormatGradient {
4703
- /** 선형이면 true, 방사형이면 false */
4790
+ /** true for linear, false for radial */
4704
4791
  isLinear?: boolean;
4705
- /** 선형일 때의 각도 */
4792
+ /** angle of a linear gradient */
4706
4793
  degree?: number;
4707
- /** 방사형의 왼쪽 여백 비율 */
4794
+ /** left offset ratio of a radial gradient */
4708
4795
  left?: number;
4709
- /** 방사형의 오른쪽 여백 비율 */
4796
+ /** right offset ratio of a radial gradient */
4710
4797
  right?: number;
4711
- /** 방사형의 위쪽 여백 비율 */
4798
+ /** top offset ratio of a radial gradient */
4712
4799
  top?: number;
4713
- /** 방사형의 아래쪽 여백 비율 */
4800
+ /** bottom offset ratio of a radial gradient */
4714
4801
  bottom?: number;
4715
- /** 색이 바뀌는 지점 목록 */
4802
+ /** list of points where the color changes */
4716
4803
  stops?: ConditionalFormatGradientStop[];
4717
4804
  }
4718
4805
  interface ConditionalFormatFill {
4719
- /** 바탕색 "#RRGGBB". 이것만 주면 단색 채우기다 */
4806
+ /** background color "#RRGGBB". If only this is given, the fill is a solid fill */
4720
4807
  backgroundColor?: string;
4721
- /** 무늬 종류("lightGrid", "darkVertical" 등). solid·none 은 무늬가 아니다 */
4808
+ /** pattern type (such as "lightGrid" or "darkVertical"). solid and none are not patterns */
4722
4809
  patternType?: string;
4723
- /** 무늬색 "#RRGGBB". 무늬가 아닌 채우기에는 없다 */
4810
+ /** pattern color "#RRGGBB". Not present for a fill without a pattern */
4724
4811
  patternColor?: string;
4725
- /** 그라데이션 채우기. 현재는 조회만 지원한다 */
4812
+ /** gradient fill. Currently read-only */
4726
4813
  gradient?: ConditionalFormatGradient;
4727
4814
  }
4728
4815
  interface ConditionalFormatBorderLine {
4729
- /** 선 스타일. 색만 주면 가는 실선으로 그린다 */
4816
+ /** line style. If only a color is given, a thin solid line is drawn */
4730
4817
  style?: BorderLineStyle;
4731
- /** 선 색 "#RRGGBB". 선 스타일만 주면 검정으로 그린다 */
4818
+ /** line color "#RRGGBB". If only a line style is given, the line is drawn in black */
4732
4819
  color?: string;
4733
4820
  }
4734
4821
  interface ConditionalFormatBorder {
4735
- /** 네 변에 함께 줄 선 스타일. 변별 지정이 있으면 그쪽이 이긴다 */
4822
+ /** line style for all four edges. An edge-specific setting takes precedence */
4736
4823
  style?: BorderLineStyle;
4737
- /** 네 변에 함께 줄 선 색 "#RRGGBB". 변별 지정이 있으면 그쪽이 이긴다 */
4824
+ /** line color "#RRGGBB" for all four edges. An edge-specific setting takes precedence */
4738
4825
  color?: string;
4739
- /** 위쪽 변. 조회는 네 변이 같아도 각 변을 따로 준다 */
4826
+ /** top edge. Getters return each edge separately even when all four edges are the same */
4740
4827
  top?: ConditionalFormatBorderLine;
4741
- /** 아래쪽 변 */
4828
+ /** bottom edge */
4742
4829
  bottom?: ConditionalFormatBorderLine;
4743
- /** 왼쪽 변 */
4830
+ /** left edge */
4744
4831
  left?: ConditionalFormatBorderLine;
4745
- /** 오른쪽 변 */
4832
+ /** right edge */
4746
4833
  right?: ConditionalFormatBorderLine;
4747
4834
  }
4748
4835
  interface ConditionalFormatStyle {
4749
- /** 글꼴 */
4836
+ /** font */
4750
4837
  font?: ConditionalFormatFont;
4751
- /** 채우기 */
4838
+ /** fill */
4752
4839
  fill?: ConditionalFormatFill;
4753
- /** 테두리 */
4840
+ /** border */
4754
4841
  border?: ConditionalFormatBorder;
4755
- /** 숫자 서식 코드. 현재는 조회만 지원한다 */
4842
+ /** number format code. Currently read-only */
4756
4843
  numberFormat?: string;
4757
4844
  }
4758
4845
  interface ConditionalFormatValue {
4759
- /** 시각 규칙이 값 범위를 나누는 기준점 종류. min·max·autoMin·autoMax 는 데이터에서 잡으므로 formula 를 쓰지 않는다 */
4846
+ /** type of threshold that a visual rule uses to divide the value range. min, max, autoMin, and autoMax are taken from the data, so formula is not used */
4760
4847
  type: ConditionalFormatValueType;
4761
- /** num·percent·percentile 의 값, formula 의 수식 */
4848
+ /** value for num, percent, and percentile, or the formula for formula */
4762
4849
  formula?: string | number;
4763
4850
  }
4764
4851
  interface ConditionalFormatRule {
4765
- /** 규칙 종류. 나머지 필드 가운데 무엇을 함께 쓰는지 이 값이 정한다 */
4852
+ /** rule type. Determines which of the other fields are used */
4766
4853
  type: ConditionalFormatRuleType;
4767
- /** cellIs 가 값을 견주는 방식 */
4854
+ /** how cellIs compares values */
4768
4855
  operator?: ConditionalFormatOperator;
4769
- /** cellIs 의 비교값, expression 의 참·거짓 수식 */
4856
+ /** comparison value for cellIs, or the true/false formula for expression */
4770
4857
  formula1?: string | number;
4771
- /** cellIs 가 between·notBetween 일 때 쓰는 두 번째 경계값 */
4858
+ /** second boundary value used when cellIs is between or notBetween */
4772
4859
  formula2?: string | number;
4773
- /** containsText·notContainsText·beginsWith·endsWith 가 찾을 문자열 */
4860
+ /** string that containsText, notContainsText, beginsWith, and endsWith look for */
4774
4861
  text?: string;
4775
- /** timePeriod 가 볼 기간 */
4862
+ /** period that timePeriod checks */
4776
4863
  timePeriod?: ConditionalFormatTimePeriod;
4777
- /** top10 이 고를 개수. percent 가 참이면 1~100, 아니면 1~1000 */
4864
+ /** number of cells that top10 picks. 1 to 100 if percent is true, otherwise 1 to 1000 */
4778
4865
  rank?: number;
4779
- /** top10 의 rank 를 개수가 아니라 백분율로 읽는다 */
4866
+ /** whether top10 reads rank as a percentage instead of a count */
4780
4867
  percent?: boolean;
4781
- /** top10 을 위에서가 아니라 아래에서 고른다 */
4868
+ /** whether top10 picks from the bottom instead of the top */
4782
4869
  bottom?: boolean;
4783
- /** colorScale 의 눈금 색 "#RRGGBB" 2~3개. dataBar 에서는 현재 조회만 지원한다 */
4870
+ /** 2 or 3 scale colors "#RRGGBB" for colorScale. Currently read-only for dataBar */
4784
4871
  colors?: string[];
4785
- /** colorScale·iconSet 의 기준점. 생략하면 데이터 범위를 고르게 나눈다. dataBar 에서는 현재 조회만 지원한다 */
4872
+ /** thresholds for colorScale and iconSet. If omitted, the data range is divided evenly. Currently read-only for dataBar */
4786
4873
  cfvo?: ConditionalFormatValue[];
4787
- /** dataBar 막대를 단색이 아니라 그라데이션으로 그린다. 현재는 조회만 지원한다 */
4874
+ /** whether dataBar draws bars with a gradient instead of a solid color. Currently read-only */
4788
4875
  gradient?: boolean;
4789
- /** dataBar 가 쓸 막대 프리셋. 막대는 이 프리셋으로만 만들 수 있다. 조회는 막대 모양이 프리셋과 같을 때 이 이름을 준다 */
4876
+ /** bar preset for dataBar. Bars can be created only with this preset. Getters return this name when the bar appearance matches a preset */
4790
4877
  dataBar?: string;
4791
- /** iconSet 이 쓸 아이콘 묶음 */
4878
+ /** icon set for iconSet */
4792
4879
  iconSet?: string;
4793
- /** iconSet 의 아이콘을 반대 순서로 매긴다 */
4880
+ /** whether iconSet assigns icons in reverse order */
4794
4881
  reverse?: boolean;
4795
- /** 조건이 맞은 셀에 입힐 강조 서식. 생략하면 기본 강조를 쓰며, 시각 규칙에는 지정할 수 없다 */
4882
+ /** highlight format to apply to cells that meet the condition. If omitted, the default highlight is used. Cannot be specified for visual rules */
4796
4883
  style?: ConditionalFormatStyle;
4797
4884
  }
4798
4885
  interface ConditionalFormatInfo {
4799
- /** 우선순위 */
4886
+ /** priority */
4800
4887
  priority: number;
4801
- /** 조건이 맞으면 뒤 규칙을 적용하지 않을지 여부 */
4888
+ /** whether later rules are skipped when the condition is met */
4802
4889
  stopIfTrue: boolean;
4803
- /** 적용 영역(콤마로 구분된 참조 영역) */
4890
+ /** applied ranges (comma-separated references) */
4804
4891
  ranges: string;
4805
- /** 규칙 내용. 강조 서식은 그 안의 style 에 담긴다 */
4892
+ /** rule definition. The highlight format is in its style */
4806
4893
  rule: ConditionalFormatRule;
4807
4894
  }
4808
4895
  interface DataValidationRule {
4809
- /** 적용 영역. 절대 참조 표기("$A$1:$B$2")이며 떨어져 있는 여러 영역은 콤마로 이어 붙인 한 문자열이다 */
4810
- ranges: string;
4811
- /** 검사 종류 */
4896
+ /** validation type. Determines which of the other fields are used */
4812
4897
  type: DataValidationType;
4813
- /** 검사에 쓰는 값·참조·수식. any 종류에는 없다 */
4814
- formula1?: string | number;
4815
- /** 비교 연산자. 숫자·날짜·시간·길이 종류에만 있다 */
4898
+ /** how the number, date, time, and length types compare values */
4816
4899
  operator?: DataValidationOperator;
4817
- /** between·notBetween 의 두 번째 경계 */
4900
+ /** value, reference, or formula used for validation. Not used for the any type */
4901
+ formula1?: string | number;
4902
+ /** second boundary for between and notBetween */
4818
4903
  formula2?: string | number;
4819
- /** 빈 셀을 허용하는지 여부 */
4820
- allowBlank: boolean;
4821
- /** 목록을 드롭다운으로 보여줄지 여부. list 종류에만 있다 */
4904
+ /** whether empty cells are allowed. true if omitted */
4905
+ allowBlank?: boolean;
4906
+ /** whether to show the list as a drop-down. Used only for the list type. true if omitted */
4822
4907
  showDropDown?: boolean;
4823
- /** 셀을 선택했을 때 안내 메시지를 보여줄지 여부 */
4824
- showInputMessage: boolean;
4825
- /** 안내 메시지 제목 */
4908
+ /** whether to show the input message when the cell is selected. true if omitted */
4909
+ showInputMessage?: boolean;
4910
+ /** input message title */
4826
4911
  inputTitle?: string;
4827
- /** 안내 메시지 본문 */
4912
+ /** input message body */
4828
4913
  inputMessage?: string;
4829
- /** 규칙을 어겼을 때 오류 메시지를 보여줄지 여부 */
4830
- showErrorMessage: boolean;
4831
- /** 오류 표시 방식 */
4832
- errorStyle: DataValidationErrorStyle;
4833
- /** 오류 메시지 제목 */
4914
+ /** whether to show an error message when the rule is violated. true if omitted */
4915
+ showErrorMessage?: boolean;
4916
+ /** error alert style. stop if omitted */
4917
+ errorStyle?: DataValidationErrorStyle;
4918
+ /** error message title */
4834
4919
  errorTitle?: string;
4835
- /** 오류 메시지 본문 */
4920
+ /** error message body */
4836
4921
  errorMessage?: string;
4837
4922
  }
4923
+ interface DataValidationInfo {
4924
+ /** applied ranges (comma-separated references) */
4925
+ ranges: string;
4926
+ /** rule definition */
4927
+ rule: DataValidationRule;
4928
+ }
4838
4929
  interface CommentInfo {
4839
- /** 메모가 붙은 셀(A1 표기) */
4930
+ /** cell that the comment is attached to (A1 notation) */
4840
4931
  cell: string;
4841
- /** 메모 내용 문자열. 여러 줄은 "\n" 으로 이어진다 */
4932
+ /** comment text. Multiple lines are joined with "\n" */
4842
4933
  text: string;
4843
- /** 항상 보이는지 여부. false 인 메모는 셀에 마우스를 올릴 때만 보인다 */
4934
+ /** whether the comment is always shown. A comment with false is shown only when the pointer is over the cell */
4844
4935
  visible: boolean;
4845
4936
  }
4846
4937
  interface CellContent {
4847
- /** 셀 값. 수식 셀은 계산 결과값이고 빈 셀은 undefined 다 */
4938
+ /** cell value. The calculated result for a formula cell, and undefined for an empty cell */
4848
4939
  value: string | number | boolean | undefined;
4849
- /** 화면에 보이는 문자열(서식 적용 후) */
4940
+ /** string shown on screen (after formatting) */
4850
4941
  displayValue: string;
4851
- /** 수식. 수식이 아니면 null */
4942
+ /** formula entered in the cell. null for a cell without a formula */
4852
4943
  formula: string | null;
4853
4944
  }
4854
4945
  interface HyperlinkInfo {
4946
+ /** A1 notation of the range that the link is set on */
4855
4947
  range: string;
4948
+ /** link type. "document", "file", and "", which are not in HyperlinkType, appear only for links in documents created by other applications, and "" means the link type is unknown */
4856
4949
  type: "web" | "email" | "book" | "document" | "file" | "";
4950
+ /** link target */
4857
4951
  location: string;
4952
+ /** display text */
4858
4953
  display: string;
4859
4954
  }
4860
- interface HyperlinkOptions {
4861
- /** 링크 대상. 웹 주소, 이메일 주소, 문서 안의 참조("Sheet1!A1"), 정의된 이름을 받으며 type 에 맞는 형식이 아니면 걸 수 없다 */
4862
- location: string;
4863
- /** 좌상단 셀에 넣을 표시 텍스트. 셀 값이 숫자이거나 줄바꿈이 든 문자열이면 무시되고 셀 값이 그대로 남는다. 셀 값이 그 밖의 문자열이면 display 로 바뀌고, 셀이 비어 있으면 display 가 들어가며 생략하면 location 이 들어간다 */
4864
- display?: string | null;
4865
- /** 링크 종류. 생략하면 location 을 보고 판별한다 */
4866
- type?: HyperlinkType | null;
4867
- }
4868
4955
  interface BorderLine {
4869
- /** 선 스타일 */
4956
+ /** line style */
4870
4957
  style: BorderLineStyle;
4871
- /** 선 색 "#RRGGBB" */
4958
+ /** line color "#RRGGBB" */
4872
4959
  color?: string;
4873
4960
  }
4874
4961
  interface BorderDiagonal {
4875
- /** 선 스타일 */
4962
+ /** line style */
4876
4963
  style: BorderLineStyle;
4877
- /** 선 색 "#RRGGBB" */
4964
+ /** line color "#RRGGBB" */
4878
4965
  color?: string;
4879
- /** 대각선 방향. setBorder 의 type 으로 그대로 넘길 수 있다 */
4966
+ /** diagonal direction. Can be passed as is as the type argument of setBorder */
4880
4967
  direction: "diagonal_up" | "diagonal_down" | "diagonal_cross";
4881
4968
  }
4882
4969
  interface BorderInfo {
4883
- /** 테두리가 없으면 null */
4970
+ /** top edge. null if there is no border */
4884
4971
  top: BorderLine | null;
4972
+ /** bottom edge. null if there is no border */
4885
4973
  bottom: BorderLine | null;
4974
+ /** left edge. null if there is no border */
4886
4975
  left: BorderLine | null;
4976
+ /** right edge. null if there is no border */
4887
4977
  right: BorderLine | null;
4978
+ /** diagonal. null if there is no border */
4888
4979
  diagonal: BorderDiagonal | null;
4889
4980
  }
4890
4981
  interface FillPattern {
4891
- /** 무늬 종류("lightGrid", "darkVertical" 등) */
4982
+ /** pattern type (such as "lightGrid" or "darkVertical") */
4892
4983
  type: string;
4893
- /** 무늬선 색 "#RRGGBB" */
4984
+ /** pattern line color "#RRGGBB" */
4894
4985
  color?: string;
4895
4986
  }
4896
4987
  interface FillInfo {
4988
+ /** fill type */
4897
4989
  type: "solid" | "pattern" | "gradient";
4898
- /** 바탕색 "#RRGGBB" */
4990
+ /** background color "#RRGGBB" */
4899
4991
  backgroundColor?: string;
4900
- /** 바탕색 위에 겹쳐 그리는 무늬 */
4992
+ /** pattern drawn over the background color */
4901
4993
  pattern?: FillPattern;
4902
4994
  }
4995
+ interface FontInfo {
4996
+ /** whether the font is bold */
4997
+ bold: boolean | undefined;
4998
+ /** whether the font is italic */
4999
+ italic: boolean | undefined;
5000
+ /** underline type */
5001
+ underline: "single" | "double" | "none";
5002
+ /** whether strikethrough is applied */
5003
+ strikethrough: boolean | undefined;
5004
+ /** font name */
5005
+ name: string | undefined;
5006
+ /** font size (pt) */
5007
+ size: number | undefined;
5008
+ /** font color "#RRGGBB" */
5009
+ color: string | undefined;
5010
+ }
5011
+ interface AlignmentInfo {
5012
+ /** horizontal alignment. Values are from HorizontalAlign */
5013
+ horizontalAlign: string | undefined;
5014
+ /** vertical alignment. Values are from VerticalAlign */
5015
+ verticalAlign: string | undefined;
5016
+ /** whether text wrapping is applied */
5017
+ wrapText: boolean | undefined;
5018
+ /** indent level */
5019
+ indent: number;
5020
+ }
4903
5021
  interface TableOptionUpdate {
4904
- /** 머리글 행을 둘지 여부 */
5022
+ /** whether to show the header row */
4905
5023
  headerRow?: boolean;
4906
- /** 요약 행을 둘지 여부 */
5024
+ /** whether to show the totals row */
4907
5025
  totalsRow?: boolean;
4908
- /** 첫 열에 강조 서식을 줄지 여부 */
5026
+ /** whether to highlight the first column */
4909
5027
  firstColumn?: boolean;
4910
- /** 끝 열에 강조 서식을 줄지 여부 */
5028
+ /** whether to highlight the last column */
4911
5029
  lastColumn?: boolean;
4912
- /** 행을 한 줄씩 번갈아 다른 색으로 칠할지 여부 */
5030
+ /** whether to shade alternate rows in different colors */
4913
5031
  bandedRows?: boolean;
4914
- /** 열을 한 줄씩 번갈아 다른 색으로 칠할지 여부 */
5032
+ /** whether to shade alternate columns in different colors */
4915
5033
  bandedColumns?: boolean;
4916
5034
  }
4917
5035
  interface TableOptions {
4918
- /** 머리글 행을 두는지 여부 */
5036
+ /** whether the header row is shown */
4919
5037
  headerRow: boolean;
4920
- /** 요약 행을 두는지 여부 */
5038
+ /** whether the totals row is shown */
4921
5039
  totalsRow: boolean;
4922
- /** 첫 열에 강조 서식을 주는지 여부 */
5040
+ /** whether the first column is highlighted */
4923
5041
  firstColumn: boolean;
4924
- /** 끝 열에 강조 서식을 주는지 여부 */
5042
+ /** whether the last column is highlighted */
4925
5043
  lastColumn: boolean;
4926
- /** 행을 한 줄씩 번갈아 다른 색으로 칠하는지 여부 */
5044
+ /** whether alternate rows are shaded in different colors */
4927
5045
  bandedRows: boolean;
4928
- /** 열을 한 줄씩 번갈아 다른 색으로 칠하는지 여부 */
5046
+ /** whether alternate columns are shaded in different colors */
4929
5047
  bandedColumns: boolean;
4930
- /** 표에 적용된 표 스타일 이름 ("TableStyleMedium2" 등) */
5048
+ /** name of the table style applied to the table (such as "TableStyleMedium2") */
4931
5049
  style: string;
4932
5050
  }
4933
5051
  interface TableInfo {
4934
- /** 표 이름 */
5052
+ /** table name */
4935
5053
  name: string;
4936
- /** 표가 놓인 시트 이름 */
5054
+ /** name of the sheet that the table is on */
4937
5055
  sheet: string;
4938
- /** 표 전체 영역의 A1 표기. 머리글 행과 요약 행이 함께 들어간다 */
5056
+ /** A1 notation of the entire table range, including the header row and totals row */
4939
5057
  range: string;
4940
- /** 머리글 행을 두는지 여부 */
5058
+ /** whether the header row is shown */
4941
5059
  headerRow: boolean;
4942
- /** 요약 행을 두는지 여부 */
5060
+ /** whether the totals row is shown */
4943
5061
  totalsRow: boolean;
4944
- /** 첫 열에 강조 서식을 주는지 여부 */
5062
+ /** whether the first column is highlighted */
4945
5063
  firstColumn: boolean;
4946
- /** 끝 열에 강조 서식을 주는지 여부 */
5064
+ /** whether the last column is highlighted */
4947
5065
  lastColumn: boolean;
4948
- /** 행을 한 줄씩 번갈아 다른 색으로 칠하는지 여부 */
5066
+ /** whether alternate rows are shaded in different colors */
4949
5067
  bandedRows: boolean;
4950
- /** 열을 한 줄씩 번갈아 다른 색으로 칠하는지 여부 */
5068
+ /** whether alternate columns are shaded in different colors */
4951
5069
  bandedColumns: boolean;
4952
- /** 표에 적용된 표 스타일 이름 ("TableStyleMedium2" 등) */
5070
+ /** name of the table style applied to the table (such as "TableStyleMedium2") */
4953
5071
  style: string;
4954
5072
  }
5073
+ interface FilterCondition {
5074
+ /** comparison operator */
5075
+ operator: FilterOperator;
5076
+ /** value to compare against */
5077
+ value: string | number;
5078
+ }
5079
+ interface FilterValuesCriteria {
5080
+ filterType: "values";
5081
+ /** list of values to show */
5082
+ values: (string | number)[];
5083
+ }
5084
+ interface FilterCustomCriteria {
5085
+ filterType: "custom";
5086
+ /** whether the conditions are combined with AND (OR if false) */
5087
+ and: boolean;
5088
+ /** one or two conditions */
5089
+ conditions: FilterCondition[];
5090
+ }
5091
+ interface FilterTop10Criteria {
5092
+ filterType: "top10";
5093
+ /** count or percentage */
5094
+ value: number;
5095
+ /** top (true) or bottom (false) */
5096
+ top: boolean;
5097
+ /** whether the filter is based on a percentage */
5098
+ percent: boolean;
5099
+ /** boundary value that satisfies the condition (calculated and included when retrieved) */
5100
+ filterValue: number;
5101
+ }
5102
+ interface FilterDynamicCriteria {
5103
+ filterType: "dynamic";
5104
+ /** above or below the average */
5105
+ type: FilterDynamicType;
5106
+ /** column average used as the reference (calculated and included when retrieved) */
5107
+ average: number;
5108
+ }
4955
5109
  interface FilterColumn {
4956
- /** 필터 영역 첫 열부터 센 0-based 오프셋. applyFilter·clearFilter·sort 에 그대로 넘길 수 있다 */
5110
+ /** 0-based offset from the first column of the filter range. Can be passed as is to applyFilter, clearFilter, and sort */
4957
5111
  colId: number;
4958
- /** 필터 종류 */
5112
+ /** filter type */
4959
5113
  filterType: FilterType;
4960
- /** applyFilter 에 넘기는 조건과 같은 형태. 알 수 없는 필터 종류면 null 이다 */
4961
- criteria: Record<string, unknown> | null;
5114
+ /** filter criteria applied to this column. null if the filter type is not in FilterType */
5115
+ criteria: FilterValuesCriteria | FilterCustomCriteria | FilterTop10Criteria | FilterDynamicCriteria | null;
4962
5116
  }
4963
5117
  interface FilterSortState {
4964
- /** 필터 영역 첫 열부터 센 0-based 오프셋. sort 에 넘기는 colId 와 같다 */
5118
+ /** 0-based offset from the first column of the filter range. Same as the colId passed to sort */
4965
5119
  colId: number;
4966
- /** 정렬 방향 */
5120
+ /** sort order */
4967
5121
  order: SortOrder;
4968
5122
  }
4969
5123
  interface FilterInfo {
4970
- /** 필터가 있는지 여부. false 면 이 필드만 들어 있다 */
5124
+ /** whether a filter exists */
4971
5125
  enabled: boolean;
4972
- /** 필터 영역의 A1 표기 (예: "A1:D20") */
5126
+ /** A1 notation of the filter range (for example, "A1:D20") */
4973
5127
  range?: string;
4974
- /** 조건이 걸린 열의 목록 */
5128
+ /** list of columns with criteria applied */
4975
5129
  columns?: FilterColumn[];
4976
- /** 필터 조건에 걸려 숨겨진 행 수. 사용자가 직접 숨긴 행은 세지 않는다 */
5130
+ /** number of rows hidden by the filter criteria */
4977
5131
  hiddenRowCount?: number;
4978
- /** 정렬 상태. 정렬한 적이 없으면 null 이고, 정렬 키가 여럿인 문서는 첫 기준만 담는다 */
5132
+ /** sort state. null if the range has never been sorted. For a document with multiple sort keys, only the primary key is included */
4979
5133
  sort?: FilterSortState | null;
4980
5134
  }
4981
5135
  interface NameUpdate {
4982
- /** 새 이름. 공백이나 허용되지 않는 문자를 쓸 수 없고, 예약된 이름이나 셀 참조로 읽히는 이름, 최대 길이를 넘는 이름도 받지 않는다 */
5136
+ /** new name. It cannot contain spaces or disallowed characters, and reserved names, names that read as cell references, and names longer than the maximum length are not accepted */
4983
5137
  newName?: string;
4984
- /** 새 수식 또는 참조. `=` 로 시작해도 되고 아니어도 된다 */
5138
+ /** new formula or reference */
4985
5139
  formula?: string;
4986
5140
  }
4987
5141
  interface NameInfo {
4988
- /** 정의된 이름 */
5142
+ /** defined name */
4989
5143
  name: string;
4990
- /** 특정 시트에서만 쓰는 이름이면 그 시트. 문서 전체에서 쓰는 이름이면 null */
5144
+ /** sheet if the name is sheet-scoped. null if the name is workbook-scoped */
4991
5145
  sheet: string | null;
4992
- /** `=` 로 시작하는 수식 */
5146
+ /** formula or reference that the name points to */
4993
5147
  formula: string;
4994
- /** 이름이 가리키는 실제 영역이다. 시트 이름을 붙인 A1 주소를 콤마로 이어 붙이며, 상수나 오류를 가리키는 이름과 지원하지 않는 함수를 쓴 이름은 빈 문자열이다 */
5148
+ /** ranges that the name refers to. Same value as getRanges() */
4995
5149
  ranges: string;
4996
5150
  }
4997
- interface FontInfo {
4998
- /** 굵게 여부 */
4999
- bold: boolean | undefined;
5000
- /** 기울임 여부 */
5001
- italic: boolean | undefined;
5002
- /** 밑줄 종류 */
5003
- underline: "single" | "double" | "none";
5004
- /** 취소선 여부 */
5005
- strikethrough: boolean | undefined;
5006
- /** 글꼴 이름 */
5007
- name: string | undefined;
5008
- /** 글꼴 크기(pt) */
5009
- size: number | undefined;
5010
- /** 글꼴 색 "#RRGGBB" */
5011
- color: string | undefined;
5012
- }
5013
- interface AlignmentInfo {
5014
- /** 가로 정렬. 값 어휘는 HorizontalAlign */
5015
- horizontalAlign: string | undefined;
5016
- /** 세로 정렬. 값 어휘는 VerticalAlign */
5017
- verticalAlign: string | undefined;
5018
- /** 텍스트 줄바꿈 여부 */
5019
- wrapText: boolean | undefined;
5020
- /** 들여쓰기 수준 */
5021
- indent: number;
5151
+ interface ChartFormatInfo {
5152
+ /** 차트 종류. 값은 getType 과 같다 */
5153
+ type: ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown";
5154
+ /** 차트 제목. 설정하지 않았으면 빈 문자열이다 */
5155
+ title: string;
5156
+ /** 범례 위치 */
5157
+ legendPosition: ChartLegendPosition;
5158
+ /** 데이터레이블 위치. null 은 그 차트 종류에 데이터레이블이 아예 없다는 뜻이다(표면형) */
5159
+ dataLabelPosition: ChartDataLabelPosition | null;
5160
+ /** 축별 축 제목. null 은 그 차트 종류에 해당 축의 제목이 아예 없다는 뜻이다 */
5161
+ axisTitle: {
5162
+ horizontal: string | null;
5163
+ vertical: string | null;
5164
+ };
5165
+ /** 축별 눈금선. null 은 그 차트 종류에 해당 축의 눈금선이 아예 없다는 뜻이고, "none" 은 쓸 수는 있지만 꺼져 있다는 뜻이다 */
5166
+ gridLine: {
5167
+ horizontal: ChartGridLineType | null;
5168
+ vertical: ChartGridLineType | null;
5169
+ };
5022
5170
  }
5023
5171
  /**
5024
- * 통합 문서 전체를 다루는 최상위 객체이자 셀 API 의 진입점이다.
5025
- * 시트·표·정의된 이름처럼 문서에 속한 요소를 조회하고 관리한다.
5172
+ * The entry point to the workbook. It is the top-level object that represents the entire workbook.
5173
+ * Reads and manages the elements of the workbook, such as sheets, tables, and defined names.
5026
5174
  */
5027
5175
  interface Workbook {
5028
5176
  /**
5029
- * 문서의 시트 구성을 배열로 반환한다. 배열 인덱스가 곧 시트 인덱스(0-based)이며 숨긴 시트도 포함한다.
5030
- * 각 시트의 상세 속성은 Worksheet 에서 조회한다.
5177
+ * Returns the sheets of the workbook as an array. The array index is the sheet index (0-based), and hidden sheets are included.
5178
+ * Detailed properties of each sheet are read from Worksheet.
5031
5179
  */
5032
5180
  getSheetList(): Promise<SheetSummary[]>;
5033
5181
  /**
5034
- * 시트 핸들을 반환한다. 시트 이름으로 지정할 때는 대소문자를 구분한다.
5035
- * sheet 를 생략하면 활성 시트를 대상으로 한다.
5182
+ * Returns the Worksheet. Sheet names are case-sensitive when the sheet is specified by name.
5183
+ * If sheet is omitted, the active sheet is used.
5036
5184
  *
5037
- * @param sheet - 시트 인덱스(0-based, getSheetList() 결과의 배열 인덱스) 또는 시트 이름
5185
+ * @param sheet - sheet index (0-based, the array index in the getSheetList() result) or sheet name
5038
5186
  */
5039
5187
  getWorksheet(sheet?: number | string): Promise<Worksheet>;
5040
5188
  /**
5041
- * ID 로 객체 핸들을 반환한다. 문서의 모든 시트를 대상으로 하며, 현재는 차트 객체만 지원한다.
5042
- * 차트가 아닌 객체는 null 을 반환한다.
5189
+ * Returns an object by ID. It searches all sheets of the document, and currently only Chart is supported.
5190
+ * Returns null for an object that is not a chart.
5043
5191
  *
5044
- * @param oid - 객체를 식별하는 고유 ID
5192
+ * @param oid - unique ID that identifies the object
5045
5193
  */
5046
5194
  getObjectById(oid: string): Promise<Chart>;
5047
5195
  /**
5048
- * 이름으로 표 핸들을 반환한다. 이름은 대소문자를 구분하지 않으며, 핸들에는 실제 저장된 표 이름이 담긴다.
5196
+ * Returns a Table by name. The name is case-insensitive, and the returned Table holds the table name as actually stored.
5049
5197
  *
5050
- * @param name - 표 이름. 문서 전체에서 유일하다
5198
+ * @param name - table name. It is unique across the document
5051
5199
  */
5052
5200
  getTable(name: string): Promise<Table>;
5053
5201
  /**
5054
- * 전달한 name 을 이름으로 하는 정의된 이름을 반환한다. 이름은 대소문자를 구분하지 않는다.
5055
- * sheet 를 생략하면 문서 전체에서 쓰는 이름만 찾는다.
5202
+ * Returns the defined name with the given name. The name is case-insensitive.
5203
+ * If sheet is omitted, only workbook-scoped names are searched.
5056
5204
  *
5057
- * @param name - 찾을 이름
5058
- * @param sheet - 특정 시트에서만 쓰는 이름이면 그 시트
5205
+ * @param name - name to look up
5206
+ * @param sheet - sheet that the name is scoped to. If omitted, the entire workbook
5059
5207
  */
5060
5208
  getDefinedName(name: string, sheet?: number | string): Promise<Name>;
5061
5209
  /**
5062
- * 정의된 이름을 만든다. formula 는 `=` 로 시작해도 되고 아니어도 된다.
5063
- * 수식에서 시트를 지정하지 않은 참조는 활성 시트 기준으로 해석한다.
5064
- * sheet 를 생략하면 문서 전체에서 쓰는 이름으로 만든다.
5065
- * 같은 이름의 정의된 이름이나 표가 이미 있으면 만들어지지 않고 오류가 발생한다.
5210
+ * Creates a defined name.
5211
+ * References in the formula that do not specify a sheet are resolved against the active sheet.
5212
+ * If sheet is omitted, the name is created as a workbook-scoped name.
5213
+ * Throws an error if a defined name or table with the same name already exists.
5066
5214
  *
5067
- * @param name - 만들 이름
5068
- * @param formula - 이름이 가리킬 수식 또는 참조
5069
- * @param sheet - 특정 시트에서만 쓸 이름이면 그 시트
5215
+ * @param name - name to create
5216
+ * @param formula - formula or reference that the name points to
5217
+ * @param sheet - sheet that the name is scoped to. If omitted, the entire workbook
5070
5218
  */
5071
5219
  addDefinedName(name: string, formula: string, sheet?: number | string): Promise<Name>;
5072
5220
  /**
5073
- * 정의된 이름 목록을 반환한다. 내장 이름, 숨긴 이름, 수식이 없는 이름은 제외한다.
5074
- * sheet 를 생략하면 문서 전체에서 쓰는 이름을 반환한다. formula 는 `=` 으로 시작한다.
5221
+ * Returns the list of defined names. Built-in names and names without a formula are excluded.
5222
+ * If sheet is omitted, the workbook-scoped names are returned.
5075
5223
  *
5076
- * @param sheet - 특정 시트에서만 쓰는 이름이면 그 시트
5224
+ * @param sheet - sheet that the name is scoped to. If omitted, the entire workbook
5225
+ * @returns Formulas start with `=`
5077
5226
  */
5078
5227
  getDefinedNameList(sheet?: number | string): Promise<NameInfo[]>;
5079
5228
  /**
5080
- * 새 시트를 시트 목록 맨 뒤에 추가하고, 추가한 시트를 활성 시트로 만든다.
5229
+ * Adds a new sheet at the end of the sheet list and makes it the active sheet.
5081
5230
  *
5082
- * @param name - 새 시트 이름
5231
+ * @param name - new sheet name
5083
5232
  */
5084
5233
  addSheet(name: string): Promise<SheetRef>;
5085
5234
  /**
5086
- * 시트를 삭제한다. 활성 시트를 삭제하면 인접한 시트가 활성 시트가 된다.
5087
- * 남은 시트가 하나뿐이거나 숨기지 않은 시트가 하나뿐이면 삭제할 수 없다.
5235
+ * Deletes a sheet. If the active sheet is deleted, an adjacent sheet becomes the active sheet.
5236
+ * The sheet cannot be deleted if it is the only remaining sheet or the only visible sheet.
5088
5237
  *
5089
- * @param sheet - 삭제할 시트
5238
+ * @param sheet - sheet to delete
5090
5239
  */
5091
5240
  removeSheet(sheet: number | string): Promise<void>;
5092
5241
  /**
5093
- * 시트를 복사해 원본 바로 뒤에 넣고, 복사본을 활성 시트로 만든다.
5242
+ * Copies a sheet and inserts the copy right after the original, and makes the copy the active sheet.
5094
5243
  *
5095
- * @param sheet - 복사할 시트
5244
+ * @param sheet - sheet to copy
5096
5245
  */
5097
5246
  copySheet(sheet: number | string): Promise<SheetRef>;
5098
5247
  /**
5099
- * 시트 위치를 이동한다.
5248
+ * Moves the position of a sheet.
5100
5249
  *
5101
- * @param from - 옮길 시트
5102
- * @param to - 옮겨 놓을 자리의 시트 인덱스(0-based)
5250
+ * @param from - sheet to move
5251
+ * @param to - sheet index (0-based) of the destination
5103
5252
  */
5104
5253
  moveSheet(from: number | string, to: number): Promise<void>;
5105
5254
  /**
5106
- * 활성 시트를 변경한다. 숨긴 시트는 활성화할 수 없다.
5255
+ * Changes the active sheet. A hidden sheet cannot be activated.
5107
5256
  *
5108
- * @param sheet - 활성화할 시트
5257
+ * @param sheet - sheet to activate
5109
5258
  */
5110
5259
  setActiveSheet(sheet: number | string): Promise<void>;
5111
5260
  /**
5112
- * 문서 속성을 반환한다. 문서에 없는 속성은 undefined 값을 가진다.
5261
+ * Returns the document properties.
5113
5262
  */
5114
5263
  getDocumentProperties(): Promise<DocumentProperties>;
5115
5264
  }
5116
5265
  /**
5117
- * 시트 하나를 다루는 핸들이다.
5118
- * 시트 자체의 속성과 그 시트에 속한 범위·차트·표·필터·규칙을 조회하고 관리한다.
5266
+ * Represents a sheet in the workbook.
5267
+ * Reads and manages the properties of the sheet and the ranges, charts, tables, filters, and rules on the sheet.
5119
5268
  */
5120
5269
  interface Worksheet {
5121
5270
  /**
5122
- * 시트 이름을 반환한다.
5271
+ * Returns the sheet name.
5123
5272
  */
5124
5273
  getName(): Promise<string>;
5125
5274
  /**
5126
- * 시트가 숨겨져 있는지 반환한다.
5275
+ * Returns whether the sheet is hidden.
5127
5276
  */
5128
5277
  isHidden(): Promise<boolean>;
5129
5278
  /**
5130
- * 시트 탭 색을 "#RRGGBB" 형태로 반환한다. 색을 지정하지 않은 시트는 빈 문자열이다.
5279
+ * Returns the sheet tab color in "#RRGGBB" format. It is an empty string for a sheet with no color set.
5131
5280
  */
5132
5281
  getTabColor(): Promise<string>;
5133
5282
  /**
5134
- * 이 시트의 선택 영역을 가리키는 Range 핸들을 반환한다.
5135
- * 선택 영역은 시트마다 따로 보관되므로 활성 시트가 아닌 시트에서도 조회할 수 있다.
5283
+ * Returns a Range for the selection on this sheet.
5284
+ * The selection is stored per sheet, so it can be read even on a sheet that is not the active sheet.
5136
5285
  */
5137
5286
  getSelection(): Promise<Range>;
5138
5287
  /**
5139
- * 값이나 셀 서식이 있는 셀을 모두 감싸는 사각 범위를 반환한다.
5140
- * 차트·도형과 행 높이·열 너비는 이 범위에 반영하지 않는다.
5288
+ * Returns the rectangular range that encloses all cells that have a value or cell format.
5289
+ * Charts, shapes, row heights, and column widths are not reflected in this range.
5141
5290
  *
5142
- * @returns 값도 셀 서식도 없는 시트에서는 null 이다
5291
+ * @returns null if the sheet has no values and no cell formats
5143
5292
  */
5144
5293
  getUsedRange(): Promise<Range>;
5145
5294
  /**
5146
- * 이 시트의 병합 셀 목록을 반환한다. 특정 범위와 겹치는 병합만 필요하면 Range.getMergeCellList() 를 쓴다.
5295
+ * Returns the list of merged cells on this sheet. To get only the merges that overlap a specific range, use Range.getMergeCellList().
5147
5296
  *
5148
- * @returns 병합된 영역을 A1 표기로 담은 배열
5297
+ * @returns array of merged areas in A1 notation
5149
5298
  */
5150
5299
  getMergeCellList(): Promise<string[]>;
5151
5300
  /**
5152
- * 이 시트의 하이퍼링크 목록을 반환한다.
5301
+ * Returns the list of hyperlinks on this sheet.
5153
5302
  */
5154
5303
  getHyperlinkList(): Promise<HyperlinkInfo[]>;
5155
5304
  /**
5156
- * 틀 고정 상태를 반환한다.
5305
+ * Returns the freeze panes state.
5157
5306
  */
5158
5307
  getFreezePanes(): Promise<FreezePanes>;
5159
5308
  /**
5160
- * 눈금선을 표시하는지 반환한다.
5309
+ * Returns whether gridlines are shown.
5161
5310
  */
5162
5311
  isGridlinesVisible(): Promise<boolean>;
5163
5312
  /**
5164
- * 화면 확대 배율을 반환한다.
5313
+ * Returns the zoom factor.
5165
5314
  *
5166
- * @returns 1 이 100% 인 배율. 퍼센트로 환산하지 않는다
5315
+ * @returns zoom factor where 1 is 100%. It is not converted to a percentage
5167
5316
  */
5168
5317
  getZoom(): Promise<number>;
5169
5318
  /**
5170
- * 시트 속성을 한 번에 반환한다. 각 항목은 같은 이름의 개별 조회 메서드와 같은 값이다.
5319
+ * Returns the sheet properties in a single call. Each item matches the getter of the same name.
5171
5320
  */
5172
5321
  getSheetInfo(): Promise<SheetInfo>;
5173
5322
  /**
5174
- * 시트 이름을 변경한다.
5323
+ * Renames the sheet.
5175
5324
  *
5176
- * @param name - 새 시트 이름
5325
+ * @param name - new sheet name
5177
5326
  */
5178
5327
  setName(name: string): Promise<void>;
5179
5328
  /**
5180
- * 시트를 숨기거나 다시 표시한다.
5181
- * 숨기지 않은 시트가 이 시트 하나뿐이면 동작하지 않는다.
5182
- * 활성 시트를 숨기면 인접한 숨기지 않은 시트가 활성 시트가 된다.
5329
+ * Hides the sheet or shows it again. If the active sheet is hidden, an adjacent visible sheet becomes the active sheet.
5330
+ * The sheet cannot be hidden if it is the only visible sheet.
5183
5331
  *
5184
- * @param hidden - true 면 숨기고 false 면 다시 표시한다
5332
+ * @param hidden - true to hide the sheet, false to show it again
5185
5333
  */
5186
5334
  setHidden(hidden: boolean): Promise<void>;
5187
5335
  /**
5188
- * 시트 탭 색을 설정한다. 빈 문자열이나 null 을 넘기거나 생략하면 지정된 탭 색을 지운다.
5336
+ * Sets the sheet tab color. Passing an empty string or null, or omitting it, clears the tab color.
5189
5337
  *
5190
- * @param color - 탭 색. "#RRGGBB" 외에 3·4·8 자리 hex, "#" 을 생략한 hex, "red" 같은 색 이름도 받는다
5338
+ * @param color - tab color. In addition to "#RRGGBB", hex with 3, 4, or 8 digits, hex without "#", and color names such as "red" are also accepted
5191
5339
  */
5192
5340
  setTabColor(color?: string | null): Promise<void>;
5193
5341
  /**
5194
- * 선택 영역을 설정한다. 대상 시트가 활성 시트가 아니면 먼저 활성 시트로 만들며, 숨긴 시트는 활성화할 수 없어 오류가 발생한다.
5195
- * 선택한 영역이 보이도록 화면을 스크롤하려면 goto() 를 쓴다.
5342
+ * Sets the selection. If the target sheet is not the active sheet, it is made the active sheet first, and a hidden sheet cannot be activated, so an error is thrown.
5343
+ * To scroll the view so that the selected range is visible, use goto().
5196
5344
  *
5197
- * @param range - 선택할 영역. A1 표기 문자열로도 지정할 수 있다("A1:B2", 단일 셀은 "E10")
5345
+ * @param range - range to select. An A1 notation string is also accepted ("A1:B2", or "E10" for a single cell)
5198
5346
  */
5199
5347
  setSelection(range: string | RangeCoords): Promise<SelectionInfo>;
5200
5348
  /**
5201
- * 지정한 영역을 선택하고 그 영역이 보이도록 화면을 스크롤한다.
5202
- * 대상 시트가 활성 시트가 아니면 먼저 활성 시트로 만들고, 숨긴 시트를 지정하면 숨기지 않은 다른 시트로 대체해 이동한다.
5349
+ * Selects the specified range and scrolls the view so that the range is visible.
5350
+ * If the target sheet is not the active sheet, it is made the active sheet first, and a hidden sheet cannot be navigated to.
5203
5351
  *
5204
- * @param range - 이동할 영역. A1 표기 문자열로도 지정할 수 있다("A1:B2", 단일 셀은 "E10")
5205
- * @returns 숨긴 시트를 지정했다면 대체해 이동한 시트의 이름이 담긴다
5352
+ * @param range - range to go to. An A1 notation string is also accepted ("A1:B2", or "E10" for a single cell)
5206
5353
  */
5207
5354
  goto(range: string | RangeCoords): Promise<SelectionInfo>;
5208
5355
  /**
5209
- * 틀 고정을 설정한다. 0 이하이거나 null 을 넘기면 그 방향의 고정을 해제한다.
5356
+ * Sets freeze panes. A value of 0 or less, or null, unfreezes that direction.
5210
5357
  *
5211
- * @param rows - 고정할 상단 행 수 (기본값: 0)
5212
- * @param cols - 고정할 좌측 열 수 (기본값: 0)
5358
+ * @param rows - number of top rows to freeze (default: 0)
5359
+ * @param cols - number of left columns to freeze (default: 0)
5213
5360
  */
5214
5361
  setFreezePanes(rows?: number | null, cols?: number | null): Promise<void>;
5215
5362
  /**
5216
- * 눈금선 표시 여부를 설정한다.
5363
+ * Sets whether gridlines are shown.
5217
5364
  *
5218
- * @param visible - true 면 눈금선을 표시하고 false 면 감춘다
5365
+ * @param visible - true to show gridlines, false to hide them
5219
5366
  */
5220
5367
  setGridlinesVisible(visible: boolean): Promise<void>;
5221
5368
  /**
5222
- * 화면 확대 배율을 설정한다. 허용 범위를 벗어난 값은 경계값으로 맞추지 않고 오류가 발생한다.
5369
+ * Sets the zoom factor. A value outside the allowed range throws an error.
5223
5370
  *
5224
- * @param zoomFactor - 1 이 100% 인 배율. 0.5 이상 1.5 이하여야 한다
5371
+ * @param zoomFactor - zoom factor where 1 is 100%. It must be greater than or equal to 0.5 and less than or equal to 1.5
5225
5372
  */
5226
5373
  setZoom(zoomFactor: number): Promise<void>;
5227
5374
  /**
5228
- * 이 시트의 영역을 가리키는 Range 핸들을 반환한다.
5229
- * 핸들은 행이나 열을 삽입·삭제해도 처음 지정한 좌표를 유지한다.
5375
+ * Returns a Range for a range on this sheet.
5230
5376
  *
5231
- * @param range - 대상 영역. A1 표기 문자열로도 지정할 수 있다("A1:B2", 단일 셀은 "E10", 행 전체는 "5:5", 열 전체는 "A:C")
5377
+ * @param range - target range. An A1 notation string is also accepted ("A1:B2", "E10" for a single cell, "5:5" for an entire row, or "A:C" for entire columns). An address with a sheet name ("Sheet1!A1") is not accepted
5232
5378
  */
5233
5379
  getRange(range: string | RangeCoords): Promise<Range>;
5234
5380
  /**
5235
- * 이 시트에 차트를 추가하고 그 차트의 핸들을 반환한다. 제목은 데이터에서 뽑아 자동으로 붙는다.
5236
- * 시리즈로 쓸 행이나 열은 100 개까지 지원한다.
5237
- * 데이터 범위는 이 시트의 것만 받는다.
5381
+ * Adds a chart to this sheet and returns the Chart. The title is taken from the data and set automatically.
5382
+ * Up to 100 rows or columns can be used as series.
5383
+ * Only data ranges on this sheet are accepted.
5238
5384
  *
5239
- * @param chartType - 차트 종류. 지원하지 않는 종류는 오류가 발생한다
5240
- * @param dataRange - 차트가 사용할 데이터 범위. A1 표기 문자열로도 지정할 수 있다("A1:B2", 단일 셀은 "E10")
5241
- * @param opts - 추가 옵션
5385
+ * @param chartType - chart type. An unsupported type throws an error
5386
+ * @param dataRange - data range used by the chart. An A1 notation string is also accepted ("A1:B2", or "E10" for a single cell)
5387
+ * @param opts - additional options
5242
5388
  */
5243
5389
  addChart(chartType: ChartType, dataRange: string | RangeCoords, opts?: AddChartOptions): Promise<Chart>;
5244
5390
  /**
5245
- * ID 로 차트 핸들을 반환한다. 이 시트에 있는 차트만 대상으로 한다.
5391
+ * Returns a Chart by ID. Only charts on this sheet are searched.
5246
5392
  *
5247
- * @param oid - 차트를 식별하는 고유 ID. getChartList() 결과의 oid 다
5393
+ * @param oid - unique ID that identifies the chart. It is the oid in the getChartList() result
5248
5394
  */
5249
5395
  getChart(oid: string): Promise<Chart>;
5250
5396
  /**
5251
- * 이 시트의 차트 정보 목록을 반환한다. 핸들이 필요하면 항목의 oid 로 getChart() 를 호출한다.
5397
+ * Returns the list of chart information on this sheet. To get a Chart, call getChart() with the oid of an item.
5252
5398
  */
5253
5399
  getChartList(): Promise<ChartInfo[]>;
5254
5400
  /**
5255
- * 이 시트에 표를 만들고 그 표의 핸들을 반환한다. 표 이름은 자동으로 정해진다.
5256
- * 머리글을 쓰지 않거나 범위가 한 행뿐이면 맨 위에 빈 머리글 행이 들어가, 아래 내용이 한 행씩 밀리고 표는 범위보다 한 행 넓어진다.
5257
- * 공동 편집 중이거나, 범위가 행 전체·열 전체이거나 시트의 마지막 행을 포함하면 만들 수 없다.
5401
+ * Creates a table on this sheet and returns the Table. The table name is assigned automatically.
5402
+ * If headers are not used or the range is a single row, an empty header row is added at the top, so the content below is pushed down by one row and the table is one row larger than the range.
5403
+ * A table cannot be created while the document is being co-edited, or if the range is entire rows or entire columns or includes the last row of the sheet.
5258
5404
  *
5259
- * @param dataRange - 표로 만들 범위. A1 표기 문자열로도 지정할 수 있다("A1:B2", 단일 셀은 "E10")
5260
- * @param hasHeaders - 범위의 첫 행을 머리글로 쓸지 여부 (기본값: true)
5405
+ * @param dataRange - range to make into a table. An A1 notation string is also accepted ("A1:B2", or "E10" for a single cell)
5406
+ * @param hasHeaders - whether the first row of the range is used as the header row (default: true)
5261
5407
  */
5262
5408
  addTable(dataRange: string | RangeCoords, hasHeaders?: boolean): Promise<Table>;
5263
5409
  /**
5264
- * 이 시트의 표 요약 목록을 반환한다. 핸들이 필요하면 요약의 name 으로 Workbook.getTable() 을 호출한다.
5410
+ * Returns the list of table summaries on this sheet. To get a Table, call Workbook.getTable() with the name in the summary.
5265
5411
  */
5266
5412
  getTableList(): Promise<TableInfo[]>;
5267
5413
  /**
5268
- * 이 시트의 자동 필터 핸들을 반환한다. 자동 필터가 설정돼 있지 않아도 핸들은 돌려주므로, 설정 여부는 핸들의 getInfo() 가 주는 enabled 로 확인하고 설정은 create() 로 한다.
5414
+ * Returns a Filter that manages the AutoFilter on this sheet. A Filter is returned even if no AutoFilter is set, so check whether one is set with enabled from getInfo() of the Filter, and set one with create().
5269
5415
  */
5270
5416
  getFilter(): Promise<Filter>;
5271
5417
  /**
5272
- * 이 시트의 조건부 서식 규칙 목록을 반환한다.
5273
- * 각 항목의 rule 은 규칙을 다시 추가할 때 그대로 넘길 수 있다. 적용 영역과 우선순위는 규칙 밖이라 따로 준다.
5274
- * rule.style 의 글꼴 크기·이름, 그라데이션, 숫자 서식은 현재 조회만 지원한다.
5275
- * 파일에서 읽어 프리셋에 없는 모양이 된 dataBar 는 colors·gradient·cfvo 로 나오며, 이 셋은 현재 조회만 지원한다.
5418
+ * Returns the list of conditional format rules on this sheet.
5419
+ * The font size and name, gradient, and number format of rule.style are currently read-only.
5420
+ * A dataBar loaded from a file with a look that is not in the presets appears as colors, gradient, and cfvo, and these three are currently read-only.
5421
+ *
5422
+ * @returns formula1 and formula2 of a rule, and formula of a ConditionalFormatValue whose type is formula, start with `=`
5276
5423
  */
5277
5424
  getConditionalFormatList(): Promise<ConditionalFormatInfo[]>;
5278
5425
  /**
5279
- * 이 시트의 데이터 유효성 규칙 목록을 반환한다.
5426
+ * Returns the list of data validation rules on this sheet.
5427
+ *
5428
+ * @returns formula1 and formula2 of a rule start with `=`, except that the comma-separated list of the list type is given without `=`
5280
5429
  */
5281
- getDataValidationList(): Promise<DataValidationRule[]>;
5430
+ getDataValidationList(): Promise<DataValidationInfo[]>;
5282
5431
  /**
5283
- * 이 시트의 셀 메모 목록을 반환한다.
5432
+ * Returns the list of cell comments on this sheet.
5284
5433
  */
5285
5434
  getCommentList(): Promise<CommentInfo[]>;
5286
5435
  /**
5287
- * 조건부 서식 규칙을 한 번에 편집한다. 규칙 삭제·적용 영역 변경·우선순위 이동을 한 묶음으로 처리해 하나라도 적용할 수 없으면 아무것도 바뀌지 않는다.
5288
- * 편집 하나만 적용할 때는 동작별 메서드를 쓴다.
5289
- * 규칙의 조건 자체는 바꿀 수 없어, 조건을 바꾸려면 규칙을 지우고 다시 추가한다.
5436
+ * Edits conditional format rules in a single call. Deleting rules, changing applied ranges, and moving priorities are processed as one batch, and if any of them cannot be applied, nothing is changed.
5437
+ * To apply only one edit, use the method for that action.
5438
+ * The condition of a rule cannot be changed, so to change a condition, delete the rule and add it again.
5290
5439
  *
5291
- * @param descriptor - 적용할 편집 내용
5440
+ * @param descriptor - edits to apply
5292
5441
  */
5293
5442
  updateConditionalFormatRules(descriptor: ConditionalFormatUpdate): Promise<void>;
5294
5443
  /**
5295
- * 조건부 서식 규칙을 삭제한다.
5444
+ * Deletes conditional format rules.
5296
5445
  *
5297
- * @param priorities - 삭제할 규칙 priority 목록. 빈 목록은 받지 않는다
5446
+ * @param priorities - priorities of the rules to delete. An empty list is not accepted
5298
5447
  */
5299
5448
  deleteConditionalFormatRules(priorities: number[]): Promise<void>;
5300
5449
  /**
5301
- * 조건부 서식 규칙 하나의 적용영역을 교체한다.
5302
- * 두 인자는 ConditionalFormatRangeSet 의 필드와 같은 계약이다.
5450
+ * Replaces the applied ranges of one conditional format rule.
5303
5451
  *
5304
- * @param priority - 대상 규칙 priority
5305
- * @param ranges - 새 적용 영역
5452
+ * @param priority - priority of the target rule
5453
+ * @param ranges - new applied ranges
5306
5454
  */
5307
5455
  setConditionalFormatRuleRanges(priority: number, ranges: string | RangeCoords[]): Promise<void>;
5308
5456
  /**
5309
- * 조건부 서식 규칙 하나를 다른 우선순위 자리로 옮긴다. 사이 규칙은 한 칸씩 shift 된다(Excel/Sheets 동일).
5457
+ * Moves one conditional format rule to another priority position. The rules in between shift by one position.
5310
5458
  *
5311
- * @param priority - 옮길 규칙 priority
5312
- * @param to - 옮겨 갈 자리. 지금 그 자리에 있는 규칙의 priority 를 넘긴다
5459
+ * @param priority - priority of the rule to move
5460
+ * @param to - position to move to. Pass the priority of the rule currently at that position
5313
5461
  */
5314
5462
  moveConditionalFormatRule(priority: number, to: number): Promise<void>;
5315
5463
  }
5316
5464
  /**
5317
- * 시트 안의 한 영역(셀 하나, 여러 셀, 행 전체, 열 전체)을 다루는 핸들이다.
5318
- * 영역에 담긴 값·수식과 셀 서식, 그리고 영역에 걸린 병합·메모·하이퍼링크·규칙을 다룬다.
5465
+ * Represents a range on a sheet, specified as a single cell, multiple cells, entire rows, or entire columns.
5466
+ * Reads and edits the values, formulas, and formats of the range, and the merges, comments, hyperlinks, and rules applied to it.
5467
+ * Keeps the originally specified coordinates even when rows or columns are inserted or deleted.
5319
5468
  */
5320
5469
  interface Range {
5321
5470
  /**
5322
- * 이 범위의 A1 주소를 반환한다("B2:C5", 단일 셀이면 "E10").
5323
- * 시트 이름을 붙이면 공백이나 특수문자가 든 이름은 따옴표로 감싼다. 이 형태는 getRange() 가 받지 않는다.
5471
+ * Returns the A1 address of this range ("B2:C5", or "E10" for a single cell).
5472
+ * If the sheet name is included, a name that contains spaces or special characters is enclosed in quotes.
5324
5473
  *
5325
- * @param includeSheetName - true 면 시트 이름을 붙이고, false 면 주소만 반환한다 (기본값: false)
5474
+ * @param includeSheetName - true to include the sheet name, false to return only the address (default: false)
5326
5475
  */
5327
5476
  getAddress(includeSheetName?: boolean): Promise<string>;
5328
5477
  /**
5329
- * 이 범위의 0-based 좌표를 반환한다. A1 주소가 필요하면 getAddress() 를 쓴다.
5330
- * 시트가 삭제됐으면 SHEET_NOT_FOUND 를 throw 한다.
5478
+ * Returns the 0-based coordinates of this range. Use getAddress() if the A1 address is needed.
5331
5479
  */
5332
5480
  getCoordinates(): Promise<SheetRangeCoords>;
5333
5481
  /**
5334
- * 범위가 셀 하나인지 반환한다. 여러 행이나 여러 열에 걸친 범위는 false 다.
5482
+ * Returns whether the range is a single cell. A range that spans multiple rows or columns returns false.
5335
5483
  */
5336
5484
  isSingleCell(): Promise<boolean>;
5337
5485
  /**
5338
- * 범위 좌상단 셀의 원시값인 문자열·숫자·불리언 중 하나의 타입 값이 반환되며, 수식 셀은 계산 결과값을 반환한다.
5486
+ * Returns the value of the top-left cell of the range. For a formula cell, returns the calculated result.
5339
5487
  *
5340
- * @returns 빈 셀은 undefined 다
5488
+ * @returns undefined for an empty cell
5341
5489
  */
5342
5490
  getValue(): Promise<string | number | boolean | undefined>;
5343
5491
  /**
5344
- * 범위 전체의 값을 행 우선 2차원 배열로 반환한다. 바깥 배열이 행, 안쪽 배열이 열이며 배열 크기는 범위 크기와 같다.
5345
- * 각 값의 형태는 getValue 와 같다.
5492
+ * Returns the values of the whole range as a row-major two-dimensional array. The outer array holds rows and the inner arrays hold columns. The array has the same size as the range.
5493
+ * Each value matches getValue.
5346
5494
  *
5347
- * @returns 빈 셀 자리는 undefined 로 채운다
5495
+ * @returns positions of empty cells are filled with undefined
5348
5496
  */
5349
5497
  getValues(): Promise<(string | number | boolean | undefined)[][]>;
5350
5498
  /**
5351
- * 범위 좌상단 셀의 수식 문자열을 반환한다. 수식이 아닌 셀(상수·빈 셀)이면 undefined 다.
5499
+ * Returns the formula string of the top-left cell of the range. Returns undefined for a cell that is not a formula (a constant or an empty cell).
5500
+ *
5501
+ * @returns formula starting with `=`. Array formula cells are in the form `{=...}`
5352
5502
  */
5353
5503
  getFormula(): Promise<string | undefined>;
5354
5504
  /**
5355
- * 범위 좌상단 셀의 화면 표시 문자열을 반환한다. 표시 형식이 적용된 결과라 저장된 값과 다를 수 있다.
5505
+ * Returns the string displayed for the top-left cell of the range. It is the result after the number format is applied, so it can differ from the stored value.
5356
5506
  *
5357
- * @returns 셀이 비어 있으면 빈 문자열
5507
+ * @returns empty string if the cell is empty
5358
5508
  */
5359
5509
  getDisplayValue(): Promise<string>;
5360
5510
  /**
5361
- * 범위 전체의 수식을 행 우선 2차원 배열로 반환한다. 배열 크기는 범위 크기와 같다.
5511
+ * Returns the formulas of the whole range as a row-major two-dimensional array. The array has the same size as the range.
5362
5512
  *
5363
- * @returns 수식이 아닌 셀 자리는 null 이다
5513
+ * @returns formulas starting with `=`, where array formula cells are in the form `{=...}`. Positions of cells that are not formulas are null
5364
5514
  */
5365
5515
  getFormulas(): Promise<(string | null)[][]>;
5366
5516
  /**
5367
- * 범위 전체의 화면 표시 문자열을 행 우선 2차원 배열로 반환한다. 배열 크기는 범위 크기와 같다.
5517
+ * Returns the displayed strings of the whole range as a row-major two-dimensional array. The array has the same size as the range.
5368
5518
  *
5369
- * @returns 빈 셀 자리는 빈 문자열이다
5519
+ * @returns positions of empty cells are empty strings
5370
5520
  */
5371
5521
  getDisplayValues(): Promise<string[][]>;
5372
5522
  /**
5373
- * 범위 좌상단 셀의 값·표시 문자열·수식을 한 번에 반환한다. 각 항목은 getValue·getDisplayValue·getFormula 와 같다.
5523
+ * Returns the value, displayed string, and formula of the top-left cell of the range in a single call. Each item matches getValue, getDisplayValue, and getFormula.
5524
+ *
5525
+ * @returns Formulas start with `=`. Array formula cells are in the form `{=...}`
5374
5526
  */
5375
5527
  getCellContent(): Promise<CellContent>;
5376
5528
  /**
5377
- * 범위 전체의 값·표시 문자열·수식을 행 우선 2차원 배열로 반환한다. 배열 크기는 범위 크기와 같다.
5529
+ * Returns the values, displayed strings, and formulas of the whole range as a row-major two-dimensional array. The array has the same size as the range.
5530
+ *
5531
+ * @returns Formulas start with `=`. Array formula cells are in the form `{=...}`
5378
5532
  */
5379
5533
  getCellContents(): Promise<CellContent[][]>;
5380
5534
  /**
5381
- * 범위 첫 행의 높이(px)를 반환한다.
5535
+ * Returns the height (px) of the first row of the range.
5382
5536
  */
5383
5537
  getRowHeight(): Promise<number>;
5384
5538
  /**
5385
- * 범위 첫 열의 너비(px)를 반환한다.
5539
+ * Returns the width (px) of the first column of the range.
5386
5540
  */
5387
5541
  getColumnWidth(): Promise<number>;
5388
5542
  /**
5389
- * 범위에 걸친 행의 높이를 지정한다. 숨긴 행에 높이를 지정하면 숨김도 함께 풀린다.
5390
- * 0 이하를 주면 높이를 바꾸지 않고 행을 숨긴다.
5391
- * 지정한 행은 높이가 고정되어 내용이 바뀌어도 자동으로 맞춰지지 않는다.
5543
+ * Sets the height of the rows spanned by the range. Setting a height on a hidden row also unhides it.
5544
+ * Passing 0 or less hides the rows without changing the height.
5545
+ * The specified rows have a fixed height, so they are not adjusted automatically when the content changes.
5392
5546
  *
5393
- * @param height - 행 높이(px)
5547
+ * @param height - row height (px)
5394
5548
  */
5395
5549
  setRowHeight(height: number): Promise<void>;
5396
5550
  /**
5397
- * 범위에 걸친 열의 너비를 지정한다. 숨긴 열에 너비를 지정하면 숨김도 함께 풀린다.
5398
- * 0 이하를 주면 너비를 바꾸지 않고 열을 숨긴다.
5399
- * 지정한 열은 너비가 고정되어 내용이 바뀌어도 자동으로 넓어지지 않는다.
5551
+ * Sets the width of the columns spanned by the range. Setting a width on a hidden column also unhides it.
5552
+ * Passing 0 or less hides the columns without changing the width.
5553
+ * The specified columns have a fixed width, so they are not widened automatically when the content changes.
5400
5554
  *
5401
- * @param width - 열 너비(px)
5555
+ * @param width - column width (px)
5402
5556
  */
5403
5557
  setColumnWidth(width: number): Promise<void>;
5404
5558
  /**
5405
- * 범위에 걸친 행의 높이를 각 행의 내용에 맞춰 조정한다. 조정한 행은 이후 내용이 바뀔 때도 높이가 자동으로 맞춰진다.
5559
+ * Autofits the height of the rows spanned by the range to the content of each row. An adjusted row is autofitted again whenever the content or format of a cell changes afterward.
5406
5560
  */
5407
5561
  autofitRows(): Promise<void>;
5408
5562
  /**
5409
- * 범위에 걸친 열의 너비를 각 열의 내용에 맞춰 조정한다. 조정한 열은 이후 값을 넣거나 글꼴 크기·들여쓰기를 바꿀 때 숫자 셀의 내용에 맞춰 너비가 넓어질 수 있다.
5563
+ * Autofits the width of the columns spanned by the range to the content of each column. An adjusted column may be widened automatically whenever the content or format of a number cell changes afterward.
5410
5564
  */
5411
5565
  autofitColumns(): Promise<void>;
5412
5566
  /**
5413
- * 범위의 첫 행 자리에 행을 삽입한다. 앞 행의 서식을 따라간다. 시트의 첫 행 자리에 삽입하면 서식 없는 행이 들어간다.
5567
+ * Inserts rows at the position of the first row of the range. The inserted rows follow the format of the row before. Inserting at the first row of the sheet inserts a row with no format.
5414
5568
  *
5415
- * @param count - 삽입할 행 수. 1 이상이 아니면 범위의 행 수만큼 삽입한다
5569
+ * @param count - number of rows to insert. If it is not 1 or greater, as many rows as the range spans are inserted
5416
5570
  */
5417
5571
  insertRow(count?: number | null): Promise<void>;
5418
5572
  /**
5419
- * 범위에 걸친 행을 삭제한다. 범위가 표의 데이터 영역을 통째로 덮으면 표가 사라지지 않도록 데이터 행 하나를 남긴다.
5573
+ * Deletes the rows spanned by the range. If the range covers the entire data area of a table, one data row is kept so that the table does not disappear.
5420
5574
  */
5421
5575
  deleteRow(): Promise<void>;
5422
5576
  /**
5423
- * 범위의 첫 열 자리에 열을 삽입한다. 앞 열의 서식을 따라간다. 시트의 첫 열 자리에 삽입하면 서식 없는 열이 들어간다.
5577
+ * Inserts columns at the position of the first column of the range. The inserted columns follow the format of the column before. Inserting at the first column of the sheet inserts a column with no format.
5424
5578
  *
5425
- * @param count - 삽입할 열 수. 1 이상이 아니면 범위의 열 수만큼 삽입한다
5579
+ * @param count - number of columns to insert. If it is not 1 or greater, as many columns as the range spans are inserted
5426
5580
  */
5427
5581
  insertColumn(count?: number | null): Promise<void>;
5428
5582
  /**
5429
- * 범위에 걸친 열을 삭제한다.
5430
- * 시트의 모든 열이나 숨기지 않은 마지막 열까지 없어질 때, 틀 고정 오른쪽 영역이 통째로 없어질 때는 삭제할 수 없다.
5583
+ * Deletes the columns spanned by the range.
5584
+ * The columns cannot be deleted if all columns of the sheet or the last visible column would be removed, or if the entire area to the right of the freeze panes would be removed.
5431
5585
  */
5432
5586
  deleteColumn(): Promise<void>;
5433
5587
  /**
5434
- * 범위에 걸친 행을 표시하거나 숨긴다. visible 이 null 이거나 undefined 면 아무것도 하지 않는다.
5588
+ * Shows or hides the rows spanned by the range.
5435
5589
  *
5436
- * @param visible - true 면 표시, false 면 숨김
5590
+ * @param visible - true to show, false to hide
5437
5591
  */
5438
5592
  setRowVisible(visible: boolean): Promise<void>;
5439
5593
  /**
5440
- * 범위에 걸친 열을 표시하거나 숨긴다. visible 이 null 이거나 undefined 면 아무것도 하지 않는다.
5594
+ * Shows or hides the columns spanned by the range.
5441
5595
  *
5442
- * @param visible - true 면 표시, false 면 숨김
5596
+ * @param visible - true to show, false to hide
5443
5597
  */
5444
5598
  setColumnVisible(visible: boolean): Promise<void>;
5445
5599
  /**
5446
- * 범위 첫 행이 표시 상태인지 반환한다.
5600
+ * Returns whether the first row of the range is visible.
5447
5601
  */
5448
5602
  isRowVisible(): Promise<boolean | undefined>;
5449
5603
  /**
5450
- * 범위 첫 열이 표시 상태인지 반환한다.
5604
+ * Returns whether the first column of the range is visible.
5451
5605
  */
5452
5606
  isColumnVisible(): Promise<boolean | undefined>;
5453
5607
  /**
5454
- * 범위의 모든 셀에 같은 값을 넣는다. 값은 문자열로 바꾼 뒤 해석하므로 "=" 로 시작하면 수식이 되고, "{=...}" 형태이면 범위 전체를 한 덩어리로 묶는 배열 수식이 된다.
5455
- * 범위가 기존 배열 수식 영역 안의 셀 하나이면 그 영역 전체를 다시 입력한다.
5456
- * 배열 수식은 병합 셀이나 표 영역에 넣을 수 없다.
5457
- * null 은 빈 셀이 되고, 객체는 JSON 표기로 들어가며, Date 처럼 문자열 표기를 갖는 객체는 그 문자열이 들어간다.
5458
- * 배열은 원소를 각각 같은 규칙으로 바꿔 콤마로 이어 넣는다.
5608
+ * Enters the same value into every cell of the range. The value is converted to a string and then interpreted, so a value starting with "=" becomes a formula, and a value in the form "{=...}" becomes an array formula that binds the whole range as one unit.
5609
+ * If the number format of the top-left cell of the range is text, a value starting with "=" also does not become a formula and is entered as a string in the whole range.
5610
+ * If the range is a single cell inside an existing array formula area, the entire area is entered again.
5611
+ * An array formula cannot be entered into a merged cell or a table area.
5612
+ * null becomes an empty cell, an object is entered in JSON notation, and an object that has a string notation, such as Date, is entered as that string.
5613
+ * An array is entered by converting each element by the same rules and joining the results with commas.
5459
5614
  *
5460
- * @param value - 넣을 값. 자기 자신을 품은 배열·객체처럼 문자열 표기를 얻을 수 없는 값은 넣을 수 없다
5615
+ * @param value - value to enter into the cells. A value that cannot be converted to a string, such as an array or object with a circular structure, cannot be entered
5461
5616
  */
5462
5617
  setValue(value: string | number | boolean | null | Date | Record<string, unknown> | any[]): Promise<void>;
5463
5618
  /**
5464
- * 범위의 셀마다 다른 값을 넣는다. 바깥 배열 인덱스가 범위 안의 행, 안쪽 배열 인덱스가 범위 안의 열에 대응하며 크기가 범위와 정확히 같아야 한다.
5465
- * 각 값의 해석은 setValue 와 같지만 배열 수식은 넣을 수 없다.
5466
- * null 과 undefined 는 빈 셀이 된다.
5467
- * 전체 행·열 범위에는 쓸 수 없다.
5619
+ * Enters a different value into each cell of the range. The outer array index corresponds to the row in the range and the inner array index corresponds to the column in the range, and the size must be exactly the same as the range.
5620
+ * Each value is interpreted as in setValue, so a value starting with "=" becomes a formula, but an array formula cannot be entered.
5621
+ * null and undefined become empty cells.
5622
+ * It cannot be used on an entire-row or entire-column range.
5468
5623
  *
5469
- * @param values - 범위 크기와 같은 행 우선 2차원 배열
5624
+ * @param values - row-major two-dimensional array with the same size as the range
5470
5625
  */
5471
5626
  setValues(values: (string | number | boolean | null | undefined | Date | Record<string, unknown> | any[])[][]): Promise<void>;
5472
5627
  /**
5473
- * 범위 안 모든 셀의 값과 수식을 지운다. 서식은 그대로 남는다.
5628
+ * Clears the values and formulas of all cells in the range. Formats are kept.
5474
5629
  */
5475
5630
  deleteValue(): Promise<void>;
5476
5631
  /**
5477
- * 범위에 굵게를 적용하거나 해제한다.
5632
+ * Applies or removes bold for the range.
5478
5633
  *
5479
- * @param isOn - true 면 적용, false 면 해제
5634
+ * @param isOn - true to apply, false to remove
5480
5635
  */
5481
5636
  setFontBold(isOn: boolean): Promise<void>;
5482
5637
  /**
5483
- * 범위에 기울임을 적용하거나 해제한다.
5638
+ * Applies or removes italic for the range.
5484
5639
  *
5485
- * @param isOn - true 면 적용, false 면 해제
5640
+ * @param isOn - true to apply, false to remove
5486
5641
  */
5487
5642
  setFontItalic(isOn: boolean): Promise<void>;
5488
5643
  /**
5489
- * 범위에 밑줄을 적용하거나 해제한다.
5644
+ * Applies or removes underline for the range.
5490
5645
  *
5491
- * @param isOn - true 면 적용, false 면 해제. false 면 isDouble 은 무시된다
5492
- * @param isDouble - true 면 이중 밑줄, false 면 실선 밑줄 (기본값: false)
5646
+ * @param isOn - true to apply, false to remove. If false, isDouble is ignored
5647
+ * @param isDouble - true for double underline, false for single underline (default: false)
5493
5648
  */
5494
5649
  setFontUnderline(isOn: boolean, isDouble?: boolean): Promise<void>;
5495
5650
  /**
5496
- * 범위에 취소선을 적용하거나 해제한다.
5651
+ * Applies or removes strikethrough for the range.
5497
5652
  *
5498
- * @param isOn - true 면 적용, false 면 해제
5653
+ * @param isOn - true to apply, false to remove
5499
5654
  */
5500
5655
  setFontStrikethrough(isOn: boolean): Promise<void>;
5501
5656
  /**
5502
- * 범위 좌상단 셀이 굵게인지 반환한다.
5657
+ * Returns whether the top-left cell of the range is bold.
5503
5658
  *
5504
- * @returns 굵게가 아니면 undefined 다
5659
+ * @returns undefined if the cell is not bold
5505
5660
  */
5506
5661
  isFontBold(): Promise<boolean | undefined>;
5507
5662
  /**
5508
- * 범위 좌상단 셀이 기울임인지 반환한다.
5663
+ * Returns whether the top-left cell of the range is italic.
5509
5664
  *
5510
- * @returns 기울임이 아니면 undefined 다
5665
+ * @returns undefined if the cell is not italic
5511
5666
  */
5512
5667
  isFontItalic(): Promise<boolean | undefined>;
5513
5668
  /**
5514
- * 범위 좌상단 셀의 밑줄 종류를 반환한다.
5669
+ * Returns the underline type of the top-left cell of the range.
5515
5670
  *
5516
- * @returns 밑줄이 없으면 undefined 다
5671
+ * @returns undefined if there is no underline
5517
5672
  */
5518
5673
  getFontUnderline(): Promise<"single" | "double" | undefined>;
5519
5674
  /**
5520
- * 범위 좌상단 셀에 취소선이 있는지 반환한다.
5675
+ * Returns whether the top-left cell of the range has strikethrough.
5521
5676
  *
5522
- * @returns 취소선이 없으면 undefined 다
5677
+ * @returns undefined if there is no strikethrough
5523
5678
  */
5524
5679
  isFontStrikethrough(): Promise<boolean | undefined>;
5525
5680
  /**
5526
- * 범위의 글꼴을 바꾼다.
5681
+ * Changes the font of the range.
5527
5682
  *
5528
- * @param name - 글꼴 이름
5683
+ * @param name - font name
5529
5684
  */
5530
5685
  setFontName(name: string): Promise<void>;
5531
5686
  /**
5532
- * 범위의 글꼴 크기를 바꾼다.
5687
+ * Changes the font size of the range.
5533
5688
  *
5534
- * @param size - 글꼴 크기(pt)
5689
+ * @param size - font size (pt)
5535
5690
  */
5536
5691
  setFontSize(size: number | string): Promise<void>;
5537
5692
  /**
5538
- * 범위의 글꼴 색을 바꾼다.
5693
+ * Changes the font color of the range.
5539
5694
  *
5540
- * @param color - "#RRGGBB" 형식의 색
5695
+ * @param color - color in "#RRGGBB" format
5541
5696
  */
5542
5697
  setFontColor(color: string): Promise<void>;
5543
5698
  /**
5544
- * 범위 좌상단 셀의 글꼴 이름을 반환한다. 글꼴을 따로 지정하지 않은 셀에는 문서 기본 글꼴 이름이 담긴다.
5699
+ * Returns the font name of the top-left cell of the range. A cell with no font specified holds the default font name of the document.
5545
5700
  */
5546
5701
  getFontName(): Promise<string | undefined>;
5547
5702
  /**
5548
- * 범위 좌상단 셀의 글꼴 크기(pt)를 반환한다. 크기를 따로 지정하지 않은 셀에는 문서 기본 크기가 담긴다.
5703
+ * Returns the font size (pt) of the top-left cell of the range. A cell with no size specified holds the default size of the document.
5549
5704
  */
5550
5705
  getFontSize(): Promise<number | undefined>;
5551
5706
  /**
5552
- * 범위 좌상단 셀의 글꼴 색을 반환한다. 색을 따로 지정하지 않은 셀에는 문서 기본 색이 담긴다.
5707
+ * Returns the font color of the top-left cell of the range. A cell with no color specified holds the default color of the document.
5553
5708
  *
5554
- * @returns "#RRGGBB" 형식의 색
5709
+ * @returns color in "#RRGGBB" format
5555
5710
  */
5556
5711
  getFontColor(): Promise<string | undefined>;
5557
5712
  /**
5558
- * 범위 좌상단 셀의 글꼴 서식을 한 번에 반환한다. 각 항목은 같은 이름의 개별 조회 메서드와 같되, underline 만 밑줄이 없을 때 undefined 가 아니라 "none" 이다.
5713
+ * Returns the font format of the top-left cell of the range in a single call. Each item matches the getter of the same name, except that underline is "none", not undefined, when there is no underline.
5559
5714
  *
5560
- * @returns 셀에 서식 정보가 없으면 undefined 다
5715
+ * @returns undefined if the cell has no format information
5561
5716
  */
5562
5717
  getFont(): Promise<FontInfo | undefined>;
5563
5718
  /**
5564
- * 범위를 단색 바탕색으로 채운다. 색을 주지 않으면 채우기를 지운다.
5719
+ * Fills the range with a solid background color. If no color is given, the fill is cleared.
5565
5720
  *
5566
- * @param color - "#RRGGBB" 형식의 색. null·undefined·빈 문자열이면 채우기를 지운다
5721
+ * @param color - color in "#RRGGBB" format. If null, undefined, or an empty string, the fill is cleared
5567
5722
  */
5568
5723
  setBackgroundColor(color?: string | null): Promise<void>;
5569
5724
  /**
5570
- * 범위의 가로 정렬을 지정한다. 지정과 함께 범위의 들여쓰기가 0 으로 초기화된다.
5571
- * HorizontalAlign 밖의 값도 검증 없이 저장되며, "centerContinuous" 와 "center-across" 는 가운데로, 그 밖의 값은 왼쪽으로 그려진다.
5725
+ * Sets the horizontal alignment of the range. Setting it also resets the indent of the range to 0.
5572
5726
  *
5573
- * @param value - 가로 정렬
5727
+ * @param value - horizontal alignment
5574
5728
  */
5575
5729
  setHorizontalAlign(value: HorizontalAlign): Promise<void>;
5576
5730
  /**
5577
- * 범위의 세로 정렬을 지정한다. VerticalAlign 밖의 값도 검증 없이 저장되며, "distributed" 는 가운데로, 그 밖의 값은 아래로 그려진다.
5731
+ * Sets the vertical alignment of the range.
5578
5732
  *
5579
- * @param value - 세로 정렬
5733
+ * @param value - vertical alignment
5580
5734
  */
5581
5735
  setVerticalAlign(value: VerticalAlign): Promise<void>;
5582
5736
  /**
5583
- * 범위에 텍스트 줄바꿈을 적용하거나 해제한다.
5737
+ * Applies or removes text wrapping for the range.
5584
5738
  *
5585
- * @param isOn - true 면 적용, false 면 해제
5739
+ * @param isOn - true to apply, false to remove
5586
5740
  */
5587
5741
  setWrapText(isOn: boolean): Promise<void>;
5588
5742
  /**
5589
- * 범위 좌상단 셀의 바탕색을 반환한다. 채우기가 없을 때는 물론 그라디언트 채우기일 때도 색 하나로 표현할 수 없어 undefined 다. 채우기 종류까지 알아야 하면 getFill 을 쓴다.
5743
+ * Returns the background color of the top-left cell of the range. It is undefined when there is no fill, and also for a gradient fill because it cannot be expressed as a single color. Use getFill if the fill type is also needed.
5590
5744
  *
5591
- * @returns "#RRGGBB" 형식의 색
5745
+ * @returns color in "#RRGGBB" format
5592
5746
  */
5593
5747
  getBackgroundColor(): Promise<string | undefined>;
5594
5748
  /**
5595
- * 범위 좌상단 셀의 가로 정렬을 반환한다. 명시 지정된 값만 반환하며, HorizontalAlign 밖의 값이 반환될 수 있다.
5749
+ * Returns the horizontal alignment of the top-left cell of the range. Returns only an explicitly set value, and a value outside HorizontalAlign can be returned.
5596
5750
  *
5597
- * @returns 지정이 없으면 undefined 다
5751
+ * @returns undefined if not set
5598
5752
  */
5599
5753
  getHorizontalAlign(): Promise<string | undefined>;
5600
5754
  /**
5601
- * 범위 좌상단 셀의 세로 정렬을 반환한다. 명시 지정된 값만 반환하며, VerticalAlign 밖의 값이 반환될 수 있다.
5602
- * 지정이 없는 셀은 아래쪽으로 그려진다.
5755
+ * Returns the vertical alignment of the top-left cell of the range. Returns only an explicitly set value, and a value outside VerticalAlign can be returned.
5603
5756
  *
5604
- * @returns 지정이 없으면 undefined 다
5757
+ * @returns undefined if not set
5605
5758
  */
5606
5759
  getVerticalAlign(): Promise<string | undefined>;
5607
5760
  /**
5608
- * 범위 좌상단 셀에 텍스트 줄바꿈이 적용되어 있는지 반환한다.
5761
+ * Returns whether text wrapping is applied to the top-left cell of the range.
5609
5762
  *
5610
- * @returns 줄바꿈이 적용되어 있지 않으면 undefined 다
5763
+ * @returns undefined if text wrapping is not applied
5611
5764
  */
5612
5765
  isWrapText(): Promise<boolean | undefined>;
5613
5766
  /**
5614
- * 범위 좌상단 셀의 채우기를 반환한다. 그라디언트 채우기는 종류만 담기고 색·방향 등 나머지는 담기지 않는다.
5767
+ * Returns the fill of the top-left cell of the range. A gradient fill holds only its type, without the color, direction, and other details.
5615
5768
  *
5616
- * @returns 채우기가 없으면 undefined 다
5769
+ * @returns undefined if there is no fill
5617
5770
  */
5618
5771
  getFill(): Promise<FillInfo | undefined>;
5619
5772
  /**
5620
- * 범위 좌상단 셀의 정렬 서식을 한 번에 반환한다. 각 항목은 같은 이름의 개별 조회 메서드와 같다.
5773
+ * Returns the alignment format of the top-left cell of the range in a single call. Each item matches the getter of the same name.
5621
5774
  *
5622
- * @returns 셀에 서식 정보가 없으면 undefined 다
5775
+ * @returns undefined if the cell has no format information
5623
5776
  */
5624
5777
  getAlignment(): Promise<AlignmentInfo | undefined>;
5625
5778
  /**
5626
- * 범위의 들여쓰기 수준을 1 올린다. 범위의 가로 정렬이 왼쪽이나 오른쪽 하나로 통일되어 있지 않으면 먼저 범위 전체를 왼쪽 정렬로 바꾼 뒤 올린다.
5779
+ * Increases the indent level of the range by 1. If the horizontal alignment of the range is not uniformly left or right, the whole range is first changed to left alignment and then the indent level is increased.
5627
5780
  */
5628
5781
  increaseIndent(): Promise<void>;
5629
5782
  /**
5630
- * 범위의 들여쓰기 수준을 1 내린다. 0 보다 아래로는 내려가지 않는다.
5783
+ * Decreases the indent level of the range by 1. It does not go below 0.
5631
5784
  */
5632
5785
  decreaseIndent(): Promise<void>;
5633
5786
  /**
5634
- * 범위 좌상단 셀의 들여쓰기 수준을 반환한다.
5787
+ * Returns the indent level of the top-left cell of the range.
5635
5788
  *
5636
- * @returns 들여쓰기가 지정되어 있지 않으면 0 이다
5789
+ * @returns 0 if no indent is set
5637
5790
  */
5638
5791
  getIndent(): Promise<number>;
5639
5792
  /**
5640
- * 범위에 테두리를 적용하거나 지운다. type 이 "none" 이면 범위의 테두리를 모두 지우고, 그 밖의 type 은 기존 테두리에 type 이 가리키는 테두리를 병합한다.
5641
- * lineStyle 이 "none" 이면 type 이 가리키는 자리의 선만 지우며 color 는 무시된다.
5642
- * 그릴 내부 선이 없으면 "center"·"middle"·"cross" 는 아무것도 하지 않는다.
5793
+ * Applies or clears borders on the range. If type is "none", all borders of the range are cleared, and for any other type, the border that type refers to is merged into the existing borders.
5794
+ * If lineStyle is "none", only the line at the position that type refers to is cleared and color is ignored.
5795
+ * If there is no inner line to draw, "center", "middle", and "cross" do nothing.
5643
5796
  *
5644
- * @param type - 테두리를 그릴 자리
5645
- * @param lineStyle - 선 스타일 (기본값: "thin")
5646
- * @param color - "#RRGGBB" 형식의 선 색 (기본값: "#000000")
5797
+ * @param type - position to draw the border
5798
+ * @param lineStyle - line style (default: "thin")
5799
+ * @param color - line color in "#RRGGBB" format (default: "#000000")
5647
5800
  */
5648
5801
  setBorder(type: BorderType, lineStyle?: BorderLineStyle | null, color?: string | null): Promise<void>;
5649
5802
  /**
5650
- * 범위 좌상단 셀의 테두리를 네 변과 대각선으로 나눠 반환한다. 실제로 그려진 선만 담긴다.
5803
+ * Returns the borders of the top-left cell of the range, split into the four edges and the diagonal. Only lines that are set are included.
5651
5804
  *
5652
- * @returns 셀에 서식 정보가 없으면 undefined 다
5805
+ * @returns undefined if the cell has no format information
5653
5806
  */
5654
5807
  getBorder(): Promise<BorderInfo | undefined>;
5655
5808
  /**
5656
- * 범위의 셀 서식(글꼴·채우기·정렬·테두리·표시 형식)을 지우고 범위 안의 병합을 해제한다. 값과 수식은 남는다.
5657
- * 행 전체·열 전체 범위가 병합과 겹치면 오류가 난다.
5809
+ * Clears the cell formats (font, fill, alignment, border, and number format) of the range and unmerges the merges in the range. Values and formulas are kept.
5810
+ * Throws an error if an entire-row or entire-column range overlaps a merged area.
5658
5811
  */
5659
5812
  clearFormat(): Promise<void>;
5660
5813
  /**
5661
- * 범위의 모든 내용을 지운다. 값·수식·서식·병합·하이퍼링크·메모·데이터 유효성·스파크라인·필터·표가 대상이다.
5662
- * 행 전체·열 전체 범위가 병합과 겹치면 오류가 난다.
5814
+ * Clears all content of the range. The targets are values, formulas, formats, merges, hyperlinks, comments, data validation, sparklines, filters, and tables.
5815
+ * Throws an error if an entire-row or entire-column range overlaps a merged area.
5663
5816
  */
5664
5817
  clearAll(): Promise<void>;
5665
5818
  /**
5666
- * 범위의 셀을 하나로 병합한다. 병합한 셀에는 좌상단 셀의 값만 남고 나머지 값은 사라진다.
5667
- * 범위가 셀 하나이거나 표와 겹치면 아무것도 하지 않는다.
5668
- * 병합이 범위 밖까지 걸쳐 있으면 오류가 난다.
5819
+ * Merges the cells of the range into one. Only the value of the top-left cell remains in the merged cell, and the other values are lost.
5820
+ * Does nothing if the range is a single cell or overlaps a table.
5821
+ * If an existing merged area only partly overlaps the range, the cells cannot be merged and an error is thrown.
5669
5822
  */
5670
5823
  merge(): Promise<void>;
5671
5824
  /**
5672
- * 범위와 겹치는 병합을 모두 해제한다.
5825
+ * Unmerges all merged areas that overlap the range.
5673
5826
  */
5674
5827
  unmerge(): Promise<void>;
5675
5828
  /**
5676
- * 범위와 겹치는 병합 영역의 주소를 A1 문자열 배열로 반환한다. 일부만 겹치는 병합도 범위에 맞춰 잘라내지 않고 병합 영역 전체 주소를 준다. 시트 전체의 병합 목록은 Worksheet.getMergeCellList 로 조회한다.
5829
+ * Returns the addresses of the merged areas that overlap the range as an array of A1 strings. A merge that overlaps only partly is not cut to fit the range, and the address of the entire merged area is returned. Use Worksheet.getMergeCellList to get the merge list of the whole sheet.
5677
5830
  */
5678
5831
  getMergeCellList(): Promise<string[]>;
5679
5832
  /**
5680
- * 범위의 표시 형식을 형식 코드로 지정한다. 넘긴 코드는 사용자 정의 형식으로 저장된다.
5833
+ * Sets the number format of the range by format code. The given code is saved as a custom format.
5681
5834
  *
5682
- * @param formatCode - 엑셀 호환 형식 코드 ("#,##0.00", "yyyy-mm-dd", "0.00%" 등)
5835
+ * @param formatCode - Excel-compatible format code (such as "#,##0.00", "yyyy-mm-dd", or "0.00%")
5683
5836
  */
5684
5837
  setNumberFormat(formatCode: string): Promise<void>;
5685
5838
  /**
5686
- * 범위 좌상단 셀의 표시 형식을 반환한다. 형식을 따로 지정하지 않은 셀에도 문서 기본 형식의 코드가 담긴다.
5839
+ * Returns the number format of the top-left cell of the range. A cell with no format specified also returns the code of the document default format.
5687
5840
  *
5688
- * @returns formatCode 는 setNumberFormat 에 그대로 넘길 수 있는 형식 코드다
5841
+ * @returns number format code that can be passed as is to setNumberFormat
5689
5842
  */
5690
- getNumberFormat(): Promise<{
5691
- formatCode: string;
5692
- }>;
5843
+ getNumberFormat(): Promise<string>;
5693
5844
  /**
5694
- * 범위에 조건부 서식 규칙을 추가한다. 추가한 규칙이 기존 규칙보다 먼저 적용된다.
5695
- * 규칙 내용이 잘못되었다면 동작하지 않는다.
5845
+ * Adds a conditional format rule to the range. The added rule has a higher priority than the existing rules.
5696
5846
  *
5697
- * @param rule - 추가할 규칙
5847
+ * @param rule - rule to add
5698
5848
  */
5699
5849
  addConditionalFormat(rule: ConditionalFormatRule): Promise<void>;
5700
5850
  /**
5701
- * 범위와 겹치는 조건부 서식 규칙을 지운다. 규칙이 범위 밖까지 걸쳐 있으면 겹치는 부분만 규칙의 적용 범위에서 빼고, 규칙 전체가 범위 안에 들면 규칙 자체를 지운다.
5851
+ * Clears the conditional format rules that overlap the range. If a rule extends beyond the range, only the overlapping part is removed from the applied range of the rule, and if the whole rule is inside the range, the rule itself is removed.
5702
5852
  */
5703
5853
  clearConditionalFormats(): Promise<void>;
5704
5854
  /**
5705
- * 범위에 데이터 유효성 검사 규칙을 적용한다. 셀 하나에는 규칙 하나만 걸리므로, 겹치는 기존 규칙은 겹치는 만큼 적용 범위에서 물러나고 이 규칙으로 바뀐다.
5706
- * 규칙 내용이 잘못되었다면 동작하지 않는다.
5855
+ * Applies a data validation rule to the range. A range reference of the list type must start with `=`, and without `=` it is treated as a comma-separated list.
5707
5856
  *
5708
- * @param rule - 규칙 객체. type 은 DataValidationType, operator 는 DataValidationOperator, errorStyle 은 DataValidationErrorStyle 어휘를 쓰며, 타입에 따라 formula 와 안내·오류 메시지를 함께 담는다
5857
+ * @param rule - rule to apply
5709
5858
  */
5710
- setDataValidation(rule: Record<string, unknown>): Promise<void>;
5859
+ setDataValidation(rule: DataValidationRule): Promise<void>;
5711
5860
  /**
5712
- * 범위와 겹치는 데이터 유효성 검사 규칙을 지운다. 규칙이 범위 밖까지 걸쳐 있으면 겹치는 부분만 적용 범위에서 뺀다.
5861
+ * Clears the data validation rules that overlap the range.
5713
5862
  */
5714
5863
  clearDataValidation(): Promise<void>;
5715
5864
  /**
5716
- * 범위를 지정한 열의 값 기준으로 정렬한다. 범위가 필터나 표 영역 안의 셀 하나이면 그 필터의 정렬로 처리되어 정렬 상태가 문서에 남는다. 머리글 행은 자동으로 가려낸다.
5717
- * 정렬할 값이 없거나 범위 안 병합의 크기가 제각각이면 정렬할 수 없다.
5865
+ * Sorts the range by the values of the specified column. If the range is a single cell inside a filter or table area, it is processed as the sort of that filter, so the sort state remains in the document. The header row is detected automatically.
5866
+ * The range cannot be sorted if there are no values to sort or if the merges in the range vary in size.
5718
5867
  *
5719
- * @param key - 정렬 기준 열. 범위의 첫 열을 0 으로 세는 0-based 오프셋이며 범위 너비를 벗어날 수 없다
5720
- * @param order - 정렬 방향. SortOrder 의 오름차순·내림차순 두 값만 받는다
5721
- * @param options - 아직 지원하지 않는 예약 인자. 값이 담긴 객체를 주면 정렬하지 않는다
5868
+ * @param key - column to sort by. It is a 0-based offset where the first column of the range is 0 and cannot exceed the width of the range
5869
+ * @param order - sort order
5722
5870
  */
5723
- sort(key: number, order: SortOrder, options?: Record<string, unknown>): Promise<void>;
5871
+ sort(key: number, order: SortOrder): Promise<void>;
5724
5872
  /**
5725
- * 범위 좌상단 셀에 메모를 넣는다. 메모가 이미 있으면 본문만 바꾸고 표시 상태와 위치는 그대로 둔다.
5873
+ * Adds a comment to the top-left cell of the range. If a comment already exists, only its text is changed, and its visibility and position are kept.
5726
5874
  *
5727
- * @param text - 메모 본문. 서식 없는 텍스트이며 줄바꿈은 "\n" 이다
5875
+ * @param text - comment text. It is unformatted text, and a line break is "\n"
5728
5876
  */
5729
5877
  setComment(text: string): Promise<void>;
5730
5878
  /**
5731
- * 범위 안의 메모를 모두 지운다.
5879
+ * Deletes all comments in the range.
5732
5880
  */
5733
5881
  deleteComment(): Promise<void>;
5734
5882
  /**
5735
- * 범위 좌상단 셀 메모의 표시 상태를 바꾼다. 메모가 없다면 동작하지 않는다.
5883
+ * Changes the visibility of the comment on the top-left cell of the range.
5736
5884
  *
5737
- * @param visible - true 면 항상 표시, false 면 마우스를 올렸을 때만 표시
5885
+ * @param visible - true to always show, false to show only on mouse hover
5738
5886
  */
5739
5887
  setCommentVisible(visible: boolean): Promise<void>;
5740
5888
  /**
5741
- * 범위와 겹치는 하이퍼링크 목록을 반환한다. 일부만 겹치는 링크도 포함한다.
5889
+ * Returns the list of hyperlinks that overlap the range. Links that overlap only partly are included.
5742
5890
  */
5743
5891
  getHyperlinkList(): Promise<HyperlinkInfo[]>;
5744
5892
  /**
5745
- * 범위에 하이퍼링크를 넣는다. 링크와 링크 서식(파란색 밑줄)은 범위 전체에 들어가지만 표시 텍스트는 좌상단 셀에만 들어간다.
5893
+ * Adds a hyperlink to the range. The link and the link format (blue underline) are applied to the whole range, but the display text is entered only in the top-left cell.
5894
+ *
5895
+ * @param location - link target. It accepts a web address, an email address, a reference in the document ("Sheet1!A1"), or a defined name, and the link cannot be set if it is not in a format that matches type
5896
+ * @param display - display text to enter in the top-left cell. If the cell value is a number or a string that contains a line break, display is ignored and the cell value is kept. If the cell value is any other string, it is replaced with display, and if the cell is empty, display is entered, and location is entered if display is omitted.
5897
+ * @param type - link type. If omitted, it is determined from location.
5746
5898
  */
5747
- setHyperlink(options: HyperlinkOptions): Promise<void>;
5899
+ setHyperlink(location: string, display?: string | null, type?: HyperlinkType | null): Promise<void>;
5748
5900
  /**
5749
- * 범위와 포함 관계인 하이퍼링크를 지운다. 범위가 링크를 품거나 링크가 범위를 품는 경우이며, 일부만 겹치는 링크는 남는다.
5750
- * 셀 값은 그대로 두고 링크 서식(파란색 밑줄)만 함께 지우며, 지운 링크와 겹쳐 있던 다른 링크의 서식은 되살린다.
5901
+ * Removes the hyperlinks that contain, or are contained in, the range. This covers links whose area is entirely inside the range and links whose area entirely contains the range. Links that overlap only partly are kept.
5902
+ * The cell value is kept and only the link format (blue underline) is cleared with it, and the format of another link that overlapped a removed link is restored.
5751
5903
  */
5752
5904
  removeHyperlink(): Promise<void>;
5753
5905
  }
5754
5906
  /**
5755
- * 워크시트에 놓인 차트 하나를 가리키는 핸들이다.
5756
- * 차트의 종류와 스타일, 제목·축 제목·범례·데이터레이블·눈금선, 데이터 소스 범위와 놓인 자리를 다룬다.
5907
+ * Represents a chart on a worksheet.
5908
+ * Reads and edits the chart type and style, chart elements such as the title and legend, the data source range, and the position of the chart.
5757
5909
  */
5758
5910
  interface Chart {
5759
5911
  /**
5760
- * 차트 종류를 반환한다. ChartType 에 없는 종류는 "unknown" 을 반환한다.
5912
+ * 차트 종류를 반환한다. 파일에서 읽은 100% 누적 막대형·거품형 차트는 ChartType 에 없는 그 종류의 이름을, 그 밖에 ChartType 에 없는 종류는 "unknown" 을 반환한다.
5761
5913
  */
5762
- getType(): Promise<string>;
5914
+ getType(): Promise<ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown">;
5763
5915
  /**
5764
5916
  * 이 차트를 편집할 수 있는지 반환한다. 외부 데이터를 소스로 하는 차트는 조회만 되고 편집은 되지 않는다.
5765
5917
  */
@@ -5779,9 +5931,9 @@ declare namespace Cell {
5779
5931
  */
5780
5932
  getLegendPosition(): Promise<ChartLegendPosition>;
5781
5933
  /**
5782
- * 데이터레이블 위치를 반환한다. 데이터레이블을 표시하지 않는 차트는 "none" 을 반환한다.
5934
+ * 데이터레이블 위치를 반환한다. 데이터레이블이 설정되지 않은 차트는 "none" 이고, 데이터레이블을 갖지 않는 차트 종류(표면형)는 null 을 반환한다.
5783
5935
  */
5784
- getDataLabelPosition(): Promise<ChartDataLabelPosition>;
5936
+ getDataLabelPosition(): Promise<ChartDataLabelPosition | null>;
5785
5937
  /**
5786
5938
  * 지정한 축의 눈금선 종류를 반환한다. 눈금선을 꺼 둔 축은 "none" 이고, 그 축의 눈금선을 갖지 않는 차트 종류(원형 계열·도넛은 양축, 방사형은 세로축)는 null 을 반환한다.
5787
5939
  *
@@ -5801,16 +5953,17 @@ declare namespace Cell {
5801
5953
  */
5802
5954
  setStyle(style: number): Promise<void>;
5803
5955
  /**
5804
- * 차트 제목을 설정한다.
5956
+ * 차트 제목을 설정한다. 빈 문자열을 넘기면 제목을 비운다.
5805
5957
  *
5806
- * @param title - 차트에 표시할 제목
5958
+ * @param title - 차트에 표시할 제목. 255자까지 지원한다
5807
5959
  */
5808
5960
  setTitle(title: string): Promise<void>;
5809
5961
  /**
5810
5962
  * 지정한 축의 제목을 설정한다. 축 제목은 원형 계열·도넛·방사형을 뺀 차트 종류에서 지원한다.
5963
+ * 빈 문자열을 넘기면 축 제목을 비운다.
5811
5964
  *
5812
5965
  * @param axis - 제목을 설정할 축(가로축 또는 세로축)
5813
- * @param title - 축에 표시할 제목
5966
+ * @param title - 축에 표시할 제목. 255자까지 지원한다
5814
5967
  */
5815
5968
  setAxisTitle(axis: ChartAxis, title: string): Promise<void>;
5816
5969
  /**
@@ -5820,266 +5973,273 @@ declare namespace Cell {
5820
5973
  */
5821
5974
  setLegendPosition(position: ChartLegendPosition): Promise<void>;
5822
5975
  /**
5823
- * 데이터레이블 위치를 설정한다. "none" 을 넘기면 데이터레이블을 숨긴다.
5824
- * 쓸 수 있는 위치는 차트 종류마다 다르며, "none" 은 모든 종류에서 쓸 수 있다.
5976
+ * 데이터레이블 위치를 설정한다. "none" 을 넘기면 데이터레이블을 없앤다.
5977
+ * 데이터레이블 설정은 2차원 차트(원형 대 원형·주식형·표면형 제외)에서만 쓸 수 있고, 3차원 차트는 현재 지원하지 않는다.
5978
+ * 쓸 수 있는 위치는 차트 종류마다 다르다.
5825
5979
  *
5826
5980
  * @param position - 데이터레이블을 놓을 자리
5827
5981
  */
5828
5982
  setDataLabelPosition(position: ChartDataLabelPosition): Promise<void>;
5829
5983
  /**
5830
5984
  * 지정한 축의 눈금선을 설정한다. "none" 을 넘기면 그 축의 눈금선을 숨긴다.
5831
- * 그 축의 눈금선을 갖지 않는 차트 종류(원형 계열·도넛은 양축, 방사형은 세로축)는 "none" 을 포함해 어떤 값을 넘겨도 오류가 발생한다.
5985
+ * 눈금선은 그 축의 눈금선을 갖는 차트 종류에서 지원한다(원형 계열·도넛은 양축, 방사형은 세로축이 없다).
5832
5986
  *
5833
5987
  * @param axis - 눈금선을 설정할 축(가로축 또는 세로축)
5834
5988
  * @param gridType - 표시할 눈금선 종류
5835
5989
  */
5836
5990
  setGridLine(axis: ChartAxis, gridType: ChartGridLineType): Promise<void>;
5837
5991
  /**
5838
- * 이 차트를 식별하는 고유 ID 를 반환한다.
5992
+ * Returns the unique ID that identifies this chart.
5839
5993
  */
5840
5994
  getId(): Promise<string>;
5841
5995
  /**
5842
- * 차트가 데이터로 삼는 셀 범위를 시트 이름을 앞에 붙인 A1 표기 문자열로 반환한다("Sheet1!A1:C5").
5843
- * 참조가 여러 시트에 걸쳐 있거나 하나의 사각 영역으로 합쳐지지 않으면 null 을 반환한다.
5996
+ * Returns the cell range that the chart uses as data, as an A1 notation string prefixed with the sheet name ("Sheet1!A1:C5").
5997
+ * Returns null if the references span multiple sheets or cannot be merged into a single rectangular range.
5844
5998
  */
5845
5999
  getDataRange(): Promise<string | null>;
5846
6000
  /**
5847
- * 차트의 서식 상태에 이 차트의 식별자와 데이터 범위를 더해 반환한다.
5848
- * 서식 값은 공통 표면이 주는 것과 같고, oid 와 range 만 셀이 더한다.
6001
+ * Returns the chart type, title, legend, data label, axis title, and gridline state, along with the identifier and data range, in a single call.
6002
+ * Each format value matches the getter of the same name.
5849
6003
  */
5850
6004
  getChartInfo(): Promise<ChartInfo>;
5851
6005
  /**
5852
- * 차트를 삭제한다.
6006
+ * Deletes the chart.
5853
6007
  */
5854
6008
  delete(): Promise<CommandResult>;
5855
6009
  /**
5856
- * 차트의 데이터 소스 범위를 바꾼다. 행과 열은 각각 100 개까지 지원한다.
5857
- * 시트를 지정하지 않으면 차트가 놓인 시트의 영역으로 처리한다.
5858
- * seriesBy 를 생략하면 지금의 시리즈 방향을 유지한다.
6010
+ * Changes the data source range of the chart. Up to 100 rows and 100 columns are supported.
6011
+ * If no sheet is specified, the range is treated as a range on the sheet that the chart is on.
6012
+ * If seriesBy is omitted, the current series direction is kept.
5859
6013
  *
5860
- * @param dataRange - 새 데이터 범위. A1 표기 문자열로도 지정할 수 있다("A1:B2", 단일 셀은 "E10", 다른 시트는 "Sheet2!A1:C5")
5861
- * @param seriesBy - 시리즈 방향. rows 는 행 하나가, columns 는 열 하나가 시리즈가 되고, auto 는 새 범위의 모양에 맞춰 정한다. 분산형과 거품형 차트는 rows·columns 를 받지 않는다
6014
+ * @param dataRange - new data range. An A1 notation string is also accepted ("A1:B2", "E10" for a single cell, or "Sheet2!A1:C5" for another sheet). A string accepts only one range (multiple ranges such as "A1:B2,D1:E2" are not accepted)
6015
+ * @param seriesBy - series direction. With rows, each row is one series, and with columns, each column is one series. With auto, the direction is determined by the shape of the new range. Scatter and bubble charts do not accept rows or columns
5862
6016
  */
5863
6017
  setDataRange(dataRange: string | SheetRangeCoords | RangeCoords, seriesBy?: "auto" | "rows" | "columns"): Promise<void>;
5864
6018
  /**
5865
- * 데이터의 행과 열을 맞바꿔 시리즈 방향을 전환한다. 호출할 때마다 방향이 번갈아 바뀐다.
5866
- * 분산형과 거품형 차트는 전환할 수 없고, 데이터 범위가 없거나 행이나 열이 100개를 넘는 차트도 전환할 수 없다.
6019
+ * Switches the series direction by swapping the rows and columns of the data. The direction alternates each time this is called.
6020
+ * Scatter and bubble charts and charts without a data range cannot be switched. Up to 100 rows and 100 columns are supported.
5867
6021
  */
5868
6022
  switchRowColumn(): Promise<void>;
5869
6023
  /**
5870
- * 차트의 왼쪽 위 모서리를 지정한 셀로 옮긴다. 크기는 그대로 둔다.
5871
- * startCell 에 여러 셀로 이루어진 범위를 넘기면 그 범위의 왼쪽 위 셀만 쓰고 나머지는 무시한다.
6024
+ * Moves the top-left corner of the chart to the specified cell. The size is kept as is.
6025
+ * If a range of multiple cells is passed as startCell, only the top-left cell of that range is used and the rest is ignored.
5872
6026
  *
5873
- * @param startCell - 옮겨 놓을 셀. A1 표기 문자열로도 지정할 수 있다("A1:B2", 단일 셀은 "E10")
6027
+ * @param startCell - cell to move the chart to. An A1 notation string is also accepted ("A1:B2", or "E10" for a single cell)
5874
6028
  */
5875
6029
  setPosition(startCell: string | RangeCoords): Promise<void>;
5876
6030
  }
5877
6031
  /**
5878
- * 워크시트에 놓인 표 하나를 다루는 핸들이다.
5879
- * 표의 영역과 표시 옵션, 표에 딸린 자동 필터를 다룬다.
5880
- * 문서를 공동 편집하는 중에는 표를 바꿀 수 없다.
6032
+ * Represents a table on a worksheet.
6033
+ * Reads and edits the table range, the display options, and the AutoFilter of the table.
6034
+ * A table cannot be changed while the document is being co-edited.
5881
6035
  */
5882
6036
  interface Table {
5883
6037
  /**
5884
- * 지정된 표 이름을 반환한다.
6038
+ * Returns the table name.
5885
6039
  */
5886
6040
  getName(): Promise<string>;
5887
6041
  /**
5888
- * 머리글 행과 요약 행을 포함한 표 전체 영역의 Range 핸들을 반환한다.
5889
- * 반환한 Range 는 호출 시점의 좌표를 담고 있어, 이후 표 영역이 바뀌어도 따라가지 않는다.
6042
+ * Returns a Range for the entire table range, including the header row and totals row.
6043
+ * The returned Range holds the coordinates at the time of the call and does not follow later changes to the table range.
5890
6044
  */
5891
6045
  getRange(): Promise<Range>;
5892
6046
  /**
5893
- * 표의 표시 옵션을 한 번에 반환한다.
6047
+ * Returns the display options of the table in a single call.
5894
6048
  */
5895
6049
  getOptions(): Promise<TableOptions>;
5896
6050
  /**
5897
- * 표를 삭제한다. 표 정의와 표에 딸린 자동 필터를 없애고 표 영역의 셀 내용까지 지운다.
6051
+ * Deletes the table. Removes the table definition and the AutoFilter of the table, and clears the cell content of the table range.
5898
6052
  */
5899
6053
  delete(): Promise<void>;
5900
6054
  /**
5901
- * 표 영역을 새 범위로 변경한다.
5902
- * 새 영역은 머리글 행 위치를 그대로 두면서 현재 표 영역과 겹쳐야 하고 두 셀 이상이어야 하며, 전체 행이나 전체 열은 지정할 수 없다.
5903
- * 현재 영역과 같은 영역을 넘기면 아무것도 바꾸지 않는다.
6055
+ * Changes the table range to a new range.
6056
+ * The new range must keep the header row in place while overlapping the current table range, must contain at least two cells, and cannot be entire rows or entire columns.
6057
+ * Passing the same range as the current table range does nothing.
5904
6058
  *
5905
- * @param range - 새 표 영역. A1 표기 문자열로도 지정할 수 있다("A1:B2", 단일 셀은 "E10")
6059
+ * @param range - new table range. An A1 notation string is also accepted ("A1:B2", or "E10" for a single cell)
5906
6060
  */
5907
6061
  resize(range: string | RangeCoords): Promise<void>;
5908
6062
  /**
5909
- * 표의 표시 옵션을 변경한다. 지정한 옵션만 적용하고 나머지는 현재 값을 그대로 둔다.
5910
- * 머리글 행이나 요약 행을 켤 때 표 바로 바깥의 인접한 행이 비어 있지 않으면 시트에 행을 새로 삽입해 아래 내용을 밀어내고, 끌 때는 그 행의 셀 값을 지운다.
5911
- * 머리글 행을 켜면 표의 자동 필터가 함께 만들어지고, 끄면 제거된다.
5912
- * 표 스타일은 이 메서드로 바꿀 수 없다.
6063
+ * Changes the display options of the table. Only the specified options are applied, and the rest keep their current values.
6064
+ * When the header row or totals row is turned on, if the adjacent row just outside the table is not empty, a new row is inserted into the sheet and the content below is pushed down. When turned off, the cell values in that row are cleared.
6065
+ * Turning on the header row also creates the table's AutoFilter, and turning it off removes it.
6066
+ * The table style cannot be changed with this method.
5913
6067
  *
5914
- * @param options - 바꿀 옵션
6068
+ * @param options - options to change
5915
6069
  */
5916
6070
  setOptions(options: TableOptionUpdate): Promise<void>;
5917
6071
  /**
5918
- * 머리글 행 표시 여부를 변경한다.
5919
- * 켤 때 표 바로 바깥의 인접한 행이 비어 있지 않으면 시트에 행을 새로 삽입해 아래 내용을 밀어내고, 끌 때는 그 행의 셀 값을 지운다.
5920
- * 머리글 행을 켜면 표의 자동 필터가 함께 만들어지고, 끄면 제거된다.
6072
+ * Changes whether the header row is shown.
6073
+ * When turned on, if the adjacent row just outside the table is not empty, a new row is inserted into the sheet and the content below is pushed down. When turned off, the cell values in that row are cleared.
6074
+ * Turning on the header row also creates the table's AutoFilter, and turning it off removes it.
6075
+ *
6076
+ * @param isOn - true to turn on, false to turn off
5921
6077
  */
5922
6078
  setHeaderRow(isOn: boolean): Promise<void>;
5923
6079
  /**
5924
- * 요약 행 표시 여부를 변경한다.
5925
- * 켤 때 표 바로 바깥의 인접한 행이 비어 있지 않으면 시트에 행을 새로 삽입해 아래 내용을 밀어내고, 끌 때는 그 행의 셀 값을 지운다.
6080
+ * Changes whether the totals row is shown.
6081
+ * When turned on, if the adjacent row just outside the table is not empty, a new row is inserted into the sheet and the content below is pushed down. When turned off, the cell values in that row are cleared.
6082
+ *
6083
+ * @param isOn - true to turn on, false to turn off
5926
6084
  */
5927
6085
  setTotalsRow(isOn: boolean): Promise<void>;
5928
6086
  /**
5929
- * 첫 열 강조 여부를 변경한다.
6087
+ * Changes whether the first column is highlighted.
6088
+ *
6089
+ * @param isOn - true to turn on, false to turn off
5930
6090
  */
5931
6091
  setFirstColumn(isOn: boolean): Promise<void>;
5932
6092
  /**
5933
- * 마지막 열 강조 여부를 변경한다.
6093
+ * Changes whether the last column is highlighted.
6094
+ *
6095
+ * @param isOn - true to turn on, false to turn off
5934
6096
  */
5935
6097
  setLastColumn(isOn: boolean): Promise<void>;
5936
6098
  /**
5937
- * 행 줄무늬 표시 여부를 변경한다.
6099
+ * Changes whether alternate rows are shaded in different colors.
6100
+ *
6101
+ * @param isOn - true to turn on, false to turn off
5938
6102
  */
5939
6103
  setBandedRows(isOn: boolean): Promise<void>;
5940
6104
  /**
5941
- * 열 줄무늬 표시 여부를 변경한다.
6105
+ * Changes whether alternate columns are shaded in different colors.
6106
+ *
6107
+ * @param isOn - true to turn on, false to turn off
5942
6108
  */
5943
6109
  setBandedColumns(isOn: boolean): Promise<void>;
5944
6110
  /**
5945
- * 표 이름을 변경한다. 표 이름을 참조하는 수식은 새 이름으로 함께 갱신된다.
5946
- * 이 핸들은 새 이름을 가리키므로 계속 쓸 수 있지만, 같은 표를 가리키던 다른 핸들과 이 표에서 미리 받아 둔 Filter 핸들은 더 이상 쓸 수 없다.
5947
- * 다른 표가 같은 이름을 쓰고 있으면 변경할 수 없으며, 이때 대소문자는 구분하지 않는다.
6111
+ * Renames the table.
6112
+ * This Table points to the new name and can still be used, but other Table objects that pointed to the same table and any Filter obtained from this table beforehand can no longer be used.
6113
+ * The table cannot be renamed if a table or defined name with the same name already exists, and the comparison is case-insensitive.
5948
6114
  *
5949
- * @param name - 새 표 이름. 공백이나 허용되지 않는 문자를 쓸 수 없고, 셀 참조로 읽히는 이름이나 최대 길이를 넘는 이름도 받지 않는다
6115
+ * @param name - new table name. It cannot contain spaces or disallowed characters, and names that read as cell references and names longer than the maximum length are not accepted
5950
6116
  */
5951
6117
  setName(name: string): Promise<void>;
5952
6118
  /**
5953
- * 이 표의 자동 필터 핸들을 반환한다.
5954
- * 표의 필터링은 표 구조에 내재하므로 아직 필터가 만들어지지 않았어도 핸들을 반환하며, 필터가 있는지는 Filter 의 getInfo() 로 확인한다.
6119
+ * Returns the Filter for the AutoFilter of this table.
6120
+ * Because filtering is inherent to the table structure, a Filter is returned even if no filter has been created yet. Check whether a filter exists with getInfo() of the Filter.
6121
+ * A Filter obtained before the table is renamed can no longer be used.
5955
6122
  */
5956
6123
  getFilter(): Promise<Filter>;
5957
6124
  /**
5958
- * 표의 이름·위치·영역과 표시 옵션을 한 번에 반환한다.
6125
+ * Returns the name, location, range, and display options of the table in a single call.
5959
6126
  */
5960
6127
  getInfo(): Promise<TableInfo>;
5961
6128
  }
5962
6129
  /**
5963
- * 시트 또는 표의 자동 필터를 가리키는 핸들이다.
5964
- * 필터 영역과 열별 필터 조건, 필터 영역의 정렬 상태를 다룬다.
6130
+ * Represents an AutoFilter on a sheet or table.
6131
+ * Reads and edits the filter range, the filter criteria of each column, and the sort state.
5965
6132
  */
5966
6133
  interface Filter {
5967
6134
  /**
5968
- * 자동 필터를 만든다.
5969
- * 시트 필터는 range 로 지정한 영역에 만들며, range 를 생략하면 현재 선택 영역을 둘러싼 데이터 영역으로 넓혀 잡는다.
5970
- * 표 필터는 range 를 무시하고 요약 행을 뺀 표 영역에 만든다.
5971
- * 대상에 이미 필터가 있으면 만들 수 없고, range 를 생략했는데 선택 영역이 빈 셀 하나뿐이어도 만들 수 없다.
6135
+ * Creates an AutoFilter.
6136
+ * A sheet filter is created on the range specified by range. If range is omitted, the data region surrounding the current selection is used.
6137
+ * A table filter ignores range and is created on the table range excluding the totals row.
6138
+ * A filter cannot be created if the target already has one, or if range is omitted and the selection is a single empty cell.
5972
6139
  *
5973
- * @param range - 필터를 만들 영역. A1 표기 문자열로도 지정할 수 있다("A1:B2", 단일 셀은 "E10")
6140
+ * @param range - range to create the filter on. An A1 notation string is also accepted ("A1:B2", or "E10" for a single cell)
5974
6141
  */
5975
6142
  create(range?: string | RangeCoords): Promise<void>;
5976
6143
  /**
5977
- * 지정한 열에 필터 조건을 적용한다. criteria 가 null 이면 그 열의 조건을 해제한다.
5978
- * 머리글 셀이 병합된 열을 지정하면 병합 영역의 첫 열에 적용된다.
5979
- * 시트 필터는 미리 create() 로 만들어 두어야 하지만, 표는 필터가 없을 때 조건을 적용하면 필터가 함께 만들어진다.
6144
+ * Applies filter criteria to the specified column. If criteria is null, the criteria of that column are cleared.
6145
+ * If the header area is merged, specifying any column within the merged area applies the filter only to the first column of the merged area.
6146
+ * A sheet filter must be created beforehand with create(), but for a table, applying criteria when there is no filter also creates the filter.
5980
6147
  *
5981
- * @param colId - 대상 열. 필터 영역 첫 열부터 센 0-based 오프셋이며(0 = 첫 열), getInfo() 의 columns[].colId 와 같은 좌표계다
5982
- * @param criteria - 적용할 조건. filterType 에 따라 값 목록·사용자 지정·상위 하위·동적 필터 중 한 스키마를 쓰며, 종류와 연산자 어휘는 FilterType·FilterOperator·FilterDynamicType 상수로 지정한다. null 이면 조건을 해제한다
6148
+ * @param colId - target column. It is a 0-based offset from the first column of the filter range (0 is the first column). It uses the same coordinate system as columns[].colId of getInfo()
6149
+ * @param criteria - filter criteria to apply. It is one of the schemas FilterValuesCriteria, FilterCustomCriteria, FilterTop10Criteria, and FilterDynamicCriteria, depending on FilterType (see each typedef for the fields). If null, the criteria of that column are cleared
5983
6150
  */
5984
- applyFilter(colId: number, criteria: Record<string, unknown> | null): Promise<void>;
6151
+ applyFilter(colId: number, criteria: object | null): Promise<void>;
5985
6152
  /**
5986
- * 필터 조건을 해제한다. colId 를 지정하면 그 열만, 생략하면 조건이 걸린 모든 열을 해제한다.
5987
- * 필터 버튼은 그대로 남는다.
5988
- * 해제할 조건이 없거나 표에 아직 필터가 없으면 아무것도 바꾸지 않는다.
6153
+ * Clears the filter criteria. If colId is specified, only that column is cleared. If omitted, all columns with criteria are cleared.
6154
+ * The filter buttons remain.
6155
+ * Does nothing if there are no criteria to clear or the table does not have a filter yet.
5989
6156
  *
5990
- * @param colId - 해제할 열. 필터 영역 첫 열부터 센 0-based 오프셋이며(0 = 첫 열), 생략하면 모든 열을 해제한다
6157
+ * @param colId - column to clear. It is a 0-based offset from the first column of the filter range (0 is the first column). If omitted, all columns are cleared
5991
6158
  */
5992
6159
  clearFilter(colId?: number): Promise<void>;
5993
6160
  /**
5994
- * 필터 영역을 지정한 열 기준으로 정렬하고, 정렬 상태를 필터에 남긴다.
5995
- * 머리글 셀이 병합된 열을 지정하면 병합 영역의 첫 열을 기준으로 정렬한다.
5996
- * 표는 필터가 없으면 정렬하면서 함께 만들지만, 시트는 자동으로 만들지 않아 create() 로 먼저 만들어야 한다.
6161
+ * Sorts the filter range by the specified column and keeps the sort state in the filter.
6162
+ * If the header area is merged, specifying any column within the merged area sorts by the first column of the merged area.
6163
+ * For a table, sorting also creates a filter if there is none, but a sheet does not create one automatically, so create() must be called first.
5997
6164
  *
5998
- * @param colId - 정렬 기준 열. 필터 영역 첫 열부터 센 0-based 오프셋이며(0 = 첫 열), getInfo() 의 sort.colId 와 같은 좌표계다
5999
- * @param order - 정렬 방향. SortOrder 의 오름차순·내림차순 두 값만 받는다
6000
- * @returns 이어서 호출할 수 있도록 이 핸들을 그대로 반환한다
6165
+ * @param colId - column to sort by. It is a 0-based offset from the first column of the filter range (0 is the first column). It uses the same coordinate system as sort.colId of getInfo()
6166
+ * @param order - sort order
6167
+ * @returns this Filter, so that calls can be chained
6001
6168
  */
6002
6169
  sort(colId: number, order: SortOrder): Promise<Filter>;
6003
6170
  /**
6004
- * 자동 필터를 없앤다. 필터 영역과 열 조건이 함께 사라진다.
6171
+ * Removes the AutoFilter. The filter range and the column criteria are removed together.
6005
6172
  */
6006
6173
  remove(): Promise<void>;
6007
6174
  /**
6008
- * 필터 영역과 열별 조건, 필터로 숨겨진 행 수, 정렬 상태를 반환한다.
6009
- * 필터가 아직 없으면 enabled 만 false 로 담고 나머지 필드는 넣지 않는다.
6175
+ * Returns the filter range, the criteria of each column, the number of rows hidden by the filter, and the sort state.
6176
+ * If no filter exists yet, only enabled is included, as false, and the other fields are omitted.
6010
6177
  */
6011
6178
  getInfo(): Promise<FilterInfo>;
6012
6179
  }
6013
6180
  /**
6014
- * 통합 문서에 정의된 이름 하나를 다루는 핸들이다.
6015
- * 이름이 가리키는 수식과 그 이름의 사용 범위를 다룬다.
6181
+ * Represents a defined name in the workbook.
6182
+ * Reads and edits the formula assigned to the name and the scope of the name.
6016
6183
  */
6017
6184
  interface Name {
6018
6185
  /**
6019
- * 지정된 이름을 반환한다.
6186
+ * Returns the name.
6020
6187
  */
6021
6188
  getName(): Promise<string>;
6022
6189
  /**
6023
- * 이 이름의 사용 범위인 시트 이름을 반환한다.
6190
+ * Returns the name of the sheet that this name is scoped to.
6024
6191
  *
6025
- * @returns 특정 시트에서만 쓰는 이름이면 그 시트 이름, 문서 전체에서 쓰는 이름이면 null
6192
+ * @returns sheet name if the name is sheet-scoped, null if the name is workbook-scoped
6026
6193
  */
6027
6194
  getSheetName(): Promise<string | null>;
6028
6195
  /**
6029
- * 이 이름이 가리키는 수식을 `=` 로 시작하는 형태로 반환한다.
6030
- * 수식의 상대 참조는 활성 시트의 활성 셀을 기준으로 풀어 쓰므로, 같은 이름이라도 활성 셀이 달라지면 반환값이 달라질 수 있다.
6196
+ * Returns the formula that this name points to.
6197
+ * Relative references in the formula are resolved against the active cell of the active sheet, so the return value can change with the active cell even for the same name.
6198
+ *
6199
+ * @returns formula starting with `=`
6031
6200
  */
6032
6201
  getFormula(): Promise<string>;
6033
6202
  /**
6034
- * 이 이름이 실제로 가리키는 영역을 반환한다. 영역이 여럿이면 콤마로 이어 붙이고, 각 영역에는 시트 이름을 항상 붙인다.
6035
- * 행이나 열이 삽입·삭제되어 참조가 밀려도 지금 가리키는 위치를 돌려준다.
6203
+ * Returns the ranges that this name actually refers to. Multiple ranges are joined with commas, and each range always includes the sheet name.
6036
6204
  *
6037
- * @returns 상수나 오류를 가리키는 이름, 지원하지 않는 함수를 쓴 이름이면 빈 문자열
6205
+ * @returns empty string if the name refers to a constant or an error, or uses an unsupported function
6038
6206
  */
6039
6207
  getRanges(): Promise<string>;
6040
6208
  /**
6041
- * 정의된 이름의 이름을 바꾼다. 이 핸들도 새 이름을 가리키므로 바꾼 뒤에도 계속 쓸 수 있다.
6042
- * 같은 범위에 같은 이름이 이미 있거나 같은 이름의 표가 있으면 바꿀 수 없다. 이때 대소문자는 구분하지 않지만, 대소문자만 바꾸는 변경은 중복으로 보지 않는다.
6209
+ * Renames the defined name.
6210
+ * A name cannot be changed to a name that already exists in the same scope or to a table name.
6043
6211
  *
6044
- * @param newName - 새 이름. 공백이나 허용되지 않는 문자를 쓸 수 없고, 예약된 이름이나 셀 참조로 읽히는 이름, 최대 길이를 넘는 이름도 받지 않는다
6212
+ * @param newName - new name. It cannot contain spaces or disallowed characters, and reserved names, names that read as cell references, and names longer than the maximum length are not accepted
6045
6213
  */
6046
6214
  setName(newName: string): Promise<void>;
6047
6215
  /**
6048
- * 정의된 이름이 가리킬 수식을 바꾼다.
6049
- * 수식에 시트를 적지 않은 참조는 이름의 사용 범위와 무관하게 활성 시트 기준으로 해석한다.
6216
+ * Changes the formula that the defined name points to.
6217
+ * References in the formula that do not specify a sheet are resolved against the active sheet, regardless of the scope of the name.
6050
6218
  *
6051
- * @param formula - 새 수식 또는 참조. `=` 로 시작해도 되고 아니어도 된다
6219
+ * @param formula - new formula or reference
6052
6220
  */
6053
6221
  setFormula(formula: string): Promise<void>;
6054
6222
  /**
6055
- * 정의된 이름의 이름과 수식을 한 번에 바꾼다.
6056
- * 바꿀 항목을 하나도 주지 않으면 오류가 난다.
6223
+ * Changes the name and the formula of the defined name in a single call.
6224
+ * Throws an error if no item to change is given.
6057
6225
  *
6058
- * @param fields - 바꿀 항목
6226
+ * @param fields - items to change
6059
6227
  */
6060
6228
  update(fields: NameUpdate): Promise<void>;
6061
6229
  /**
6062
- * 정의된 이름을 삭제한다. 삭제한 뒤에는 이 핸들로 수식을 조회하거나 내용을 바꿀 수 없다.
6230
+ * Deletes the defined name.
6063
6231
  */
6064
6232
  delete(): Promise<void>;
6065
6233
  /**
6066
- * 이름과 사용 범위 시트, 수식을 한 번에 반환한다.
6067
- * name 은 getName(), formula 는 getFormula() 와 같은 규칙을 따른다.
6234
+ * Returns the name, the scope sheet, the formula, and the referenced ranges in a single call.
6235
+ * Each value matches getName(), getSheetName(), getFormula(), and getRanges().
6236
+ *
6237
+ * @returns Formulas start with `=`
6068
6238
  */
6069
6239
  getInfo(): Promise<NameInfo>;
6070
6240
  }
6071
6241
  }
6072
6242
 
6073
- /**
6074
- * Thinkfree Office SDK Type Definitions
6075
- *
6076
- * ⚠️ AUTO-GENERATED — DO NOT EDIT.
6077
- * 오피스 구현 저장소(비공개)의 API JSDoc 에서 생성된다 — 수정은 원본 JSDoc 에서.
6078
- *
6079
- * proxy 메서드는 postMessage bridge 를 거치므로 Promise 를 반환한다.
6080
- * Generated: 2026-09-22
6081
- */
6082
-
6083
6243
  declare namespace Show {
6084
6244
  /** 도형 종류 (모델 shape type 값). 도형 조회·판별에서 도형의 유형을 구분하는 값으로 사용한다. */
6085
6245
  export const ShapeType: {
@@ -7524,13 +7684,32 @@ declare namespace Show {
7524
7684
  /** 단락 뒤 간격 (pt) */
7525
7685
  spaceAfter?: number;
7526
7686
  }
7687
+ export interface ChartFormatInfo {
7688
+ /** 차트 종류. 값은 getType 과 같다 */
7689
+ type: ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown";
7690
+ /** 차트 제목. 설정하지 않았으면 빈 문자열이다 */
7691
+ title: string;
7692
+ /** 범례 위치 */
7693
+ legendPosition: ChartLegendPosition;
7694
+ /** 데이터레이블 위치. null 은 그 차트 종류에 데이터레이블이 아예 없다는 뜻이다(표면형) */
7695
+ dataLabelPosition: ChartDataLabelPosition | null;
7696
+ /** 축별 축 제목. null 은 그 차트 종류에 해당 축의 제목이 아예 없다는 뜻이다 */
7697
+ axisTitle: {
7698
+ horizontal: string | null;
7699
+ vertical: string | null;
7700
+ };
7701
+ /** 축별 눈금선. null 은 그 차트 종류에 해당 축의 눈금선이 아예 없다는 뜻이고, "none" 은 쓸 수는 있지만 꺼져 있다는 뜻이다 */
7702
+ gridLine: {
7703
+ horizontal: ChartGridLineType | null;
7704
+ vertical: ChartGridLineType | null;
7705
+ };
7706
+ }
7527
7707
  const __proxyBrand: unique symbol;
7528
7708
  /**
7529
7709
  * 문서 전체를 다루는 진입점으로, 슬라이드 조회·검색(getSlide/findShapes/findText 등),
7530
7710
  * 슬라이드 삽입·삭제·복제·이동(insertSlide/deleteSlide/duplicateSlide 등),
7531
7711
  * 날짜·슬라이드 번호·바닥글 일괄 설정(setDate/setSlideNumber/setFooter 등),
7532
- * 테마 적용(setColorScheme/setFontScheme/setFormatScheme 등),
7533
- * 저장·다운로드·인쇄(save/download/print 등), 슬라이드 쇼 시작(startSlideShow)을 제공한다.
7712
+ * 테마 적용(setColorScheme/setFontScheme/setFormatScheme 등), 슬라이드 쇼 시작(startSlideShow)을 제공한다.
7534
7713
  */
7535
7714
  export interface Document {
7536
7715
  /**
@@ -7637,11 +7816,14 @@ declare namespace Show {
7637
7816
  * 텍스트를 검색한다. slideProxyList 를 주면 그 슬라이드들만 검색한다.
7638
7817
  * 매치는 문서 순서(슬라이드 → 도형 → 표 셀)로 반환된다.
7639
7818
  * 병합으로 숨겨진 표 셀, 슬라이드 번호·날짜 같은 자동 갱신 필드, 문단 경계를 가로지르는 매치는 검색되지 않는다.
7819
+ * 발표자 노트의 매치는 반환하지 않는다 (노트 텍스트는 Slide.getSlideNoteText 로 조회).
7640
7820
  *
7641
- * @param query - 찾을 텍스트
7642
- * @param slideProxyList - 검색 대상 슬라이드 (기본값: 전체 슬라이드)
7821
+ * @param query - 찾을 텍스트 (개행 불가)
7822
+ * @param slideProxyList - 검색 대상 슬라이드. 빈 배열이면 아무것도 검색하지 않는다 (기본값: 전체 슬라이드)
7643
7823
  * @param caseSensitive - 대소문자 구분 (기본값: false)
7644
7824
  * @returns 매치 목록. target 은 표 셀 매치면 TableCell, 아니면 도형 프록시(Shape)이며, range 를 그대로 서식 API 에 넘겨 매치 구간만 편집할 수 있다 (예: `m.target.setBold(true, m.range)`). range 의 from/to 는 글자 offset(to 포함), text 는 검색 시점의 매치 텍스트다.
7825
+ * @throws {Error} query 가 비었거나 최대 길이를 넘거나 개행을 포함한 경우 (error.code = "INVALID_ARGUMENT")
7826
+ * @throws {Error} query 가 빈 문자열이거나 최대 길이를 넘는 경우 (error.code = "INVALID_ARGUMENT")
7645
7827
  */
7646
7828
  findText(query: string, slideProxyList?: Slide[], caseSensitive?: boolean): Promise<{
7647
7829
  target: (TableCell | Shape);
@@ -7663,7 +7845,7 @@ declare namespace Show {
7663
7845
  getColorSchemeList(): Promise<{
7664
7846
  prst: string;
7665
7847
  name: string;
7666
- colors: Record<string, unknown>;
7848
+ colors: Record<string, string>;
7667
7849
  }[]>;
7668
7850
  /**
7669
7851
  * 문서의 색상 테마를 반환한다. (setColorScheme 대칭)
@@ -7675,7 +7857,7 @@ declare namespace Show {
7675
7857
  getColorScheme(): Promise<{
7676
7858
  prst: string | null;
7677
7859
  name: string;
7678
- colors: Record<string, unknown>;
7860
+ colors: Record<string, string>;
7679
7861
  } | null>;
7680
7862
  /**
7681
7863
  * 문서의 테마 글꼴을 반환한다. (setFontScheme 대칭)
@@ -7721,7 +7903,7 @@ declare namespace Show {
7721
7903
  }[]>;
7722
7904
  /**
7723
7905
  * 차트 프리셋 스타일(1~12)별 계열 색 팔레트를 현재 슬라이드에 적용된 테마 기준으로 반환한다.
7724
- * set_chart_style 의 style 을 고를 때 참고용.
7906
+ * Chart.setStyle 의 style 을 고를 때 참고용.
7725
7907
  * style 은 색 그룹(4) × 배경/선 변형(3) 조합. 색은 그룹으로만 결정되므로 같은 그룹(예: 1~3)은 colors 가 동일하고,
7726
7908
  * 그룹 내 차이(뒤 1/2/3)는 배경/선 변형(variant)이다. 색은 테마 accent 에 종속 — 테마가 바뀌면 값도 바뀐다.
7727
7909
  *
@@ -7734,14 +7916,18 @@ declare namespace Show {
7734
7916
  }[]>;
7735
7917
  /**
7736
7918
  * 검색 텍스트를 찾아 모두 새 텍스트로 바꾼다. (모두 바꾸기) slideProxyList 를 주면 그 슬라이드들만 바꾼다.
7919
+ * findText 와 달리 발표자 노트의 텍스트도 바꾸고 replacedCount 에 센다.
7737
7920
  * 병합으로 숨겨진 표 셀, 슬라이드 번호·날짜 같은 자동 갱신 필드, 문단 경계를 가로지르는 매치는 바뀌지 않는다.
7738
7921
  * 협업 잠금 등으로 편집할 수 없는 텍스트의 매치도 바꾸지 않고 skippedCount 로 반환한다.
7739
7922
  *
7740
- * @param query - 찾을 텍스트
7923
+ * @param query - 찾을 텍스트 (개행 불가)
7741
7924
  * @param replacement - 바꿀 텍스트. 빈 문자열이면 매치를 삭제한다 (기본값: "")
7742
- * @param slideProxyList - 치환 대상 슬라이드 (기본값: 전체 슬라이드)
7925
+ * @param slideProxyList - 치환 대상 슬라이드. 빈 배열이면 아무것도 바꾸지 않는다 (기본값: 전체 슬라이드)
7743
7926
  * @param caseSensitive - 대소문자 구분 (기본값: false)
7744
7927
  * @returns 치환한 매치 수 / 제외한 매치 수
7928
+ * @throws {Error} query 가 비었거나 개행을 포함한 경우, query·replacement 가 최대 길이를 넘는 경우
7929
+ * (error.code = "INVALID_ARGUMENT")
7930
+ * @throws {Error} query 가 빈 문자열이거나 query, replacement 가 최대 길이를 넘는 경우 (error.code = "INVALID_ARGUMENT")
7745
7931
  */
7746
7932
  replaceText(query: string, replacement?: string, slideProxyList?: Slide[], caseSensitive?: boolean): Promise<{
7747
7933
  replacedCount: number;
@@ -7753,6 +7939,7 @@ declare namespace Show {
7753
7939
  * @param index - 삽입 위치 (0-based) (기본값: 마지막에 추가)
7754
7940
  * @param layoutType - 레이아웃 종류. 같은 type 이 여럿이면 첫 번째. 지정한 type 미존재 시 BLANK (문서에 BLANK 가 없으면 첫 번째 마스터의 첫 번째 레이아웃) (기본값: SlideLayoutType.BLANK)
7755
7941
  * @returns 삽입된 슬라이드
7942
+ * @throws {Error} 삽입하면 슬라이드가 299장을 넘는 경우 (error.code = "SLIDE_COUNT_LIMIT")
7756
7943
  */
7757
7944
  insertSlide(index?: number, layoutType?: SlideLayoutType): Promise<Slide>;
7758
7945
  /**
@@ -7772,12 +7959,14 @@ declare namespace Show {
7772
7959
  * 슬라이드 하나를 삭제한다.
7773
7960
  *
7774
7961
  * @param slideProxy - 삭제할 슬라이드
7962
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7775
7963
  */
7776
7964
  deleteSlide(slideProxy: Slide): Promise<void>;
7777
7965
  /**
7778
7966
  * 여러 슬라이드를 일괄 삭제한다.
7779
7967
  *
7780
7968
  * @param slideProxyList - 삭제할 슬라이드 배열
7969
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7781
7970
  */
7782
7971
  deleteSlides(slideProxyList: Slide[]): Promise<void>;
7783
7972
  /**
@@ -7785,6 +7974,8 @@ declare namespace Show {
7785
7974
  *
7786
7975
  * @param slideProxy - 복제할 슬라이드
7787
7976
  * @returns 복제된 슬라이드 Proxy
7977
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7978
+ * @throws {Error} 복제하면 슬라이드가 299장을 넘는 경우 (error.code = "SLIDE_COUNT_LIMIT")
7788
7979
  */
7789
7980
  duplicateSlide(slideProxy: Slide): Promise<Slide | null>;
7790
7981
  /**
@@ -7792,6 +7983,8 @@ declare namespace Show {
7792
7983
  *
7793
7984
  * @param slideProxyList - 복제할 슬라이드 배열
7794
7985
  * @returns 복제된 슬라이드 Proxy 배열
7986
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7987
+ * @throws {Error} 복제하면 슬라이드가 299장을 넘는 경우. 한 장도 복제하지 않는다 (error.code = "SLIDE_COUNT_LIMIT")
7795
7988
  */
7796
7989
  duplicateSlides(slideProxyList: Slide[]): Promise<Slide[]>;
7797
7990
  /**
@@ -7805,6 +7998,7 @@ declare namespace Show {
7805
7998
  * 지정한 슬라이드로 현재 보기를 전환한다.
7806
7999
  *
7807
8000
  * @param slideProxy - 이동할 슬라이드
8001
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7808
8002
  */
7809
8003
  goToSlide(slideProxy: Slide): Promise<void>;
7810
8004
  /**
@@ -7840,12 +8034,14 @@ declare namespace Show {
7840
8034
  *
7841
8035
  * @param slideProxyList - 대상 슬라이드 배열
7842
8036
  * @param isHidden - true: 숨김, false: 표시
8037
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7843
8038
  */
7844
8039
  hideSlides(slideProxyList: Slide[], isHidden: boolean): Promise<void>;
7845
8040
  /**
7846
8041
  * 여러 슬라이드의 배경을 일괄 초기화한다.
7847
8042
  *
7848
8043
  * @param slideProxyList - 대상 슬라이드 배열
8044
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7849
8045
  */
7850
8046
  resetBackgrounds(slideProxyList: Slide[]): Promise<void>;
7851
8047
  /**
@@ -7855,12 +8051,14 @@ declare namespace Show {
7855
8051
  *
7856
8052
  * @param slideProxyList - 대상 슬라이드 배열 (전체 적용은 getSlides() 를 넘긴다)
7857
8053
  * @param transition - 전환 효과 설정
8054
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7858
8055
  */
7859
8056
  setTransition(slideProxyList: Slide[], transition: Transition): Promise<void>;
7860
8057
  /**
7861
8058
  * 여러 슬라이드의 전환 효과를 제거한다. (단일 undo 로 처리)
7862
8059
  *
7863
8060
  * @param slideProxyList - 대상 슬라이드 배열
8061
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7864
8062
  */
7865
8063
  removeTransition(slideProxyList: Slide[]): Promise<void>;
7866
8064
  /**
@@ -7868,8 +8066,8 @@ declare namespace Show {
7868
8066
  * getColorSchemeList 로 목록을 확인한 뒤 prst 를 전달한다.
7869
8067
  *
7870
8068
  * @param colorSchemePrst - 색상 테마 프리셋 이름
7871
- * @throws {Error} 목록에 없는 prst 인 경우 (error.code = "SCHEME_NOT_FOUND"),
7872
- * 문서에 슬라이드가 없는 경우 (error.code = "EXECUTION_ERROR")
8069
+ * @throws {Error} 목록에 없는 prst 인 경우 (error.code = "SCHEME_NOT_FOUND")
8070
+ * @throws {Error} 문서에 슬라이드가 없는 경우 (error.code = "EXECUTION_ERROR")
7873
8071
  */
7874
8072
  setColorScheme(colorSchemePrst: string): Promise<void>;
7875
8073
  /**
@@ -7880,6 +8078,7 @@ declare namespace Show {
7880
8078
  * @param slideProxyList - 대상 슬라이드 배열
7881
8079
  * @param colorSchemePrst - 색상 테마 프리셋 이름
7882
8080
  * @throws {Error} 목록에 없는 prst 인 경우 (error.code = "SCHEME_NOT_FOUND")
8081
+ * @throws {Error} 지목한 슬라이드가 문서에 없는 경우 (error.code = "SLIDE_NOT_FOUND")
7883
8082
  */
7884
8083
  setSlideColorScheme(slideProxyList: Slide[], colorSchemePrst: string): Promise<void>;
7885
8084
  /**
@@ -7887,6 +8086,7 @@ declare namespace Show {
7887
8086
  *
7888
8087
  * @param colorScheme - 새 색상 테마 정보
7889
8088
  * @throws {Error} 이름이 이미 있거나 문서에 슬라이드가 없는 경우 (error.code = "EXECUTION_ERROR")
8089
+ * @throws {Error} 이름이 비었거나 색이 #RRGGBB 형식이 아닌 경우 (error.code = "INVALID_ARGUMENT")
7890
8090
  */
7891
8091
  createColorScheme(colorScheme: ColorScheme): Promise<void>;
7892
8092
  /**
@@ -7894,8 +8094,8 @@ declare namespace Show {
7894
8094
  * getFontSchemeList 로 목록을 확인한 뒤 prst 를 전달한다.
7895
8095
  *
7896
8096
  * @param fontSchemePrst - 테마 글꼴 프리셋 이름
7897
- * @throws {Error} 목록에 없는 prst 인 경우 (error.code = "SCHEME_NOT_FOUND"),
7898
- * 문서에 슬라이드가 없는 경우 (error.code = "EXECUTION_ERROR")
8097
+ * @throws {Error} 목록에 없는 prst 인 경우 (error.code = "SCHEME_NOT_FOUND")
8098
+ * @throws {Error} 문서에 슬라이드가 없는 경우 (error.code = "EXECUTION_ERROR")
7899
8099
  */
7900
8100
  setFontScheme(fontSchemePrst: string): Promise<void>;
7901
8101
  /**
@@ -7903,37 +8103,10 @@ declare namespace Show {
7903
8103
  * getFormatSchemeList 로 목록을 확인한 뒤 prst 를 전달한다.
7904
8104
  *
7905
8105
  * @param formatSchemePrst - 테마 효과 프리셋 이름
7906
- * @throws {Error} 목록에 없는 prst 인 경우 (error.code = "SCHEME_NOT_FOUND"),
7907
- * 문서에 슬라이드가 없는 경우 (error.code = "EXECUTION_ERROR")
8106
+ * @throws {Error} 목록에 없는 prst 인 경우 (error.code = "SCHEME_NOT_FOUND")
8107
+ * @throws {Error} 문서에 슬라이드가 없는 경우 (error.code = "EXECUTION_ERROR")
7908
8108
  */
7909
8109
  setFormatScheme(formatSchemePrst: string): Promise<void>;
7910
- /**
7911
- * 문서를 저장한다.
7912
- * (서버 I/O 이므로 Actor 경유)
7913
- */
7914
- save(): Promise<void>;
7915
- /**
7916
- * 문서를 닫는다.
7917
- * (앱 레벨 동작이므로 Actor 경유)
7918
- */
7919
- close(): Promise<void>;
7920
- /**
7921
- * 문서를 다운로드한다.
7922
- * (서버 I/O 이므로 Actor 경유)
7923
- */
7924
- download(): Promise<void>;
7925
- /**
7926
- * 문서를 PDF 로 변환해 다운로드한다. 원본 형식(pptx 등)으로 받으려면 download() 를 사용한다.
7927
- * 요청만 보내고 변환 완료를 기다리지 않는다 — 변환 진행·실패는 앱 상태 UI 가 표시한다.
7928
- * OfficeFilter 사용 시 해당 API 미지원 (미구현)
7929
- * (서버 변환·I/O 이므로 Actor 경유)
7930
- */
7931
- downloadAsPdf(): Promise<void>;
7932
- /**
7933
- * 현재 문서를 인쇄한다.
7934
- * (브라우저 인쇄/PDF 등 앱 레벨 동작이므로 Actor 경유)
7935
- */
7936
- print(): Promise<void>;
7937
8110
  /**
7938
8111
  * 문서 전체의 댓글 표시 여부를 설정한다.
7939
8112
  *
@@ -8032,10 +8205,13 @@ declare namespace Show {
8032
8205
  /**
8033
8206
  * 이 슬라이드에서 텍스트를 검색한다. 매치는 도형 → 표 셀 순서로 반환된다.
8034
8207
  * 병합으로 숨겨진 표 셀, 슬라이드 번호·날짜 같은 자동 갱신 필드, 문단 경계를 가로지르는 매치는 검색되지 않는다.
8208
+ * 발표자 노트의 매치는 반환하지 않는다 (노트 텍스트는 getSlideNoteText 로 조회).
8035
8209
  *
8036
- * @param query - 찾을 텍스트
8210
+ * @param query - 찾을 텍스트 (개행 불가)
8037
8211
  * @param caseSensitive - 대소문자 구분 (기본값: false)
8038
8212
  * @returns 매치 목록. target 은 표 셀 매치면 TableCell, 아니면 도형 프록시(Shape)이며, range(글자 offset, to 포함)를 그대로 서식 API 에 넘겨 매치 구간만 편집할 수 있다 (예: `m.target.setBold(true, m.range)`). text 는 검색 시점의 매치 텍스트다.
8213
+ * @throws {Error} query 가 비었거나 최대 길이를 넘거나 개행을 포함한 경우 (error.code = "INVALID_ARGUMENT")
8214
+ * @throws {Error} query 가 빈 문자열이거나 최대 길이를 넘는 경우 (error.code = "INVALID_ARGUMENT")
8039
8215
  */
8040
8216
  findText(query: string, caseSensitive?: boolean): Promise<{
8041
8217
  target: (TableCell | Shape);
@@ -8112,17 +8288,21 @@ declare namespace Show {
8112
8288
  getColorScheme(): Promise<{
8113
8289
  prst: string | null;
8114
8290
  name: string;
8115
- colors: Record<string, unknown>;
8291
+ colors: Record<string, string>;
8116
8292
  } | null>;
8117
8293
  /**
8118
8294
  * 이 슬라이드에서 검색 텍스트를 찾아 모두 새 텍스트로 바꾼다. (모두 바꾸기)
8295
+ * findText 와 달리 이 슬라이드의 발표자 노트 텍스트도 바꾸고 replacedCount 에 센다.
8119
8296
  * 병합으로 숨겨진 표 셀, 슬라이드 번호·날짜 같은 자동 갱신 필드, 문단 경계를 가로지르는 매치는 바뀌지 않는다.
8120
8297
  * 협업 잠금 등으로 편집할 수 없는 텍스트의 매치도 바꾸지 않고 skippedCount 로 반환한다.
8121
8298
  *
8122
- * @param query - 찾을 텍스트
8299
+ * @param query - 찾을 텍스트 (개행 불가)
8123
8300
  * @param replacement - 바꿀 텍스트. 빈 문자열이면 매치를 삭제한다 (기본값: "")
8124
8301
  * @param caseSensitive - 대소문자 구분 (기본값: false)
8125
8302
  * @returns 치환한 매치 수 / 제외한 매치 수
8303
+ * @throws {Error} query 가 비었거나 개행을 포함한 경우, query·replacement 가 최대 길이를 넘는 경우
8304
+ * (error.code = "INVALID_ARGUMENT")
8305
+ * @throws {Error} query 가 빈 문자열이거나 query, replacement 가 최대 길이를 넘는 경우 (error.code = "INVALID_ARGUMENT")
8126
8306
  */
8127
8307
  replaceText(query: string, replacement?: string, caseSensitive?: boolean): Promise<{
8128
8308
  replacedCount: number;
@@ -8171,6 +8351,7 @@ declare namespace Show {
8171
8351
  * @param colNum - 열 수
8172
8352
  * @param styleName - 표 스타일 이름 (doc.getTableStyleNames() 결과). 목록에 없는 이름이면 throw (기본값: 문서 기본 스타일)
8173
8353
  * @returns 삽입된 표
8354
+ * @throws {Error} 목록에 없는 스타일 이름인 경우 (error.code = "SCHEME_NOT_FOUND")
8174
8355
  */
8175
8356
  insertTable(rowNum: number, colNum: number, styleName?: string): Promise<Table>;
8176
8357
  /**
@@ -8178,6 +8359,8 @@ declare namespace Show {
8178
8359
  *
8179
8360
  * @param url - 이미지 URL
8180
8361
  * @returns 삽입된 이미지 도형 Proxy
8362
+ * @throws {Error} 이미지 업로드에 실패한 경우 (error.code = "EXECUTION_ERROR")
8363
+ * @throws {Error} 업로드 후 대상 슬라이드·도형이 사라진 경우 (error.code = "SHAPE_NOT_FOUND")
8181
8364
  */
8182
8365
  insertImage(url: string): Promise<Image>;
8183
8366
  /**
@@ -8186,12 +8369,15 @@ declare namespace Show {
8186
8369
  * @param url - 웹 동영상 URL (YouTube watch/embed/shorts/youtu.be, 3DS media)
8187
8370
  * @returns 삽입된 웹 동영상 도형 Proxy
8188
8371
  * @throws {Error} 지원하지 않는 URL 이거나 미디어 해석에 실패한 경우 (error.code = "INVALID_ARGUMENT")
8372
+ * @throws {Error} 썸네일 업로드에 실패한 경우 (error.code = "EXECUTION_ERROR")
8373
+ * @throws {Error} 업로드 후 대상 슬라이드·도형이 사라진 경우 (error.code = "SHAPE_NOT_FOUND")
8189
8374
  */
8190
8375
  insertWebVideo(url: string): Promise<Image>;
8191
8376
  /**
8192
8377
  * 슬라이드의 도형들을 하나의 이미지로 저장한다. (기존 UI 동작과 동일)
8193
8378
  *
8194
8379
  * @param shapeProxyList - 이미지로 저장할 도형 Proxy 배열
8380
+ * @throws {Error} 지목한 도형이 슬라이드에 없는 경우 (error.code = "SHAPE_NOT_FOUND")
8195
8381
  */
8196
8382
  saveAsPicture(shapeProxyList: (Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control)[]): Promise<void>;
8197
8383
  /**
@@ -8201,6 +8387,7 @@ declare namespace Show {
8201
8387
  *
8202
8388
  * @param shapeProxyList - 그룹화할 도형 Proxy 배열 (서로 다른 도형 2개 미만이면 throw)
8203
8389
  * @returns 생성된 그룹 도형 (실패 시 null)
8390
+ * @throws {Error} 지목한 도형이 슬라이드에 없는 경우 (error.code = "SHAPE_NOT_FOUND")
8204
8391
  * @throws {Error} 그룹 안의 자식 도형이나 그룹 잠금(noGrp) 도형이 포함된 경우 (error.code = "EXECUTION_ERROR")
8205
8392
  */
8206
8393
  groupShapes(shapeProxyList: (Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control)[]): Promise<Group | null>;
@@ -8211,6 +8398,7 @@ declare namespace Show {
8211
8398
  *
8212
8399
  * @param shapeProxy - 그룹 해제할 그룹 도형 Proxy
8213
8400
  * @returns 분리된 자식 도형 배열
8401
+ * @throws {Error} 지목한 도형이 슬라이드에 없는 경우 (error.code = "SHAPE_NOT_FOUND")
8214
8402
  * @throws {Error} 그룹 해제할 수 없는 도형인 경우 (error.code = "EXECUTION_ERROR")
8215
8403
  */
8216
8404
  ungroupShapes(shapeProxy: Group): Promise<(Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control)[]>;
@@ -8218,12 +8406,14 @@ declare namespace Show {
8218
8406
  * 도형 하나를 삭제한다.
8219
8407
  *
8220
8408
  * @param shapeProxy - 삭제할 도형 Proxy
8409
+ * @throws {Error} 지목한 도형이 슬라이드에 없는 경우 (error.code = "SHAPE_NOT_FOUND")
8221
8410
  */
8222
8411
  deleteShape(shapeProxy: Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control): Promise<void>;
8223
8412
  /**
8224
8413
  * 여러 도형을 일괄 삭제한다.
8225
8414
  *
8226
8415
  * @param shapeProxyList - 삭제할 도형 Proxy 배열
8416
+ * @throws {Error} 지목한 도형이 슬라이드에 없는 경우 (error.code = "SHAPE_NOT_FOUND")
8227
8417
  */
8228
8418
  deleteShapes(shapeProxyList: (Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control)[]): Promise<void>;
8229
8419
  /**
@@ -8231,6 +8421,7 @@ declare namespace Show {
8231
8421
  *
8232
8422
  * @param shapeProxy - 복제할 도형 Proxy
8233
8423
  * @returns 새로 생성된 도형 Proxy
8424
+ * @throws {Error} 지목한 도형이 슬라이드에 없는 경우 (error.code = "SHAPE_NOT_FOUND")
8234
8425
  */
8235
8426
  duplicateShape(shapeProxy: Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control): Promise<Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control | null>;
8236
8427
  /**
@@ -8238,6 +8429,7 @@ declare namespace Show {
8238
8429
  *
8239
8430
  * @param shapeProxyList - 복제할 도형 Proxy 배열
8240
8431
  * @returns 새로 생성된 도형 Proxy 배열
8432
+ * @throws {Error} 지목한 도형이 슬라이드에 없는 경우 (error.code = "SHAPE_NOT_FOUND")
8241
8433
  */
8242
8434
  duplicateShapes(shapeProxyList: (Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control)[]): Promise<(Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control)[]>;
8243
8435
  /**
@@ -8246,6 +8438,7 @@ declare namespace Show {
8246
8438
  *
8247
8439
  * @param shapeProxyList - 분배할 도형 Proxy 배열
8248
8440
  * @param direction - 분배 방향
8441
+ * @throws {Error} 지목한 도형이 슬라이드에 없는 경우 (error.code = "SHAPE_NOT_FOUND")
8249
8442
  */
8250
8443
  distributeShapes(shapeProxyList: (Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control)[], direction: DistributeDirection): Promise<void>;
8251
8444
  /**
@@ -8289,8 +8482,7 @@ declare namespace Show {
8289
8482
  * @param type - 그라데이션 유형 (lin/circle/rect/shape) (기본값: GradientType.LINEAR)
8290
8483
  * @param stops - 색상 변화점. pos 생략 시 균등 분배, alpha 는 투명도(0~100) (기본값: [{ color: "accent1", pos: 0 }, { color: "bg1", pos: 100 }])
8291
8484
  * @param angle - 그라데이션 각도 (lin 일 때만 사용) (기본값: 45)
8292
- * @example
8293
- * slide.setGradientFill("lin", [{ color: "#FF0000" }, { color: "#0000FF" }], 90);
8485
+ * @example slide.setGradientFill("lin", [{ color: "#FF0000" }, { color: "#0000FF" }], 90);
8294
8486
  */
8295
8487
  setGradientFill(type?: GradientType, stops?: {
8296
8488
  color: string;
@@ -8304,7 +8496,8 @@ declare namespace Show {
8304
8496
  * @param fillMode - 이미지 채우기 방식 (기본값: ImageFillMode.STRETCH)
8305
8497
  * @param alpha - 투명도 (0~100) (기본값: 0(불투명))
8306
8498
  * @param detail - 세부 옵션. offset/scale/mirror/align 은 fillMode=ImageFillMode.TILE 일 때만 반영 (기본값: {})
8307
- * @returns 이미지 업로드 후 배경 적용이 끝나면 resolve. 업로드 실패 시 EXECUTION_ERROR 로 reject
8499
+ * @returns 이미지 업로드 후 배경 적용이 끝나면 resolve
8500
+ * @throws {Error} 이미지 업로드에 실패한 경우 (error.code = "EXECUTION_ERROR")
8308
8501
  */
8309
8502
  setImageFill(imageUrl: string, fillMode?: ImageFillMode, alpha?: number, detail?: ImageFillDetail): Promise<void>;
8310
8503
  /**
@@ -8333,29 +8526,31 @@ declare namespace Show {
8333
8526
  * 댓글을 추가한다.
8334
8527
  *
8335
8528
  * @param text - 댓글 텍스트
8336
- * @returns 생성된 댓글 (실패 시 null)
8529
+ * @returns 생성된 댓글
8337
8530
  */
8338
- insertComment(text: string): Promise<Comment | null>;
8531
+ insertComment(text: string): Promise<Comment>;
8339
8532
  /**
8340
- * 댓글에 답글을 추가한다.
8533
+ * 댓글에 답글을 추가한다. 최상위 댓글만 지목할 수 있고 답글에는 답글을 달 수 없다.
8341
8534
  *
8342
- * @param commentProxy - 부모 댓글
8535
+ * @param commentProxy - 답글을 달 부모 댓글
8343
8536
  * @param text - 답글 텍스트
8344
8537
  * @returns 생성된 답글
8345
- * @throws {Error} 부모 댓글이 없는 경우 (error.code = "COMMENT_NOT_FOUND")
8538
+ * @throws {Error} 지목한 댓글이 슬라이드에 없는 경우 (error.code = "COMMENT_NOT_FOUND")
8539
+ * @throws {Error} 답글을 부모로 지목한 경우 (error.code = "EXECUTION_ERROR")
8346
8540
  */
8347
- replyComment(commentProxy: Comment, text: string): Promise<Comment | null>;
8541
+ replyComment(commentProxy: Comment, text: string): Promise<Comment>;
8348
8542
  /**
8349
8543
  * 댓글 하나를 삭제한다. 부모 댓글이면 그 답글도 함께 삭제된다.
8350
8544
  *
8351
8545
  * @param commentProxy - 삭제할 댓글
8546
+ * @throws {Error} 지목한 댓글이 슬라이드에 없는 경우 (error.code = "COMMENT_NOT_FOUND")
8352
8547
  */
8353
8548
  deleteComment(commentProxy: Comment): Promise<void>;
8354
8549
  /**
8355
8550
  * 여러 댓글을 일괄 삭제한다. 부모 댓글이 포함되면 그 답글도 함께 삭제된다. (UI 동작과 일치)
8356
8551
  *
8357
8552
  * @param commentProxyList - 삭제할 댓글 배열
8358
- * @throws {Error} 슬라이드에 없는 댓글이 포함된 경우 (error.code = "COMMENT_NOT_FOUND")
8553
+ * @throws {Error} 지목한 댓글이 슬라이드에 없는 경우 (error.code = "COMMENT_NOT_FOUND")
8359
8554
  */
8360
8555
  deleteComments(commentProxyList: Comment[]): Promise<void>;
8361
8556
  /**
@@ -8377,6 +8572,7 @@ declare namespace Show {
8377
8572
  * 문서를 변경하지 않는 표시용 동작이다.
8378
8573
  *
8379
8574
  * @param autoPreview - 지정하면 재생 대신 '자동 미리보기 설정'을 on/off 로 토글한다 (전환 효과 설정 시 자동으로 미리보기를 재생할지 여부, 앱 전역 설정) (기본값: 없음(즉시 미리보기 재생))
8575
+ * @throws {Error} 이 슬라이드가 현재 보고 있는 슬라이드가 아닌 경우 (error.code = "EXECUTION_ERROR")
8380
8576
  */
8381
8577
  previewTransition(autoPreview?: boolean): Promise<void>;
8382
8578
  /**
@@ -8498,9 +8694,12 @@ declare namespace Show {
8498
8694
  /**
8499
8695
  * 댓글 메모를 x, y 만큼 상대 이동시킨다.
8500
8696
  *
8501
- * @param distance - { x, y } (px 단위 이동량). 양수 = 오른쪽/아래
8697
+ * @param distance - 이동량 (px 단위). 양수 = 오른쪽/아래
8502
8698
  */
8503
- moveBy(distance: Record<string, unknown>): Promise<void>;
8699
+ moveBy(distance: {
8700
+ x: number;
8701
+ y: number;
8702
+ }): Promise<void>;
8504
8703
  /**
8505
8704
  * 댓글 메모를 슬라이드 기준 절대 위치로 이동시킨다. (상대 이동은 moveBy)
8506
8705
  *
@@ -8516,7 +8715,7 @@ declare namespace Show {
8516
8715
  }
8517
8716
  /**
8518
8717
  * 모든 도형 종류가 공유하는 공통 API 로, 위치·크기·회전 조회와 변경(getTransform/moveBy/setRotation 등),
8519
- * 정렬·순서·뒤집기(align/reorder/flip), 하이퍼링크(getHyperlink/setHyperlink/removeHyperlink),
8718
+ * 정렬·순서·뒤집기(align/reorder/flip),
8520
8719
  * 도형 종류 판별 가드(isShape/isImage/isChart 등)를 제공한다.
8521
8720
  * 대상 도형이 없으면(협업 중 삭제 등) getter 는 null 을 반환하고 setter 는 SHAPE_NOT_FOUND 로 실패한다.
8522
8721
  *
@@ -8653,13 +8852,6 @@ declare namespace Show {
8653
8852
  * @returns 상하 반전 여부. 대상 도형이 없으면 null
8654
8853
  */
8655
8854
  isFlippedV(): Promise<boolean | null>;
8656
- /**
8657
- * 도형에 설정된 하이퍼링크를 반환한다. 반환 객체를 그대로 setHyperlink 에 넘길 수 있다.
8658
- * 지원하지 않는 종류(프로그램 실행·매크로 등)가 걸려 있으면 null 이다.
8659
- *
8660
- * @returns 하이퍼링크 정보. 하이퍼링크(action)가 없으면 null
8661
- */
8662
- getHyperlink(): Promise<Hyperlink | null>;
8663
8855
  /**
8664
8856
  * 도형의 너비를 설정한다. 크기 조정이 불가능한 도형이면 무시된다.
8665
8857
  *
@@ -8727,26 +8919,41 @@ declare namespace Show {
8727
8919
  * @param alignType - 정렬 타입
8728
8920
  */
8729
8921
  align(alignType: AlignType): Promise<void>;
8922
+ }
8923
+ /**
8924
+ * 채우기·선·효과를 지원하는 도형들의 공통 API 로, 채우기(setSolidFill/setGradientFill/setImageFill 등),
8925
+ * 선 서식(setLineColor/setLineWidth/setLineDash 등),
8926
+ * 그림자·네온·부드러운 가장자리·반사 효과(setOuterShadow/setGlow/setSoftEdge 등),
8927
+ * 3D 서식(set3d/remove3d)을 제공한다.
8928
+ * 대상 도형이 없으면(협업 중 삭제 등) getter 는 null 을 반환하고 setter 는 SHAPE_NOT_FOUND 로 실패한다.
8929
+ */
8930
+ export interface BasePathShape extends BaseShape {
8931
+ /**
8932
+ * 도형에 설정된 하이퍼링크를 반환한다. 반환 객체를 그대로 setHyperlink 에 넘길 수 있다.
8933
+ * 지원하지 않는 종류(프로그램 실행·매크로 등)가 걸려 있으면 null 이다.
8934
+ * 클릭 하이퍼링크(hlinkClick)만 읽는다 — setHyperlink/removeHyperlink 와 대상이 같아
8935
+ * get → set 왕복이 성립한다 (hover 전용 링크는 이 API 계층의 대상이 아니다).
8936
+ * 글자(run) 단위로 걸린 텍스트 링크는 Shape.getTextHyperlink 로 읽는다.
8937
+ *
8938
+ * @returns 하이퍼링크 정보. 하이퍼링크(action)가 없으면 null
8939
+ */
8940
+ getHyperlink(): Promise<Hyperlink | null>;
8730
8941
  /**
8731
8942
  * 도형에 하이퍼링크를 설정한다. (getHyperlink 대칭 — 반환 객체를 그대로 넘겨 하이퍼링크를 복사할 수 있다)
8732
8943
  * 지원하지 않는 종류나 유효하지 않은 대상(삭제된 슬라이드 등)은 무시한다.
8944
+ * 글자(run) 단위 텍스트 링크는 Shape.setTextHyperlink 로 건다.
8733
8945
  *
8734
8946
  * @param hyperlink - getHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
8947
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
8735
8948
  */
8736
8949
  setHyperlink(hyperlink: Hyperlink): Promise<void>;
8737
8950
  /**
8738
8951
  * 도형의 하이퍼링크를 제거한다.
8952
+ * 글자(run) 단위 텍스트 링크는 Shape.removeTextHyperlink 로 제거한다.
8953
+ *
8954
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
8739
8955
  */
8740
8956
  removeHyperlink(): Promise<void>;
8741
- }
8742
- /**
8743
- * 채우기·선·효과를 지원하는 도형들의 공통 API 로, 채우기(setSolidFill/setGradientFill/setImageFill 등),
8744
- * 선 서식(setLineColor/setLineWidth/setLineDash 등),
8745
- * 그림자·네온·부드러운 가장자리·반사 효과(setOuterShadow/setGlow/setSoftEdge 등),
8746
- * 3D 서식(set3d/remove3d)을 제공한다.
8747
- * 대상 도형이 없으면(협업 중 삭제 등) getter 는 null 을 반환하고 setter 는 SHAPE_NOT_FOUND 로 실패한다.
8748
- */
8749
- export interface BasePathShape extends BaseShape {
8750
8957
  /**
8751
8958
  * 도형 채우기를 반환한다. (setFill 대칭 - 반환 객체를 그대로 넘길 수 있다)
8752
8959
  * type 별 개별 setter 는 setSolidFill/setGradientFill/setImageFill/setPatternFill/removeFill 이다.
@@ -8829,8 +9036,9 @@ declare namespace Show {
8829
9036
  * @param fillMode - 이미지 채우기 방식 (기본값: ImageFillMode.STRETCH)
8830
9037
  * @param alpha - 투명도 (0~100, 0=불투명) (기본값: 0)
8831
9038
  * @param detail - 세부 옵션. offset/scale/mirror/align 은 fillMode=ImageFillMode.TILE 일 때만 반영 (기본값: {})
8832
- * @returns 이미지 업로드 후 채우기 적용이 끝나면 resolve. 대상 도형이 없으면(업로드 중 삭제 포함) SHAPE_NOT_FOUND 로, 업로드 실패 시 EXECUTION_ERROR 로 reject
8833
- * @example shape.setImageFill(url, ImageFillMode.TILE, 0, { scale: { x: 50, y: 50 }, mirror: "x", align: "tl", rotateWithShape: true });
9039
+ * @returns 이미지 업로드 후 채우기 적용이 끝나면 resolve.
9040
+ * @throws {Error} 이미지 업로드에 실패한 경우 (error.code = "EXECUTION_ERROR")
9041
+ * @example await shape.setImageFill(url, ImageFillMode.TILE, 0, { scale: { x: 50, y: 50 }, mirror: "x", align: "tl", rotateWithShape: true });
8834
9042
  */
8835
9043
  setImageFill(imageUrl: string, fillMode?: ImageFillMode, alpha?: number, detail?: ImageFillDetail): Promise<void>;
8836
9044
  /**
@@ -9133,10 +9341,9 @@ declare namespace Show {
9133
9341
  /**
9134
9342
  * 텍스트 구간의 하이퍼링크를 반환한다. (setTextHyperlink 대칭 — 반환 객체를 그대로 넘겨 복사할 수 있다)
9135
9343
  * range 를 주면 그 구간의 첫 글자, range 가 없으면 텍스트의 첫 글자가 속한 run 을 기준으로 한다.
9136
- * 도형 자체에 걸린 하이퍼링크는 getHyperlink 로 읽는다.
9137
9344
  *
9138
9345
  * @param range - 조회할 텍스트 구간 (기본값: 텍스트 첫 글자)
9139
- * @returns 하이퍼링크 정보 (getHyperlink 와 같은 Hyperlink 객체). 링크 없음/텍스트 없음/미노출 action 이면 null
9346
+ * @returns 하이퍼링크 정보. 링크 없음/텍스트 없음/미노출 action 이면 null
9140
9347
  */
9141
9348
  getTextHyperlink(range?: TextRange): Promise<Hyperlink | null>;
9142
9349
  /**
@@ -9233,7 +9440,7 @@ declare namespace Show {
9233
9440
  setTextColor(color: string, range?: TextRange): Promise<void>;
9234
9441
  /**
9235
9442
  * 텍스트에 하이퍼링크를 설정한다. (getTextHyperlink 대칭 — 반환 객체를 그대로 넘겨 링크를 복사할 수 있다)
9236
- * 도형 전체에 링크를 거는 setHyperlink 와 달리 링크가 글자(run) 단위로 걸리며 하이퍼링크 서식으로 표시된다.
9443
+ * 링크는 글자(run) 단위로 걸리며 하이퍼링크 서식으로 표시된다.
9237
9444
  * 지원하지 않는 종류나 유효하지 않은 대상(삭제된 슬라이드 등)은 무시한다.
9238
9445
  *
9239
9446
  * @param hyperlink - getTextHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
@@ -9241,7 +9448,7 @@ declare namespace Show {
9241
9448
  */
9242
9449
  setTextHyperlink(hyperlink: Hyperlink, range?: TextRange): Promise<void>;
9243
9450
  /**
9244
- * 텍스트의 하이퍼링크를 제거한다. (도형 자체에 걸린 하이퍼링크는 removeHyperlink)
9451
+ * 텍스트의 하이퍼링크를 제거한다.
9245
9452
  *
9246
9453
  * @param range - 제거할 텍스트 구간 (기본값: 전체 텍스트)
9247
9454
  */
@@ -9495,9 +9702,35 @@ declare namespace Show {
9495
9702
  */
9496
9703
  readonly [__proxyBrand]?: 'Chart';
9497
9704
  /**
9498
- * 차트 종류를 반환한다. ChartType 에 없는 종류는 "unknown" 을 반환한다.
9705
+ * 도형에 설정된 하이퍼링크를 반환한다. 반환 객체를 그대로 setHyperlink 에 넘길 수 있다.
9706
+ * 지원하지 않는 종류(프로그램 실행·매크로 등)가 걸려 있으면 null 이다.
9707
+ * 클릭 하이퍼링크(hlinkClick)만 읽는다 — setHyperlink/removeHyperlink 와 대상이 같아
9708
+ * get → set 왕복이 성립한다 (hover 전용 링크는 이 API 계층의 대상이 아니다).
9709
+ * 글자(run) 단위로 걸린 텍스트 링크는 Shape.getTextHyperlink 로 읽는다.
9710
+ *
9711
+ * @returns 하이퍼링크 정보. 하이퍼링크(action)가 없으면 null
9499
9712
  */
9500
- getType(): Promise<string>;
9713
+ getHyperlink(): Promise<Hyperlink | null>;
9714
+ /**
9715
+ * 도형에 하이퍼링크를 설정한다. (getHyperlink 대칭 — 반환 객체를 그대로 넘겨 하이퍼링크를 복사할 수 있다)
9716
+ * 지원하지 않는 종류나 유효하지 않은 대상(삭제된 슬라이드 등)은 무시한다.
9717
+ * 글자(run) 단위 텍스트 링크는 Shape.setTextHyperlink 로 건다.
9718
+ *
9719
+ * @param hyperlink - getHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
9720
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
9721
+ */
9722
+ setHyperlink(hyperlink: Hyperlink): Promise<void>;
9723
+ /**
9724
+ * 도형의 하이퍼링크를 제거한다.
9725
+ * 글자(run) 단위 텍스트 링크는 Shape.removeTextHyperlink 로 제거한다.
9726
+ *
9727
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
9728
+ */
9729
+ removeHyperlink(): Promise<void>;
9730
+ /**
9731
+ * 차트 종류를 반환한다. 파일에서 읽은 100% 누적 막대형·거품형 차트는 ChartType 에 없는 그 종류의 이름을, 그 밖에 ChartType 에 없는 종류는 "unknown" 을 반환한다.
9732
+ */
9733
+ getType(): Promise<ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown">;
9501
9734
  /**
9502
9735
  * 이 차트를 편집할 수 있는지 반환한다. 외부 데이터를 소스로 하는 차트는 조회만 되고 편집은 되지 않는다.
9503
9736
  */
@@ -9517,9 +9750,9 @@ declare namespace Show {
9517
9750
  */
9518
9751
  getLegendPosition(): Promise<ChartLegendPosition>;
9519
9752
  /**
9520
- * 데이터레이블 위치를 반환한다. 데이터레이블을 표시하지 않는 차트는 "none" 을 반환한다.
9753
+ * 데이터레이블 위치를 반환한다. 데이터레이블이 설정되지 않은 차트는 "none" 이고, 데이터레이블을 갖지 않는 차트 종류(표면형)는 null 을 반환한다.
9521
9754
  */
9522
- getDataLabelPosition(): Promise<ChartDataLabelPosition>;
9755
+ getDataLabelPosition(): Promise<ChartDataLabelPosition | null>;
9523
9756
  /**
9524
9757
  * 지정한 축의 눈금선 종류를 반환한다. 눈금선을 꺼 둔 축은 "none" 이고, 그 축의 눈금선을 갖지 않는 차트 종류(원형 계열·도넛은 양축, 방사형은 세로축)는 null 을 반환한다.
9525
9758
  *
@@ -9527,22 +9760,9 @@ declare namespace Show {
9527
9760
  */
9528
9761
  getGridLine(axis: ChartAxis): Promise<ChartGridLineType | null>;
9529
9762
  /**
9530
- * 차트의 서식 상태를 한 번에 반환한다. 각 값은 이름이 같은 조회 메서드와 같은 규약을 따른다. axisTitle 과 gridLine 의 null 은 그 차트 종류에 해당 축의 제목·눈금선이 아예 없다는 뜻이고, "none" 은 쓸 수는 있지만 꺼져 있다는 뜻이다.
9531
- */
9532
- getChartInfo(): Promise<{
9533
- type: string;
9534
- title: string;
9535
- legendPosition: ChartLegendPosition;
9536
- dataLabelPosition: ChartDataLabelPosition;
9537
- axisTitle: {
9538
- horizontal: string | null;
9539
- vertical: string | null;
9540
- };
9541
- gridLine: {
9542
- horizontal: ChartGridLineType | null;
9543
- vertical: ChartGridLineType | null;
9544
- };
9545
- }>;
9763
+ * 차트의 서식 상태를 한 번에 반환한다. 각 값은 이름이 같은 조회 메서드와 같다.
9764
+ */
9765
+ getChartInfo(): Promise<ChartFormatInfo>;
9546
9766
  /**
9547
9767
  * 차트 종류를 바꾼다. 지금 종류와 같은 값을 넘기면 아무것도 바뀌지 않는다.
9548
9768
  *
@@ -9556,16 +9776,17 @@ declare namespace Show {
9556
9776
  */
9557
9777
  setStyle(style: number): Promise<void>;
9558
9778
  /**
9559
- * 차트 제목을 설정한다.
9779
+ * 차트 제목을 설정한다. 빈 문자열을 넘기면 제목을 비운다.
9560
9780
  *
9561
- * @param title - 차트에 표시할 제목
9781
+ * @param title - 차트에 표시할 제목. 255자까지 지원한다
9562
9782
  */
9563
9783
  setTitle(title: string): Promise<void>;
9564
9784
  /**
9565
9785
  * 지정한 축의 제목을 설정한다. 축 제목은 원형 계열·도넛·방사형을 뺀 차트 종류에서 지원한다.
9786
+ * 빈 문자열을 넘기면 축 제목을 비운다.
9566
9787
  *
9567
9788
  * @param axis - 제목을 설정할 축(가로축 또는 세로축)
9568
- * @param title - 축에 표시할 제목
9789
+ * @param title - 축에 표시할 제목. 255자까지 지원한다
9569
9790
  */
9570
9791
  setAxisTitle(axis: ChartAxis, title: string): Promise<void>;
9571
9792
  /**
@@ -9575,15 +9796,16 @@ declare namespace Show {
9575
9796
  */
9576
9797
  setLegendPosition(position: ChartLegendPosition): Promise<void>;
9577
9798
  /**
9578
- * 데이터레이블 위치를 설정한다. "none" 을 넘기면 데이터레이블을 숨긴다.
9579
- * 쓸 수 있는 위치는 차트 종류마다 다르며, "none" 은 모든 종류에서 쓸 수 있다.
9799
+ * 데이터레이블 위치를 설정한다. "none" 을 넘기면 데이터레이블을 없앤다.
9800
+ * 데이터레이블 설정은 2차원 차트(원형 대 원형·주식형·표면형 제외)에서만 쓸 수 있고, 3차원 차트는 현재 지원하지 않는다.
9801
+ * 쓸 수 있는 위치는 차트 종류마다 다르다.
9580
9802
  *
9581
9803
  * @param position - 데이터레이블을 놓을 자리
9582
9804
  */
9583
9805
  setDataLabelPosition(position: ChartDataLabelPosition): Promise<void>;
9584
9806
  /**
9585
9807
  * 지정한 축의 눈금선을 설정한다. "none" 을 넘기면 그 축의 눈금선을 숨긴다.
9586
- * 그 축의 눈금선을 갖지 않는 차트 종류(원형 계열·도넛은 양축, 방사형은 세로축)는 "none" 을 포함해 어떤 값을 넘겨도 오류가 발생한다.
9808
+ * 눈금선은 그 축의 눈금선을 갖는 차트 종류에서 지원한다(원형 계열·도넛은 양축, 방사형은 세로축이 없다).
9587
9809
  *
9588
9810
  * @param axis - 눈금선을 설정할 축(가로축 또는 세로축)
9589
9811
  * @param gridType - 표시할 눈금선 종류
@@ -9593,7 +9815,9 @@ declare namespace Show {
9593
9815
  /**
9594
9816
  * 표 도형을 다루는 핸들로, 셀·행·열 조회와 검색(getCell/getCells/findCells 등),
9595
9817
  * 행·열 삽입·삭제(insertRow/deleteRow/insertCol 등), 셀 병합·해제(mergeCell/unmergeCell),
9596
- * 표 스타일(setStyle/setStyleOption), 행 높이·열 너비 조정(setRowHeight/setColWidth)을 제공한다.
9818
+ * 표 스타일(setStyle/setStyleOption), 행 높이·열 너비 조정(setRowHeight/setColWidth)을 제공하며,
9819
+ * 대상 표가 없으면(협업 중 삭제 등) getter 는 null(개수는 0, 목록은 빈 배열)을 반환하고
9820
+ * setter 는 SHAPE_NOT_FOUND 로 실패한다.
9597
9821
  */
9598
9822
  export interface Table extends BaseShape {
9599
9823
  /**
@@ -9701,11 +9925,15 @@ declare namespace Show {
9701
9925
  setStyleOption(option: TableStyleOption, enabled: boolean): Promise<void>;
9702
9926
  /**
9703
9927
  * 지정 범위의 셀을 병합한다.
9928
+ * 범위에 일부만 걸친 기존 병합 셀이 있으면 그 셀을 모두 감싸도록 범위를 넓혀 병합한다.
9704
9929
  *
9705
9930
  * @param startRow - 병합 시작 행 인덱스 (0-based)
9706
9931
  * @param startCol - 병합 시작 열 인덱스 (0-based)
9707
9932
  * @param endRow - 병합 끝 행 인덱스 (0-based, inclusive)
9708
9933
  * @param endCol - 병합 끝 열 인덱스 (0-based, inclusive)
9934
+ * @throws {Error} endRow·endCol 이 표 범위를 벗어난 경우 (error.code = "INVALID_ARGUMENT")
9935
+ * @throws {Error} 범위가 셀 하나(병합 셀 하나 안쪽 포함)이거나, 넓힌 범위를 원래 범위에 걸친 셀들이 빈틈없이
9936
+ * 채우지 못하는 경우 (error.code = "INVALID_ARGUMENT")
9709
9937
  */
9710
9938
  mergeCell(startRow: number, startCol: number, endRow: number, endCol: number): Promise<void>;
9711
9939
  /**
@@ -9715,6 +9943,7 @@ declare namespace Show {
9715
9943
  * @param startCol - 해제 시작 열 인덱스 (0-based)
9716
9944
  * @param endRow - 해제 끝 행 인덱스 (0-based, inclusive)
9717
9945
  * @param endCol - 해제 끝 열 인덱스 (0-based, inclusive)
9946
+ * @throws {Error} endRow·endCol 이 표 범위를 벗어난 경우 (error.code = "INVALID_ARGUMENT")
9718
9947
  */
9719
9948
  unmergeCell(startRow: number, startCol: number, endRow: number, endCol: number): Promise<void>;
9720
9949
  /**
@@ -9724,6 +9953,7 @@ declare namespace Show {
9724
9953
  * @param baseRowIndex - 삽입 기준 행 인덱스 (0-based)
9725
9954
  * @param position - InsertPosition.ABOVE | InsertPosition.BELOW
9726
9955
  * @param insertNum - 삽입할 행 개수
9956
+ * @throws {Error} baseRowIndex 가 표 범위를 벗어난 경우 (error.code = "INVALID_ARGUMENT")
9727
9957
  */
9728
9958
  insertRow(baseRowIndex: number, position: InsertPosition, insertNum: number): Promise<void>;
9729
9959
  /**
@@ -9732,7 +9962,7 @@ declare namespace Show {
9732
9962
  *
9733
9963
  * @param startRow - 삭제 시작 행 인덱스 (0-based)
9734
9964
  * @param endRow - 삭제 끝 행 인덱스 (0-based, inclusive)
9735
- * @throws {Error} 삭제 후 남는 행이 없는 경우 (error.code = "INVALID_ARGUMENT")
9965
+ * @throws {Error} 삭제 후 남는 행이 없거나 endRow 가 표 범위를 벗어난 경우 (error.code = "INVALID_ARGUMENT")
9736
9966
  */
9737
9967
  deleteRow(startRow: number, endRow: number): Promise<void>;
9738
9968
  /**
@@ -9742,6 +9972,7 @@ declare namespace Show {
9742
9972
  * @param baseColIndex - 삽입 기준 열 인덱스 (0-based)
9743
9973
  * @param position - InsertPosition.LEFT | InsertPosition.RIGHT
9744
9974
  * @param insertNum - 삽입할 열 개수
9975
+ * @throws {Error} baseColIndex 가 표 범위를 벗어난 경우 (error.code = "INVALID_ARGUMENT")
9745
9976
  */
9746
9977
  insertCol(baseColIndex: number, position: InsertPosition, insertNum: number): Promise<void>;
9747
9978
  /**
@@ -9750,7 +9981,7 @@ declare namespace Show {
9750
9981
  *
9751
9982
  * @param startCol - 삭제 시작 열 인덱스 (0-based)
9752
9983
  * @param endCol - 삭제 끝 열 인덱스 (0-based, inclusive)
9753
- * @throws {Error} 삭제 후 남는 열이 없는 경우 (error.code = "INVALID_ARGUMENT")
9984
+ * @throws {Error} 삭제 후 남는 열이 없거나 endCol 이 표 범위를 벗어난 경우 (error.code = "INVALID_ARGUMENT")
9754
9985
  */
9755
9986
  deleteCol(startCol: number, endCol: number): Promise<void>;
9756
9987
  /**
@@ -9771,7 +10002,8 @@ declare namespace Show {
9771
10002
  /**
9772
10003
  * 표 셀 하나를 다루는 핸들로, 셀 텍스트 조회·편집과 글자·문단 서식(getText/setText/setFontStyle 등),
9773
10004
  * 셀 배경 채우기(setSolidFill/setFill), 테두리(getBorderStyle/setBorderStyle),
9774
- * 행·열 위치 조회(getRowIndex/getColIndex)를 제공한다.
10005
+ * 행·열 위치 조회(getRowIndex/getColIndex)를 제공하며,
10006
+ * 대상 표가 없으면(협업 중 삭제 등) getter 는 null 을 반환하고 setter 는 SHAPE_NOT_FOUND 로 실패한다.
9775
10007
  */
9776
10008
  export interface TableCell {
9777
10009
  /**
@@ -9924,10 +10156,9 @@ declare namespace Show {
9924
10156
  /**
9925
10157
  * 텍스트 구간의 하이퍼링크를 반환한다. (setTextHyperlink 대칭 — 반환 객체를 그대로 넘겨 복사할 수 있다)
9926
10158
  * range 를 주면 그 구간의 첫 글자, range 가 없으면 텍스트의 첫 글자가 속한 run 을 기준으로 한다.
9927
- * 도형 자체에 걸린 하이퍼링크는 getHyperlink 로 읽는다.
9928
10159
  *
9929
10160
  * @param range - 조회할 텍스트 구간 (기본값: 텍스트 첫 글자)
9930
- * @returns 하이퍼링크 정보 (getHyperlink 와 같은 Hyperlink 객체). 링크 없음/텍스트 없음/미노출 action 이면 null
10161
+ * @returns 하이퍼링크 정보. 링크 없음/텍스트 없음/미노출 action 이면 null
9931
10162
  */
9932
10163
  getTextHyperlink(range?: TextRange): Promise<Hyperlink | null>;
9933
10164
  /**
@@ -10024,7 +10255,7 @@ declare namespace Show {
10024
10255
  setTextColor(color: string, range?: TextRange): Promise<void>;
10025
10256
  /**
10026
10257
  * 텍스트에 하이퍼링크를 설정한다. (getTextHyperlink 대칭 — 반환 객체를 그대로 넘겨 링크를 복사할 수 있다)
10027
- * 도형 전체에 링크를 거는 setHyperlink 와 달리 링크가 글자(run) 단위로 걸리며 하이퍼링크 서식으로 표시된다.
10258
+ * 링크는 글자(run) 단위로 걸리며 하이퍼링크 서식으로 표시된다.
10028
10259
  * 지원하지 않는 종류나 유효하지 않은 대상(삭제된 슬라이드 등)은 무시한다.
10029
10260
  *
10030
10261
  * @param hyperlink - getTextHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
@@ -10032,7 +10263,7 @@ declare namespace Show {
10032
10263
  */
10033
10264
  setTextHyperlink(hyperlink: Hyperlink, range?: TextRange): Promise<void>;
10034
10265
  /**
10035
- * 텍스트의 하이퍼링크를 제거한다. (도형 자체에 걸린 하이퍼링크는 removeHyperlink)
10266
+ * 텍스트의 하이퍼링크를 제거한다.
10036
10267
  *
10037
10268
  * @param range - 제거할 텍스트 구간 (기본값: 전체 텍스트)
10038
10269
  */
@@ -10212,7 +10443,7 @@ declare namespace Show {
10212
10443
  }
10213
10444
  /**
10214
10445
  * 다이어그램 개체를 다루는 핸들로, 내용 편집은 지원하지 않으며
10215
- * 위치·크기·정렬·순서 등 BaseShape 공통 API 만 제공한다.
10446
+ * 위치·크기·정렬·순서 등 BaseShape 공통 API 와 하이퍼링크(getHyperlink/setHyperlink/removeHyperlink)만 제공한다.
10216
10447
  */
10217
10448
  export interface Diagram extends BaseShape {
10218
10449
  /**
@@ -10221,10 +10452,36 @@ declare namespace Show {
10221
10452
  * 외부 코드에서 접근할 수 없다.
10222
10453
  */
10223
10454
  readonly [__proxyBrand]?: 'Diagram';
10455
+ /**
10456
+ * 도형에 설정된 하이퍼링크를 반환한다. 반환 객체를 그대로 setHyperlink 에 넘길 수 있다.
10457
+ * 지원하지 않는 종류(프로그램 실행·매크로 등)가 걸려 있으면 null 이다.
10458
+ * 클릭 하이퍼링크(hlinkClick)만 읽는다 — setHyperlink/removeHyperlink 와 대상이 같아
10459
+ * get → set 왕복이 성립한다 (hover 전용 링크는 이 API 계층의 대상이 아니다).
10460
+ * 글자(run) 단위로 걸린 텍스트 링크는 Shape.getTextHyperlink 로 읽는다.
10461
+ *
10462
+ * @returns 하이퍼링크 정보. 하이퍼링크(action)가 없으면 null
10463
+ */
10464
+ getHyperlink(): Promise<Hyperlink | null>;
10465
+ /**
10466
+ * 도형에 하이퍼링크를 설정한다. (getHyperlink 대칭 — 반환 객체를 그대로 넘겨 하이퍼링크를 복사할 수 있다)
10467
+ * 지원하지 않는 종류나 유효하지 않은 대상(삭제된 슬라이드 등)은 무시한다.
10468
+ * 글자(run) 단위 텍스트 링크는 Shape.setTextHyperlink 로 건다.
10469
+ *
10470
+ * @param hyperlink - getHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
10471
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
10472
+ */
10473
+ setHyperlink(hyperlink: Hyperlink): Promise<void>;
10474
+ /**
10475
+ * 도형의 하이퍼링크를 제거한다.
10476
+ * 글자(run) 단위 텍스트 링크는 Shape.removeTextHyperlink 로 제거한다.
10477
+ *
10478
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
10479
+ */
10480
+ removeHyperlink(): Promise<void>;
10224
10481
  }
10225
10482
  /**
10226
10483
  * OLE 개체를 다루는 핸들로, 내용 편집은 지원하지 않으며
10227
- * 위치·크기·정렬·순서 등 BaseShape 공통 API 만 제공한다.
10484
+ * 위치·크기·정렬·순서 등 BaseShape 공통 API 와 하이퍼링크(getHyperlink/setHyperlink/removeHyperlink)만 제공한다.
10228
10485
  */
10229
10486
  export interface OleObject extends BaseShape {
10230
10487
  /**
@@ -10233,10 +10490,36 @@ declare namespace Show {
10233
10490
  * 외부 코드에서 접근할 수 없다.
10234
10491
  */
10235
10492
  readonly [__proxyBrand]?: 'OleObject';
10493
+ /**
10494
+ * 도형에 설정된 하이퍼링크를 반환한다. 반환 객체를 그대로 setHyperlink 에 넘길 수 있다.
10495
+ * 지원하지 않는 종류(프로그램 실행·매크로 등)가 걸려 있으면 null 이다.
10496
+ * 클릭 하이퍼링크(hlinkClick)만 읽는다 — setHyperlink/removeHyperlink 와 대상이 같아
10497
+ * get → set 왕복이 성립한다 (hover 전용 링크는 이 API 계층의 대상이 아니다).
10498
+ * 글자(run) 단위로 걸린 텍스트 링크는 Shape.getTextHyperlink 로 읽는다.
10499
+ *
10500
+ * @returns 하이퍼링크 정보. 하이퍼링크(action)가 없으면 null
10501
+ */
10502
+ getHyperlink(): Promise<Hyperlink | null>;
10503
+ /**
10504
+ * 도형에 하이퍼링크를 설정한다. (getHyperlink 대칭 — 반환 객체를 그대로 넘겨 하이퍼링크를 복사할 수 있다)
10505
+ * 지원하지 않는 종류나 유효하지 않은 대상(삭제된 슬라이드 등)은 무시한다.
10506
+ * 글자(run) 단위 텍스트 링크는 Shape.setTextHyperlink 로 건다.
10507
+ *
10508
+ * @param hyperlink - getHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
10509
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
10510
+ */
10511
+ setHyperlink(hyperlink: Hyperlink): Promise<void>;
10512
+ /**
10513
+ * 도형의 하이퍼링크를 제거한다.
10514
+ * 글자(run) 단위 텍스트 링크는 Shape.removeTextHyperlink 로 제거한다.
10515
+ *
10516
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
10517
+ */
10518
+ removeHyperlink(): Promise<void>;
10236
10519
  }
10237
10520
  /**
10238
10521
  * 컨트롤 개체를 다루는 핸들로, 내용 편집은 지원하지 않으며
10239
- * 위치·크기·정렬·순서 등 BaseShape 공통 API 만 제공한다.
10522
+ * 위치·크기·정렬·순서 등 BaseShape 공통 API 와 하이퍼링크(getHyperlink/setHyperlink/removeHyperlink)만 제공한다.
10240
10523
  */
10241
10524
  export interface Control extends BaseShape {
10242
10525
  /**
@@ -10245,6 +10528,32 @@ declare namespace Show {
10245
10528
  * 외부 코드에서 접근할 수 없다.
10246
10529
  */
10247
10530
  readonly [__proxyBrand]?: 'Control';
10531
+ /**
10532
+ * 도형에 설정된 하이퍼링크를 반환한다. 반환 객체를 그대로 setHyperlink 에 넘길 수 있다.
10533
+ * 지원하지 않는 종류(프로그램 실행·매크로 등)가 걸려 있으면 null 이다.
10534
+ * 클릭 하이퍼링크(hlinkClick)만 읽는다 — setHyperlink/removeHyperlink 와 대상이 같아
10535
+ * get → set 왕복이 성립한다 (hover 전용 링크는 이 API 계층의 대상이 아니다).
10536
+ * 글자(run) 단위로 걸린 텍스트 링크는 Shape.getTextHyperlink 로 읽는다.
10537
+ *
10538
+ * @returns 하이퍼링크 정보. 하이퍼링크(action)가 없으면 null
10539
+ */
10540
+ getHyperlink(): Promise<Hyperlink | null>;
10541
+ /**
10542
+ * 도형에 하이퍼링크를 설정한다. (getHyperlink 대칭 — 반환 객체를 그대로 넘겨 하이퍼링크를 복사할 수 있다)
10543
+ * 지원하지 않는 종류나 유효하지 않은 대상(삭제된 슬라이드 등)은 무시한다.
10544
+ * 글자(run) 단위 텍스트 링크는 Shape.setTextHyperlink 로 건다.
10545
+ *
10546
+ * @param hyperlink - getHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
10547
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
10548
+ */
10549
+ setHyperlink(hyperlink: Hyperlink): Promise<void>;
10550
+ /**
10551
+ * 도형의 하이퍼링크를 제거한다.
10552
+ * 글자(run) 단위 텍스트 링크는 Shape.removeTextHyperlink 로 제거한다.
10553
+ *
10554
+ * @throws {Error} 웹 비디오 이미지인 경우 (error.code = "UNSUPPORTED_OPERATION")
10555
+ */
10556
+ removeHyperlink(): Promise<void>;
10248
10557
  }
10249
10558
  export { };
10250
10559
  }
@@ -10399,10 +10708,22 @@ interface ApiErrorInfo {
10399
10708
  code: string;
10400
10709
  message: string;
10401
10710
  }
10402
- /** 성공 응답 — 반환값이 없는 동작은 `result` 를 생략한다. */
10711
+ /**
10712
+ * 실행으로 바뀐 호출 대상 핸들의 식별자. `attrs` 는 anchored descriptor 의 attrs 와 같은 형태다.
10713
+ * proxyClient 가 호출한 핸들에 반영하며 개발자 표면에는 드러나지 않는다.
10714
+ */
10715
+ interface ProxyRebind {
10716
+ type: string;
10717
+ attrs: Record<string, unknown>;
10718
+ }
10719
+ /**
10720
+ * 성공 응답 — 반환값이 없는 동작은 `result` 를 생략한다.
10721
+ * `rebind` 는 실행이 호출 대상의 식별자를 바꿨을 때만 온다 (예: 이름 변경).
10722
+ */
10403
10723
  interface ApiSuccessResponse<T = unknown> {
10404
10724
  success: true;
10405
10725
  result?: T;
10726
+ rebind?: ProxyRebind;
10406
10727
  }
10407
10728
  /** 실패 응답 — `SDKError.data` 로 전파되는 shape. */
10408
10729
  interface ApiErrorResponse {
@@ -10775,19 +11096,11 @@ declare function getSystemPrompt(execute: ExecuteFn): Promise<string>;
10775
11096
  * - module: OfficeModule
10776
11097
  * - execute: (method, params) => Promise<unknown> AI/Office Agent 진입점
10777
11098
  * - getToolSchemas: () => Promise<ToolSchema[]> SDK.toolList 호출
10778
- * - getSystemPrompt:() => Promise<string> SDK.systemPrompt 호출 (제공)
11099
+ * - getSystemPrompt:() => Promise<string> SDK.systemPrompt 호출
10779
11100
  * - getTools: (options?) => Promise<OfficeTool[]> 실행 가능한 도구 배열 (개발자 기본 경로)
10780
11101
  * - registerTools: (modelContext, options?) => Promise getTools 위의 콜백 등록 편의 함수
10781
11102
  * - getDocument: () => 모듈별 문서 최상위 핸들
10782
11103
  * - disconnect: () => void 리스너 제거 + pending reject
10783
- *
10784
- * Wires together:
10785
- * - postMessage context (postMessage.ts)
10786
- * - execute function (execute.ts)
10787
- * - registerTools (registerWith.ts)
10788
- *
10789
- * server-only — LLM 이 `office.execute("도구이름", [args])` 로 동적 dispatch. 옛 정적
10790
- * 개발자 표면(`sdk.api.X.Y`) + 도구 큐(`registerTool`) 는 2026-06-01 폐기.
10791
11104
  */
10792
11105
 
10793
11106
  /**