@thinkfree.dev/tfo-sdk 0.2.0 → 0.2.1

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
@@ -10,7 +10,7 @@
10
10
  * ⚠️ AUTO-GENERATED — DO NOT EDIT.
11
11
  * 오피스 구현 저장소(비공개)의 API JSDoc 에서 생성된다 — 수정은 원본 JSDoc 에서.
12
12
  *
13
- * Generated: 2026-09-14
13
+ * Generated: 2026-09-15
14
14
  */
15
15
  /** 선 대시(점선) 스타일 (OOXML a:prstDash). */
16
16
  declare const LineDash: {
@@ -292,7 +292,7 @@ type ChartDataLabelPosition = typeof ChartDataLabelPosition[keyof typeof ChartDa
292
292
  * 오피스 구현 저장소(비공개)의 API JSDoc 에서 생성된다 — 수정은 원본 JSDoc 에서.
293
293
  *
294
294
  * proxy 메서드는 postMessage bridge 를 거치므로 Promise 를 반환한다.
295
- * Generated: 2026-09-14
295
+ * Generated: 2026-09-15
296
296
  */
297
297
 
298
298
  declare namespace Word {
@@ -947,11 +947,11 @@ declare namespace Word {
947
947
  align?: TextAlign | null;
948
948
  /** line spacing — number = multiple (e.g. 1.5), "Npx" = the same multiple fixed (e.g. "1.5px"; N is a line-height multiple, not pixels), null = remove */
949
949
  lineSpacing?: number | string | null;
950
- /** left indent (px, null removes it) */
950
+ /** left indent (pt, null removes it) */
951
951
  leftIndent?: number | null;
952
- /** right indent (px, null removes it) */
952
+ /** right indent (pt, null removes it) */
953
953
  rightIndent?: number | null;
954
- /** first-line indent (px, negative for a hanging indent, null removes it) */
954
+ /** first-line indent (pt, negative for a hanging indent, null removes it) */
955
955
  firstLineIndent?: number | null;
956
956
  /** space before the paragraph (pt, null removes it) */
957
957
  spaceBefore?: number | null;
@@ -1007,9 +1007,9 @@ declare namespace Word {
1007
1007
  shapeType: ShapeType;
1008
1008
  /** 도형이 속한 영역 ID (본문 "0") */
1009
1009
  storyId: string;
1010
- /** 너비(px) */
1010
+ /** 너비(pt) */
1011
1011
  width: number;
1012
- /** 높이(px) */
1012
+ /** 높이(pt) */
1013
1013
  height: number;
1014
1014
  /** 배치 모드 (inline/infront/behind) */
1015
1015
  wrap: ShapeWrap;
@@ -1020,9 +1020,9 @@ declare namespace Word {
1020
1020
  paragraphId: string;
1021
1021
  offset?: number;
1022
1022
  };
1023
- /** floating 전용 가로 위치(px, relativeFromH 기준 — move 에 그대로 재사용 가능) */
1023
+ /** floating 전용 가로 위치(pt, relativeFromH 기준 — move 에 그대로 재사용 가능) */
1024
1024
  x?: number;
1025
- /** floating 전용 세로 위치(px, relativeFromV 기준) */
1025
+ /** floating 전용 세로 위치(pt, relativeFromV 기준) */
1026
1026
  y?: number;
1027
1027
  /** floating 전용 가로 기준점 */
1028
1028
  relativeFromH?: PositionRelativeFromH;
@@ -1969,8 +1969,8 @@ declare namespace Word {
1969
1969
  *
1970
1970
  * @param preset - base shape of the shape (e.g. "rect", "ellipse", "roundRect")
1971
1971
  * @param options - shape insertion options
1972
- * @param options.width - width (px) (기본값: 100)
1973
- * @param options.height - height (px) (기본값: 100)
1972
+ * @param options.width - width (pt) (기본값: 75)
1973
+ * @param options.height - height (pt) (기본값: 75)
1974
1974
  * @param options.offset - character position within the paragraph (0-based); takes precedence over position
1975
1975
  * @param options.position - insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (기본값: InsertAt.START)
1976
1976
  * @returns the inserted shape
@@ -1990,8 +1990,8 @@ declare namespace Word {
1990
1990
  * Inserts a text box into the paragraph.
1991
1991
  *
1992
1992
  * @param options - text box insertion options
1993
- * @param options.width - width (px) (기본값: 100)
1994
- * @param options.height - height (px) (기본값: 100)
1993
+ * @param options.width - width (pt) (기본값: 75)
1994
+ * @param options.height - height (pt) (기본값: 75)
1995
1995
  * @param options.text - initial content text
1996
1996
  * @param options.offset - character position within the paragraph (0-based); takes precedence over position
1997
1997
  * @param options.position - insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (기본값: InsertAt.START)
@@ -2020,8 +2020,8 @@ declare namespace Word {
2020
2020
  * @param options.src - path of an already uploaded image
2021
2021
  * @param options.url - image URL (uploaded first, then inserted)
2022
2022
  * @param options.base64 - base64 data (uploaded first, then inserted)
2023
- * @param options.width - width (px) (기본값: original size)
2024
- * @param options.height - height (px) (기본값: original size)
2023
+ * @param options.width - width (pt) (기본값: original size)
2024
+ * @param options.height - height (pt) (기본값: original size)
2025
2025
  * @param options.offset - character position within the paragraph (0-based); takes precedence over position
2026
2026
  * @param options.position - insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (기본값: InsertAt.START)
2027
2027
  * @returns the inserted image
@@ -2046,8 +2046,8 @@ declare namespace Word {
2046
2046
  *
2047
2047
  * @param url - web video URL (YouTube / 3DS 3DEXPERIENCE)
2048
2048
  * @param options - web video insertion options
2049
- * @param options.width - width (px) (기본값: original thumbnail size)
2050
- * @param options.height - height (px) (기본값: original thumbnail size)
2049
+ * @param options.width - width (pt) (기본값: original thumbnail size)
2050
+ * @param options.height - height (pt) (기본값: original thumbnail size)
2051
2051
  * @param options.offset - character position within the paragraph (0-based); takes precedence over position
2052
2052
  * @param options.position - insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (기본값: InsertAt.START)
2053
2053
  * @returns the inserted web video image object
@@ -2277,7 +2277,7 @@ declare namespace Word {
2277
2277
  * @example
2278
2278
  * para.setParagraphFormat({ align: TextAlign.CENTER }); // center alignment
2279
2279
  * para.setParagraphFormat({ lineSpacing: 1.5, spaceAfter: 10 }); // 1.5x line spacing, 10pt space after paragraph
2280
- * para.setParagraphFormat({ leftIndent: 20, align: null }); // 20px left indent, remove alignment
2280
+ * para.setParagraphFormat({ leftIndent: 20, align: null }); // 20pt left indent, remove alignment
2281
2281
  */
2282
2282
  setParagraphFormat(options: ParagraphFormat): Promise<void>;
2283
2283
  /**
@@ -2882,7 +2882,7 @@ declare namespace Word {
2882
2882
  * - Use the returned shape to set formatting and placement.
2883
2883
  *
2884
2884
  * @param preset - basic shape of the shape (e.g. "rect", "ellipse", "roundRect")
2885
- * @param options - size (px; an omitted axis defaults to 100)
2885
+ * @param options - size (pt; an omitted axis defaults to 75)
2886
2886
  * @returns the inserted shape
2887
2887
  * @throws {Error} if preset is not a ShapePreset value, width/height are not positive, or the range position cannot be resolved
2888
2888
  * @example
@@ -2915,8 +2915,8 @@ declare namespace Word {
2915
2915
  * @param options.src - path of an already uploaded image
2916
2916
  * @param options.url - image URL (uploaded first, then inserted)
2917
2917
  * @param options.base64 - base64 data (uploaded first, then inserted)
2918
- * @param options.width - width (px). Required with src — the original size is only known for url/base64, which are measured on upload (기본값: original size)
2919
- * @param options.height - height (px). Required with src — the original size is only known for url/base64, which are measured on upload (기본값: original size)
2918
+ * @param options.width - width (pt). Required with src — the original size is only known for url/base64, which are measured on upload (기본값: original size)
2919
+ * @param options.height - height (pt). Required with src — the original size is only known for url/base64, which are measured on upload (기본값: original size)
2920
2920
  * @returns the inserted image
2921
2921
  * @throws {Error} if exactly one source (src/url/base64) is not specified, width/height are missing or not positive with src, the range position cannot be resolved, or the image download/upload fails (Promise reject)
2922
2922
  * @example
@@ -2936,7 +2936,7 @@ declare namespace Word {
2936
2936
  * - If the preview image cannot be fetched, a fallback image is used.
2937
2937
  *
2938
2938
  * @param url - web video URL (YouTube / 3DS 3DEXPERIENCE)
2939
- * @param options - size (px) (기본값: thumbnail original size)
2939
+ * @param options - size (pt) (기본값: thumbnail original size)
2940
2940
  * @returns the inserted web video image object
2941
2941
  * @throws {Error} if url is missing or unsupported, the range position cannot be resolved, or both the preview and fallback image uploads fail (Promise reject)
2942
2942
  * @example
@@ -3467,7 +3467,7 @@ declare namespace Word {
3467
3467
  * Changes the size of the shape.
3468
3468
  * - Specify at least one of width or height. The size of the unspecified dimension is kept.
3469
3469
  *
3470
- * @param options - new size (px). Each field is optional, at least one required; omitted axes keep their current value
3470
+ * @param options - new size (pt). Each field is optional, at least one required; omitted axes keep their current value
3471
3471
  * @throws {Error} if the shape does not exist, both width and height are omitted, or a given value is not positive
3472
3472
  * @example
3473
3473
  * shape.resize({ width: 200, height: 100 }); // change width and height together
@@ -3499,11 +3499,11 @@ declare namespace Word {
3499
3499
  setZOrder(order: ShapeZOrder): Promise<void>;
3500
3500
  /**
3501
3501
  * Changes the position of a shape placed in front of or behind text.
3502
- * - x and y are px coordinates relative to relativeFromH and relativeFromV; unspecified fields are kept.
3502
+ * - x and y are pt coordinates relative to relativeFromH and relativeFromV; unspecified fields are kept.
3503
3503
  * - A reference point must be given together with its coordinate, because changing the reference point changes the meaning of the coordinate.
3504
3504
  * - If anchorParagraphId is given, the shape moves to that paragraph; otherwise only the position within the current paragraph changes.
3505
3505
  *
3506
- * @param options - move options (x/y in px). Omitted fields keep their current value
3506
+ * @param options - move options (x/y in pt). Omitted fields keep their current value
3507
3507
  * @throws {Error} if the shape does not exist, all fields are omitted, x or y is not a number, a relativeFrom value is invalid, the shape is inline, a reference point is given without its coordinate, the current position of an omitted axis is not a coordinate (aligned or percentage based), or the target paragraph does not exist or is outside the body
3508
3508
  * @example
3509
3509
  * shape.move({ x: 100, y: 50 }); // move coordinates only, keeping the current reference points
@@ -4020,7 +4020,7 @@ declare namespace Word {
4020
4020
  * 오피스 구현 저장소(비공개)의 API JSDoc 에서 생성된다 — 수정은 원본 JSDoc 에서.
4021
4021
  *
4022
4022
  * proxy 메서드는 postMessage bridge 를 거치므로 Promise 를 반환한다.
4023
- * Generated: 2026-09-14
4023
+ * Generated: 2026-09-15
4024
4024
  */
4025
4025
 
4026
4026
  declare namespace Cell {
@@ -5496,7 +5496,7 @@ declare namespace Cell {
5496
5496
  * 오피스 구현 저장소(비공개)의 API JSDoc 에서 생성된다 — 수정은 원본 JSDoc 에서.
5497
5497
  *
5498
5498
  * proxy 메서드는 postMessage bridge 를 거치므로 Promise 를 반환한다.
5499
- * Generated: 2026-09-14
5499
+ * Generated: 2026-09-15
5500
5500
  */
5501
5501
 
5502
5502
  declare namespace Show {
@@ -5784,16 +5784,6 @@ declare namespace Show {
5784
5784
  readonly MONGOLIAN_VERTICAL: "mongolianVert";
5785
5785
  };
5786
5786
  export type WriteMode = typeof WriteMode[keyof typeof WriteMode];
5787
- export const TextMode: {
5788
- readonly REPLACE: "replace";
5789
- readonly APPEND: "append";
5790
- };
5791
- export type TextMode = typeof TextMode[keyof typeof TextMode];
5792
- export const MoveMode: {
5793
- readonly ABSOLUTE: "absolute";
5794
- readonly RELATIVE: "relative";
5795
- };
5796
- export type MoveMode = typeof MoveMode[keyof typeof MoveMode];
5797
5787
  export const TextAlignV: {
5798
5788
  readonly TOP: 0;
5799
5789
  readonly MIDDLE: 1;
@@ -6029,9 +6019,7 @@ declare namespace Show {
6029
6019
  export type TableStyleType = typeof TableStyleType[keyof typeof TableStyleType];
6030
6020
  /**
6031
6021
  * ShapePreset family 정의 (family ID → preset 목록).
6032
- * 정본: commonFrame/js/uiFramework/templateDefine.js 의 shape_btn_<family>_ 팔레트.
6033
6022
  * findShapes 의 presetId 에 family 키("rectangle" 등)를 전달하면 해당 계열 전체를, ShapePreset 값("rect" 등)을 전달하면 그 도형만 매칭한다.
6034
- * 신규 도형 추가 시 templateDefine.js 와 동기화할 것.
6035
6023
  */
6036
6024
  export const ShapePresetFamily: {
6037
6025
  readonly rectangle: readonly ["rect", "roundRect", "snip1Rect", "snip2SameRect", "snip2DiagRect", "snipRoundRect", "round1Rect", "round2SameRect", "round2DiagRect"];
@@ -6105,7 +6093,7 @@ declare namespace Show {
6105
6093
  shapeType?: ShapeType;
6106
6094
  /** 도형 프리셋. ShapePreset 값(정확 매칭) 또는 ShapePresetFamily 키(계열 매칭). 배열로 여러 개 지정 가능 */
6107
6095
  presetId?: ShapePreset | ShapePresetFamily | string | (ShapePreset | ShapePresetFamily | string)[];
6108
- /** 텍스트 포함 여부 */
6096
+ /** 도형 텍스트에 포함된 문자열 */
6109
6097
  textContains?: string;
6110
6098
  /** 텍스트 존재 여부 */
6111
6099
  hasText?: boolean;
@@ -6127,7 +6115,7 @@ declare namespace Show {
6127
6115
  hasEffect?: boolean;
6128
6116
  }
6129
6117
  export interface TableFilter {
6130
- /** 셀 텍스트 포함 여부 */
6118
+ /** 셀 텍스트에 포함된 문자열 */
6131
6119
  textContains?: string;
6132
6120
  /** 행 수 */
6133
6121
  rowCount?: number;
@@ -6135,7 +6123,7 @@ declare namespace Show {
6135
6123
  colCount?: number;
6136
6124
  }
6137
6125
  export interface CommentFilter {
6138
- /** 댓글 텍스트 포함 여부 */
6126
+ /** 댓글 텍스트에 포함된 문자열 */
6139
6127
  textContains?: string;
6140
6128
  /** 답글 여부 */
6141
6129
  isReply?: boolean;
@@ -6155,7 +6143,7 @@ declare namespace Show {
6155
6143
  thruBlack?: boolean;
6156
6144
  /** 자동 진행 시간 (s) (기본값: 자동 진행 안 함) */
6157
6145
  advTm?: number;
6158
- /** 클릭으로 진행 여부 (기본값: true(클릭 시 진행)) */
6146
+ /** 클릭으로 진행 여부 (기본값: true) */
6159
6147
  advClick?: boolean;
6160
6148
  }
6161
6149
  export interface ChartFilter {
@@ -6169,9 +6157,9 @@ declare namespace Show {
6169
6157
  y: number;
6170
6158
  }
6171
6159
  export interface ShapeTransform {
6172
- /** X 좌표 (px 단위) */
6160
+ /** 좌상단 X 좌표 (px 단위, 반전·회전과 무관한 모델 기준) */
6173
6161
  x: number;
6174
- /** Y 좌표 (px 단위) */
6162
+ /** 좌상단 Y 좌표 (px 단위, 반전·회전과 무관한 모델 기준) */
6175
6163
  y: number;
6176
6164
  /** 너비 (px 단위) */
6177
6165
  width: number;
@@ -6193,9 +6181,9 @@ declare namespace Show {
6193
6181
  path?: string;
6194
6182
  }
6195
6183
  export interface ShapeMoveDistance {
6196
- /** X 이동량 (px 단위, 양수 = 오른쪽) (기본값: 0(X 유지)) */
6184
+ /** X 이동량 (px 단위, 양수 = 오른쪽). 생략하면 X 는 이동하지 않음 */
6197
6185
  x?: number;
6198
- /** Y 이동량 (px 단위, 양수 = 아래) (기본값: 0(Y 유지)) */
6186
+ /** Y 이동량 (px 단위, 양수 = 아래). 생략하면 Y 는 이동하지 않음 */
6199
6187
  y?: number;
6200
6188
  }
6201
6189
  export interface Fill {
@@ -6203,11 +6191,11 @@ declare namespace Show {
6203
6191
  type: FillType;
6204
6192
  /** solid: hex "#RRGGBB" 또는 scheme color */
6205
6193
  color?: string;
6206
- /** solid/image: 투명도(0~100, 0=불투명일 때 생략) */
6194
+ /** solid/image: 투명도 (0~100, 0=불투명). 불투명이면 키를 생략한다 */
6207
6195
  alpha?: number;
6208
6196
  /** gradient: 그라데이션 유형(lin/circle/rect/shape) */
6209
6197
  gradientType?: GradientType;
6210
- /** gradient: 각도(degree) */
6198
+ /** gradient: 각도(degree). 조회값은 0.1도 단위이며 [0, 360) 으로 정규화된다(360 은 0) */
6211
6199
  angle?: number;
6212
6200
  /** gradient: 색상 변화점 */
6213
6201
  stops?: {
@@ -6217,11 +6205,11 @@ declare namespace Show {
6217
6205
  }[];
6218
6206
  /** image: 이미지 채우기 방식 */
6219
6207
  fillMode?: ImageFillMode;
6220
- /** image: uploaded resource id for same-document setFill round-trip */
6208
+ /** image: 같은 문서 안 setFill 왕복용 업로드 리소스 id */
6221
6209
  embed?: string;
6222
- /** image: original image width in px */
6210
+ /** image: 원본 이미지 너비 (px) */
6223
6211
  width?: number;
6224
- /** image: original image height in px */
6212
+ /** image: 원본 이미지 높이 (px) */
6225
6213
  height?: number;
6226
6214
  /** image: 바둑판 오프셋 (pt). fillMode=ImageFillMode.TILE 일 때만 존재 */
6227
6215
  offset?: {
@@ -6245,9 +6233,9 @@ declare namespace Show {
6245
6233
  foreColor?: string;
6246
6234
  /** pattern: 배경색 (hex "#RRGGBB"/scheme) */
6247
6235
  backColor?: string;
6248
- /** pattern: 전경색 투명도 (0~100, 0=불투명일 때 생략) */
6236
+ /** pattern: 전경색 투명도 (0~100, 0=불투명). 불투명이면 키를 생략한다 */
6249
6237
  foreAlpha?: number;
6250
- /** pattern: 배경색 투명도 (0~100, 0=불투명일 때 생략) */
6238
+ /** pattern: 배경색 투명도 (0~100, 0=불투명). 불투명이면 키를 생략한다 */
6251
6239
  backAlpha?: number;
6252
6240
  }
6253
6241
  export interface LineStyle {
@@ -6255,7 +6243,7 @@ declare namespace Show {
6255
6243
  type: FillType;
6256
6244
  /** solid: 선 색상 (hex "#RRGGBB"/scheme) */
6257
6245
  color?: string | null;
6258
- /** solid: 투명도 (0~100, 0=불투명일 때 생략) */
6246
+ /** solid: 투명도 (0~100, 0=불투명). 불투명이면 키를 생략한다 */
6259
6247
  alpha?: number;
6260
6248
  /** gradient: 그라데이션 유형(lin/circle/rect/shape) */
6261
6249
  gradientType?: GradientType;
@@ -6265,9 +6253,9 @@ declare namespace Show {
6265
6253
  pos?: number;
6266
6254
  alpha?: number;
6267
6255
  }[];
6268
- /** gradient: 각도(degree) */
6256
+ /** gradient: 각도(degree). 조회값은 0.1도 단위이며 [0, 360) 으로 정규화된다(360 은 0) */
6269
6257
  angle?: number;
6270
- /** 선 두께 (pt). 선 없음이면 null */
6258
+ /** 선 두께 (pt). 선 없음(noFill)이어도 두께는 그대로 담긴다 */
6271
6259
  width: number | null;
6272
6260
  /** 선 대시 유형 */
6273
6261
  dash: LineDash | null;
@@ -6276,59 +6264,126 @@ declare namespace Show {
6276
6264
  /** 선 연결(모서리) 유형 */
6277
6265
  join: LineJoin | null;
6278
6266
  }
6267
+ export interface LineEnd {
6268
+ /** 화살표 타입 */
6269
+ type: LineEndType;
6270
+ /** 화살표 너비 */
6271
+ width: LineEndSize;
6272
+ /** 화살표 길이 */
6273
+ length: LineEndSize;
6274
+ }
6275
+ export interface ImageCrop {
6276
+ /** 왼쪽 crop 퍼센트 */
6277
+ left: number;
6278
+ /** 위쪽 crop 퍼센트 */
6279
+ top: number;
6280
+ /** 오른쪽 crop 퍼센트 */
6281
+ right: number;
6282
+ /** 아래쪽 crop 퍼센트 */
6283
+ bottom: number;
6284
+ }
6285
+ export interface BulletStyle {
6286
+ /** 글머리 기호 유형 */
6287
+ type: BulletType;
6288
+ /** BulletType.AUTO_NUM: 번호 매기기 유형, BulletType.CHAR: 글머리 문자 유형 (CharType 7종 프리셋의 문자와 글꼴이 모두 일치할 때만 포함) */
6289
+ subType?: NumberedType | CharType;
6290
+ /** 시작 번호 (BulletType.AUTO_NUM 일 때만 포함) */
6291
+ startAt?: number;
6292
+ /** 글머리 문자 원문 (BulletType.CHAR 일 때만 포함. 프리셋 밖의 문자도 그대로 반환) */
6293
+ char?: string;
6294
+ }
6295
+ export interface OuterShadow {
6296
+ /** hex (#RRGGBB) 또는 scheme color (기본값: "#000000") */
6297
+ color?: string;
6298
+ /** 투명도 (0~100, 0=불투명) (기본값: 50) */
6299
+ alpha?: number;
6300
+ /** 흐림 반경 (pt) (기본값: 6) */
6301
+ blur?: number;
6302
+ /** 거리 (pt) (기본값: 6) */
6303
+ dist?: number;
6304
+ /** 방향 (degree) (기본값: 90) */
6305
+ dir?: number;
6306
+ /** 가로 배율 (%) (기본값: 100) */
6307
+ sx?: number;
6308
+ /** 세로 배율 (%) (기본값: 100) */
6309
+ sy?: number;
6310
+ /** 가로 기울임 (degree) (기본값: 0) */
6311
+ kx?: number;
6312
+ /** 세로 기울임 (degree) (기본값: 0) */
6313
+ ky?: number;
6314
+ /** 정렬 기준 (기본값: RectAlign.CENTER) */
6315
+ algn?: RectAlign;
6316
+ /** 도형 회전 연동 (기본값: false) */
6317
+ rotWithShape?: boolean;
6318
+ }
6319
+ export interface InnerShadow {
6320
+ /** hex (#RRGGBB) 또는 scheme color (기본값: "#000000") */
6321
+ color?: string;
6322
+ /** 투명도 (0~100, 0=불투명) (기본값: 50) */
6323
+ alpha?: number;
6324
+ /** 흐림 반경 (pt) (기본값: 6) */
6325
+ blur?: number;
6326
+ /** 거리 (pt) (기본값: 6) */
6327
+ dist?: number;
6328
+ /** 방향 (degree) (기본값: 90) */
6329
+ dir?: number;
6330
+ }
6331
+ export interface Glow {
6332
+ /** hex (#RRGGBB) 또는 scheme color (기본값: "#356FFF") */
6333
+ color?: string;
6334
+ /** 투명도 (0~100, 0=불투명) (기본값: 50) */
6335
+ alpha?: number;
6336
+ /** 광선 반경 (pt) (기본값: 10) */
6337
+ rad?: number;
6338
+ }
6339
+ export interface SoftEdge {
6340
+ /** 반경 (pt) (기본값: 5) */
6341
+ rad?: number;
6342
+ }
6343
+ export interface Reflection {
6344
+ /** 흐림 반경 (pt) (기본값: 0.5) */
6345
+ blur?: number;
6346
+ /** 거리 (pt) (기본값: 0) */
6347
+ dist?: number;
6348
+ /** 시작 위치 (0~100). 렌더링에는 반영되지 않는다 (기본값: 0) */
6349
+ stPos?: number;
6350
+ /** 반사 크기 (0~100) (기본값: 50) */
6351
+ endPos?: number;
6352
+ /** 시작 투명도 (0~100, 0=불투명) (기본값: 50) */
6353
+ startAlpha?: number;
6354
+ /** 끝 투명도 (0~100, 0=불투명) (기본값: 99.7) */
6355
+ endAlpha?: number;
6356
+ /** 방향 (degree). 렌더링에는 반영되지 않는다 (기본값: 90) */
6357
+ dir?: number;
6358
+ /** 페이드 방향 (degree). 렌더링에는 반영되지 않는다 (기본값: 90) */
6359
+ fadeDir?: number;
6360
+ /** 가로 배율 (%) (기본값: 100) */
6361
+ sx?: number;
6362
+ /** 세로 배율 (%) (기본값: -100) */
6363
+ sy?: number;
6364
+ /** 가로 기울임 (degree) (기본값: 0) */
6365
+ kx?: number;
6366
+ /** 세로 기울임 (degree) (기본값: 0) */
6367
+ ky?: number;
6368
+ /** 정렬 기준 (기본값: RectAlign.BOTTOM_LEFT) */
6369
+ algn?: RectAlign;
6370
+ /** 도형 회전 연동 (기본값: false) */
6371
+ rotWithShape?: boolean;
6372
+ }
6279
6373
  export interface Effects {
6280
- /** 외부 그림자. 전체 필드를 setOuterShadow 공개 인자로 사용할 수 있다. 배치 파라미터는 sx/sy 배율·kx/ky 기울임(degree)·algn 정렬·rotWithShape 이다. alpha 항상 포함(불투명=0) */
6281
- outerShadow?: {
6282
- color: string;
6283
- alpha: number;
6284
- blur: number;
6285
- dist: number;
6286
- dir: number;
6287
- sx: number;
6288
- sy: number;
6289
- kx: number;
6290
- ky: number;
6291
- algn: string;
6292
- rotWithShape: boolean;
6293
- };
6294
- /** 내부 그림자 (setInnerShadow). 내부 그림자는 배치 파라미터가 없다 */
6295
- innerShadow?: {
6296
- color: string;
6297
- alpha: number;
6298
- blur: number;
6299
- dist: number;
6300
- dir: number;
6301
- };
6302
- /** 네온(광선) (setGlow). alpha 항상 포함(불투명=0) */
6303
- glow?: {
6304
- color: string;
6305
- alpha: number;
6306
- rad: number;
6307
- };
6308
- /** 옅은 테두리 (setSoftEdge) */
6309
- softEdge?: {
6310
- rad: number;
6311
- };
6312
- /** 반사. 전체 필드를 setReflection 공개 인자로 사용할 수 있다. 렌더에 반영되는 것은 blur/dist/endPos/startAlpha/endAlpha 이며 dir 은 렌더가 참조하지 않는다. 배치 파라미터는 sx/sy 배율·kx/ky 기울임(degree)·algn 정렬·rotWithShape 이다. stPos·fadeDir 은 웹쇼 렌더가 참조하지 않지만, 외부 문서(PowerPoint 등)에서 온 값이 setReflection 의 기본값으로 덮이지 않도록 함께 반환한다 */
6313
- reflection?: {
6314
- blur: number;
6315
- dist: number;
6316
- stPos: number;
6317
- endPos: number;
6318
- dir: number;
6319
- fadeDir: number;
6320
- startAlpha: number;
6321
- endAlpha: number;
6322
- sx: number;
6323
- sy: number;
6324
- kx: number;
6325
- ky: number;
6326
- algn: string;
6327
- rotWithShape: boolean;
6328
- };
6329
- /** 카메라(회전) 3D (set3d 의 scene3d) */
6374
+ /** 외부 그림자 */
6375
+ outerShadow?: OuterShadow;
6376
+ /** 내부 그림자 */
6377
+ innerShadow?: InnerShadow;
6378
+ /** 네온(광선) */
6379
+ glow?: Glow;
6380
+ /** 옅은 테두리 */
6381
+ softEdge?: SoftEdge;
6382
+ /** 반사 */
6383
+ reflection?: Reflection;
6384
+ /** 카메라(회전) 3D */
6330
6385
  scene3d?: Scene3d;
6331
- /** 입체(깊이) 3D (set3d 의 sp3d) */
6386
+ /** 입체(깊이) 3D */
6332
6387
  sp3d?: Sp3d;
6333
6388
  }
6334
6389
  export interface ImageFillDetail {
@@ -6346,33 +6401,9 @@ declare namespace Show {
6346
6401
  mirror?: ImageTileFlip;
6347
6402
  /** 바둑판 정렬 기준점 (기본값: RectAlign.TOP_LEFT) */
6348
6403
  align?: RectAlign;
6349
- /** 도형과 함께 회전 여부 (기본값: 기존 동작 유지(기본 true)) */
6404
+ /** 도형과 함께 회전 여부. 생략하면 기존 동작 유지 (모델 기본 true) */
6350
6405
  rotateWithShape?: boolean;
6351
6406
  }
6352
- export interface Effect {
6353
- /** 효과 타입 */
6354
- type: EffectType;
6355
- /** 효과 색상 (outer/inner shadow, glow 에만 사용) */
6356
- color?: EffectColor;
6357
- /** 흐림 반경 (pt) */
6358
- blurRad?: number;
6359
- /** 거리 (pt) */
6360
- dist?: number;
6361
- /** 방향 (degree) */
6362
- dir?: number;
6363
- /** glow/softEdge 반경 (pt) */
6364
- rad?: number;
6365
- /** reflection 크기 (0~100) */
6366
- endPos?: number;
6367
- }
6368
- export interface EffectColor {
6369
- /** hex (#RRGGBB) 또는 scheme color */
6370
- strVal: string;
6371
- /** 투명도 (0~100, UI 단위) */
6372
- colorEffects?: {
6373
- alpha: number;
6374
- };
6375
- }
6376
6407
  export interface Scene3d {
6377
6408
  /** camera 프리셋 (orthographicFront, isometricLeftDown 등) */
6378
6409
  prst?: string;
@@ -6396,7 +6427,7 @@ declare namespace Show {
6396
6427
  min: number | null;
6397
6428
  /** 설정 가능한 최댓값, 범위를 알 수 없으면 null */
6398
6429
  max: number | null;
6399
- /** 값의 단위. pct는 1/1000%, ang는 1/60000도이며 범위를 알 수 없으면 null */
6430
+ /** 값의 단위 (pct 는 1/1000%, ang 는 1/60000도). 범위를 알 수 없으면 null */
6400
6431
  unit: string | null;
6401
6432
  }
6402
6433
  export interface AdjustValueUpdate {
@@ -6417,7 +6448,7 @@ declare namespace Show {
6417
6448
  rowIndex?: number;
6418
6449
  /** 특정 열만 (0-based, 대표 셀 기준) */
6419
6450
  colIndex?: number;
6420
- /** true: 텍스트 비어있는 셀, false: 텍스트 있는 셀 */
6451
+ /** true: 텍스트가 비어 있는 셀, false: 텍스트가 있는 셀 */
6421
6452
  isEmpty?: boolean;
6422
6453
  /** true: 병합 대표 셀, false: 단일 셀 */
6423
6454
  isMerged?: boolean;
@@ -6438,6 +6469,12 @@ declare namespace Show {
6438
6469
  /** 선 대시 유형 */
6439
6470
  dash: LineDash | null;
6440
6471
  }
6472
+ export interface TextRange {
6473
+ /** 시작 글자 offset (0-based) */
6474
+ from: number;
6475
+ /** 끝 글자 offset (포함) */
6476
+ to: number;
6477
+ }
6441
6478
  export interface FontStyle {
6442
6479
  /** 글자 크기 (pt) */
6443
6480
  fontSize?: number;
@@ -6459,17 +6496,17 @@ declare namespace Show {
6459
6496
  export interface ParagraphStyle {
6460
6497
  /** 가로 정렬 */
6461
6498
  alignH?: TextAlignH;
6462
- /** 줄 간격 값 (UI "줄 간격"의 값). MULTIPLE 이면 배수 백분율(150=1.5배), EXACT 면 pt */
6499
+ /** 줄 간격 값. MULTIPLE 이면 배수 백분율(150=1.5배), EXACT 이면 pt */
6463
6500
  lineSpacing?: number;
6464
6501
  /** 줄 간격 유형 (기본값: LineSpacingType.MULTIPLE) */
6465
6502
  lineSpacingType?: LineSpacingType;
6466
- /** 단락 전체의 왼쪽 여백 (pt, UI "텍스트 앞") */
6503
+ /** 단락 전체의 왼쪽 여백 (pt) */
6467
6504
  marginLeft?: number;
6468
- /** 첫 줄만의 들여쓰기 (pt, UI "첫 줄"). 양수는 들여쓰기, 음수는 내어쓰기, 0 은 없음 */
6505
+ /** 첫 줄에만 적용되는 들여쓰기 (pt). 양수는 들여쓰기, 음수는 내어쓰기, 0 은 들여쓰기 없음 */
6469
6506
  firstLineIndent?: number;
6470
- /** 단락 앞 간격 (pt, UI "문단 위") */
6507
+ /** 단락 앞 간격 (pt) */
6471
6508
  spaceBefore?: number;
6472
- /** 단락 뒤 간격 (pt, UI "문단 아래") */
6509
+ /** 단락 뒤 간격 (pt) */
6473
6510
  spaceAfter?: number;
6474
6511
  }
6475
6512
  const __proxyBrand: unique symbol;
@@ -7369,7 +7406,7 @@ declare namespace Show {
7369
7406
  */
7370
7407
  setStyle(styleIndex: number): Promise<void>;
7371
7408
  }
7372
- /** 모든 도형 종류가 공유하는 공통 API 로, 위치·크기·회전 조회와 변경(getTransform/moveBy/rotate 등), 정렬·순서·뒤집기(align/reorder/flip), 하이퍼링크(getHyperlink/setHyperlink/removeHyperlink), 도형 종류 판별 가드(isShape/isImage/isChart 등)를 제공한다. */
7409
+ /** 모든 도형 종류가 공유하는 공통 API 로, 위치·크기·회전 조회와 변경(getTransform/moveBy/setRotation 등), 정렬·순서·뒤집기(align/reorder/flip), 하이퍼링크(getHyperlink/setHyperlink/removeHyperlink), 도형 종류 판별 가드(isShape/isImage/isChart 등)를 제공한다. */
7373
7410
  export interface BaseShape {
7374
7411
  /**
7375
7412
  * 이 핸들이 `Shape` 인지 판별한다 (union 좁히기용 type guard).
@@ -7418,38 +7455,42 @@ declare namespace Show {
7418
7455
  isControl(): this is Control;
7419
7456
  /**
7420
7457
  * 도형의 위치, 크기, 회전 정보를 반환한다.
7458
+ * x/y 는 반전(flip) 여부와 무관하게 도형의 좌상단이라, 반환값을 다른 도형의 setTransform 에 그대로 넘기면
7459
+ * 두 도형이 같은 자리에 놓인다.
7460
+ * 값은 에디터 입력 단위로 반올림해 반환한다 - 크기는 소수 한 자리, 위치는 정수.
7461
+ * setter 도 같은 단위로 넣으므로, 임포트 문서처럼 더 잘게 놓인 도형은 되넘길 때 그만큼 움직인다.
7421
7462
  *
7422
- * @returns 도형의 위치·크기·회전 정보. 모델 없음(협업 삭제 등)이면 null
7463
+ * @returns 도형의 위치·크기·회전 정보. 대상 도형이 없으면(협업 중 삭제 등) null
7423
7464
  */
7424
7465
  getTransform(): Promise<ShapeTransform | null>;
7425
7466
  /**
7426
7467
  * 도형의 너비를 반환한다. (setWidth 대칭)
7427
7468
  *
7428
- * @returns 너비 (px 단위). 모델 없음이면 null
7469
+ * @returns 너비 (px 단위). 대상 도형이 없으면 null
7429
7470
  */
7430
7471
  getWidth(): Promise<number | null>;
7431
7472
  /**
7432
7473
  * 도형의 높이를 반환한다. (setHeight 대칭)
7433
7474
  *
7434
- * @returns 높이 (px 단위). 모델 없음이면 null
7475
+ * @returns 높이 (px 단위). 대상 도형이 없으면 null
7435
7476
  */
7436
7477
  getHeight(): Promise<number | null>;
7437
7478
  /**
7438
7479
  * 도형의 X 좌표를 반환한다. (setX 대칭)
7439
7480
  *
7440
- * @returns X 좌표 (px 단위). 모델 없음이면 null
7481
+ * @returns X 좌표 (px 단위). 대상 도형이 없으면 null
7441
7482
  */
7442
7483
  getX(): Promise<number | null>;
7443
7484
  /**
7444
7485
  * 도형의 Y 좌표를 반환한다. (setY 대칭)
7445
7486
  *
7446
- * @returns Y 좌표 (px 단위). 모델 없음이면 null
7487
+ * @returns Y 좌표 (px 단위). 대상 도형이 없으면 null
7447
7488
  */
7448
7489
  getY(): Promise<number | null>;
7449
7490
  /**
7450
- * 도형의 회전 각도를 반환한다. (rotate 대칭)
7491
+ * 도형의 회전 각도를 반환한다. (setRotation 대칭)
7451
7492
  *
7452
- * @returns 회전 각도 (degree). 모델 없음이면 null
7493
+ * @returns 회전 각도 (degree). 대상 도형이 없으면 null
7453
7494
  */
7454
7495
  getRotation(): Promise<number | null>;
7455
7496
  /**
@@ -7461,84 +7502,120 @@ declare namespace Show {
7461
7502
  /**
7462
7503
  * 도형이 placeholder(제목 · 본문 틀 등)인지 반환한다.
7463
7504
  *
7464
- * @returns placeholder 여부
7505
+ * @returns placeholder 여부. 대상 도형이 없으면 null
7465
7506
  */
7466
- isPlaceholder(): Promise<boolean>;
7507
+ isPlaceholder(): Promise<boolean | null>;
7467
7508
  /**
7468
- * 도형에 설정된 하이퍼링크를 반환한다.
7469
- * 반환 객체를 그대로 setHyperlink 에 넘길 수 있다.
7470
- * 지원하지 않는 action(program/macro/ole 등)은 공개 타입으로 노출하지 않고 null 을 반환한다.
7509
+ * 도형의 placeholder 종류를 반환한다.
7510
+ *
7511
+ * @returns placeholder 종류. placeholder 가 아니거나 대상 도형이 없으면 null
7512
+ */
7513
+ getPlaceholderType(): Promise<PlaceholderType | null>;
7514
+ /**
7515
+ * 도형이 텍스트를 담고 있는지 반환한다. 에디터가 텍스트를 비었다고 보는 기준과 같다 —
7516
+ * 공백만 있거나 빈 문단이 둘 이상(개행만 넣은 상태)이면 true, 빈 문단 하나뿐이면 false 다.
7517
+ * 도형 레벨 텍스트가 없는 종류(표·그룹·차트)는 항상 false 다. (표는 셀 단위로 조회)
7518
+ *
7519
+ * @returns 텍스트 존재 여부. 대상 도형이 없으면 null
7520
+ */
7521
+ hasText(): Promise<boolean | null>;
7522
+ /**
7523
+ * 부모(슬라이드, 그룹 자식이면 그 그룹) 안에서 도형의 z-order 순번을 반환한다. 0 이 맨 뒤이며, 클수록 앞이다.
7524
+ *
7525
+ * @returns z-order 순번. 대상 도형이 없으면 null
7526
+ */
7527
+ getZOrderIndex(): Promise<number | null>;
7528
+ /**
7529
+ * 도형이 좌우로 반전된 상태인지 반환한다. (flip(FlipDirection.HORIZONTAL) 을 호출하면 이 값이 뒤집힌다)
7530
+ *
7531
+ * @returns 좌우 반전 여부. 대상 도형이 없으면 null
7532
+ */
7533
+ isFlippedH(): Promise<boolean | null>;
7534
+ /**
7535
+ * 도형이 상하로 반전된 상태인지 반환한다. (flip(FlipDirection.VERTICAL) 을 호출하면 이 값이 뒤집힌다)
7536
+ *
7537
+ * @returns 상하 반전 여부. 대상 도형이 없으면 null
7538
+ */
7539
+ isFlippedV(): Promise<boolean | null>;
7540
+ /**
7541
+ * 도형에 설정된 하이퍼링크를 반환한다. 반환 객체를 그대로 setHyperlink 에 넘길 수 있다.
7542
+ * 지원하지 않는 종류(프로그램 실행·매크로 등)가 걸려 있으면 null 이다.
7471
7543
  *
7472
7544
  * @returns 하이퍼링크 정보. 하이퍼링크(action)가 없으면 null
7473
7545
  */
7474
7546
  getHyperlink(): Promise<Hyperlink | null>;
7475
7547
  /**
7476
- * 도형의 너비를 설정한다.
7548
+ * 도형의 너비를 설정한다. 크기 조정이 불가능한 도형이면 무시된다.
7477
7549
  *
7478
- * @param width - 너비 (px 단위)
7550
+ * @param width - 너비 (px 단위, 소수 한 자리로 반올림)
7479
7551
  */
7480
7552
  setWidth(width: number): Promise<void>;
7481
7553
  /**
7482
- * 도형의 높이를 설정한다.
7554
+ * 도형의 높이를 설정한다. 크기 조정이 불가능한 도형이면 무시된다.
7483
7555
  *
7484
- * @param height - 높이 (px 단위)
7556
+ * @param height - 높이 (px 단위, 소수 한 자리로 반올림)
7485
7557
  */
7486
7558
  setHeight(height: number): Promise<void>;
7487
7559
  /**
7488
- * 도형의 X 좌표를 절대값으로 설정한다. (상대 이동은 comment.moveBy 등과 구분)
7560
+ * 도형의 X 좌표를 절대값으로 설정한다. 이동이 불가능한 도형이면 무시된다. (상대 이동은 moveBy)
7489
7561
  *
7490
- * @param x - X 좌표 (px 단위)
7562
+ * @param x - X 좌표 (px 단위, 정수로 반올림)
7491
7563
  */
7492
7564
  setX(x: number): Promise<void>;
7493
7565
  /**
7494
- * 도형의 Y 좌표를 절대값으로 설정한다.
7566
+ * 도형의 Y 좌표를 절대값으로 설정한다. 이동이 불가능한 도형이면 무시된다.
7495
7567
  *
7496
- * @param y - Y 좌표 (px 단위)
7568
+ * @param y - Y 좌표 (px 단위, 정수로 반올림)
7497
7569
  */
7498
7570
  setY(y: number): Promise<void>;
7499
7571
  /**
7500
7572
  * 도형을 현재 위치 기준으로 x, y 만큼 상대 이동한다. (절대 좌표 설정은 setX / setY)
7501
7573
  *
7502
7574
  * @param distance - 이동량 (px 단위)
7575
+ * @throws {Error} 이동한 결과 좌표가 setX/setY 와 같은 위치 범위를 벗어나는 경우 (error.code = "INVALID_ARGUMENT")
7503
7576
  */
7504
7577
  moveBy(distance: ShapeMoveDistance): Promise<void>;
7505
7578
  /**
7506
- * 도형을 회전한다.
7579
+ * 도형의 회전 각도를 절대값으로 설정한다. 회전이 불가능한 도형이면 무시된다. (getRotation 대칭)
7507
7580
  *
7508
7581
  * @param rotation - 회전 각도 (degree)
7509
7582
  */
7510
- rotate(rotation: number): Promise<void>;
7583
+ setRotation(rotation: number): Promise<void>;
7511
7584
  /**
7512
7585
  * 도형의 위치·크기·회전을 한 번에 설정한다. getTransform() 반환값을 그대로 넘길 수 있다. (getTransform 대칭)
7513
- * 제공된 필드만 적용하며, 각 필드는 개별 setter 의 잠금 가드(canResize/canMove/canRotate)를 따른다.
7514
- * 크기→위치→회전 순으로 개별 액션을 발생시키므로 실행 취소는 여러 단계가 될 수 있다.
7586
+ * 값을 준 필드만 크기→위치→회전 순으로 적용하고, 생략한 필드는 현재 값을 유지한다.
7587
+ * 각 필드는 개별 setter 와 같이 해당 조작(크기/이동/회전)이 불가능한 도형에서 무시된다.
7515
7588
  *
7516
- * @param transform - 위치/크기 (px) · 회전 (degree) (기본값: 현재 값 유지)
7589
+ * @param transform - 위치/크기 (px) · 회전 (degree)
7517
7590
  */
7518
- setTransform(transform?: ShapeTransform): Promise<void>;
7591
+ setTransform(transform?: Partial<ShapeTransform>): Promise<void>;
7519
7592
  /**
7520
- * 도형을 상하 또는 좌우로 반전한다.
7593
+ * 도형을 상하 또는 좌우로 반전한다. 현재 반전 상태를 뒤집는 토글이며, 지금 반전돼 있는지는
7594
+ * isFlippedH()/isFlippedV() 로 읽는다. 회전이 불가능한 도형에서는 반전도 무시된다.
7595
+ * 회전된 도형은 각도도 거울상으로 함께 바뀐다 (getRotation() 값이 360 - 기존 각도 로 바뀐다).
7521
7596
  *
7522
7597
  * @param direction - 반전 방향
7523
7598
  */
7524
7599
  flip(direction: FlipDirection): Promise<void>;
7525
7600
  /**
7526
- * 도형의 정렬 순서(앞으로/뒤로)를 변경한다.
7601
+ * 도형의 정렬 순서(앞으로/뒤로)를 변경한다. 이미 목표 위치라 바뀔 것이 없으면 무시된다.
7527
7602
  *
7528
7603
  * @param order - 순서 변경 타입
7529
7604
  */
7530
7605
  reorder(order: ShapeZOrder): Promise<void>;
7531
7606
  /**
7532
- * 도형을 슬라이드 기준으로 정렬한다.
7607
+ * 도형을 슬라이드 기준으로 정렬한다. 이동이 불가능한 도형이면 무시된다.
7608
+ * 그룹 자식도 그룹 안이 아니라 슬라이드를 기준으로 움직인다(에디터와 같다).
7609
+ * 자식이 그룹 밖으로 나가면 그룹이 자식을 담도록 함께 넓어진다.
7533
7610
  *
7534
7611
  * @param alignType - 정렬 타입
7535
7612
  */
7536
7613
  align(alignType: AlignType): Promise<void>;
7537
7614
  /**
7538
7615
  * 도형에 하이퍼링크를 설정한다. (getHyperlink 대칭 — 반환 객체를 그대로 넘겨 하이퍼링크를 복사할 수 있다)
7539
- * other(program/macro/ole 등)와 유효하지 않은 대상(없는 슬라이드 id·ShowJumpType 밖의 값)은 무시한다.
7616
+ * 지원하지 않는 종류나 유효하지 않은 대상(없는 슬라이드 id 등)은 무시한다.
7540
7617
  *
7541
- * @param hyperlink - getHyperlink() 반환값 (baseShape 의 Hyperlink). type 이 없으면 무시한다
7618
+ * @param hyperlink - getHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
7542
7619
  */
7543
7620
  setHyperlink(hyperlink: Hyperlink): Promise<void>;
7544
7621
  /**
@@ -7549,65 +7626,65 @@ declare namespace Show {
7549
7626
  /** 채우기·선·효과를 지원하는 도형들의 공통 API 로, 채우기(setSolidFill/setGradientFill/setImageFill 등), 선 서식(setLineColor/setLineWidth/setLineDash 등), 그림자·네온·부드러운 가장자리·반사 효과(setOuterShadow/setGlow/setSoftEdge 등), 3D 서식(set3d/remove3d)을 제공한다. */
7550
7627
  export interface BasePathShape extends BaseShape {
7551
7628
  /**
7552
- * 도형 채우기를 반환한다. (setSolidFill/setGradientFill/setImageFill/removeFill 대칭)
7553
- * type 으로 분기해 그대로 대응 setter 에 넘길 수 있다.
7629
+ * 도형 채우기를 반환한다. (setFill 대칭 - 반환 객체를 그대로 넘길 수 있다)
7630
+ * type 별 개별 setter 는 setSolidFill/setGradientFill/setImageFill/setPatternFill/removeFill 이다.
7554
7631
  *
7555
- * @returns 채우기 정보. noFill 이면 `{ type: FillType.NONE }`, 모델 없음(협업 삭제 등)이면 null
7632
+ * @returns 채우기 정보. noFill 이면 `{ type: FillType.NONE }`, 대상 도형이 없으면(협업 중 삭제 등) null
7556
7633
  */
7557
7634
  getFill(): Promise<Fill | null>;
7558
7635
  /**
7559
- * 선 스타일을 반환한다. (setLineColor/setLineWidth/setLineDash/setLineCap/setLineJoin 대칭)
7636
+ * 선 스타일을 반환한다. (setLineStyle 대칭 - 반환 객체를 그대로 넘길 수 있다)
7637
+ * 개별 setter 는 setLineColor/setLineGradient/setLineWidth/setLineDash/setLineCap/setLineJoin 이다.
7560
7638
  *
7561
- * 선 채우기는 getFill 과 같은 판별 유니언으로 읽는다 — type 으로 분기하며 단색은 color,
7562
- * 그라데이션은 gradientType/stops/angle 을 담는다.
7639
+ * 선 채우기는 getFill 과 같은 형태로 담는다.
7563
7640
  *
7564
- * @returns 선 스타일. 모델 없으면 null
7641
+ * @returns 선 스타일. 대상 도형이 없으면 null
7565
7642
  */
7566
7643
  getLineStyle(): Promise<LineStyle | null>;
7567
7644
  /**
7568
7645
  * 선 색상을 반환한다. (setLineColor 대칭. 투명도까지 필요하면 getLineStyle 사용)
7569
7646
  *
7570
- * @returns 선 색상 (hex "#RRGGBB"/scheme). 선 없음/모델 없음이면 null
7647
+ * @returns 선 색상 (hex "#RRGGBB" — scheme color 도 hex 로 풀려서 나온다). 선이 없거나 대상 도형이 없으면 null
7571
7648
  */
7572
7649
  getLineColor(): Promise<string | null>;
7573
7650
  /**
7574
7651
  * 선 두께(pt)를 반환한다. (setLineWidth 대칭)
7575
7652
  *
7576
- * @returns 선 두께 (pt). 선 없음/모델 없음이면 null
7653
+ * @returns 선 두께 (pt). 선 없음(noFill)이어도 두께는 그대로 반환한다. 대상 도형이 없으면 null
7577
7654
  */
7578
7655
  getLineWidth(): Promise<number | null>;
7579
7656
  /**
7580
7657
  * 선 대시 유형을 반환한다. (setLineDash 대칭)
7581
7658
  *
7582
- * @returns 선 대시 유형. LineDash enum 이 아니거나 모델 없음이면 null
7659
+ * @returns 선 대시 유형. LineDash enum 이 아니거나 대상 도형이 없으면 null
7583
7660
  */
7584
7661
  getLineDash(): Promise<LineDash | null>;
7585
7662
  /**
7586
7663
  * 선 끝 모양(cap)을 반환한다. (setLineCap 대칭)
7587
7664
  *
7588
- * @returns 선 끝 모양. 없음/모델 없음이면 null
7665
+ * @returns 선 끝 모양. 설정이 없거나 대상 도형이 없으면 null
7589
7666
  */
7590
7667
  getLineCap(): Promise<LineCap | null>;
7591
7668
  /**
7592
7669
  * 선 연결 유형(join)을 반환한다. (setLineJoin 대칭)
7593
7670
  *
7594
- * @returns 선 연결(모서리) 유형. 없음/모델 없음이면 null
7671
+ * @returns 선 연결(모서리) 유형. 설정이 없거나 대상 도형이 없으면 null
7595
7672
  */
7596
7673
  getLineJoin(): Promise<LineJoin | null>;
7597
7674
  /**
7598
7675
  * 도형에 적용된 효과를 반환한다. 적용된 효과만 키로 포함된다.
7599
- * 각 값은 대응 setter(setOuterShadow/setInnerShadow/setGlow/setSoftEdge/setReflection/set3d) 인자와 대칭.
7600
- * 모델 UI obj 를 경유하므로 길이(pt)·비율(%)은 소수 첫째 자리까지만 정확하다 — 그보다 작은 차이는
7601
- * 왕복에서 반올림된다(렌더에는 나타나지 않는 수준).
7676
+ * 각 값은 대응 setter(setOuterShadow/setInnerShadow/setGlow/setSoftEdge/setReflection/set3d) 의 인자와 같은 형태다.
7677
+ * 그림자·네온의 alpha 는 불투명(0)이어도 항상 포함되고, 길이(pt)·비율(%)은 소수 첫째 자리로 반올림된다.
7678
+ * outerShadow·innerShadow 가 함께 실린 문서면 둘 다 담는다 (setter 로는 하나만 넣을 수 있다).
7602
7679
  *
7603
- * @returns 효과 정보. 적용된 효과가 없으면 빈 객체 `{}`, 모델 없음(협업 삭제 등)이면 null
7680
+ * @returns 효과 정보. 적용된 효과가 없으면 빈 객체 `{}`, 대상 도형이 없으면(협업 중 삭제 등) null
7604
7681
  */
7605
7682
  getEffects(): Promise<Effects | null>;
7606
7683
  /**
7607
7684
  * 도형 채우기를 단색으로 설정한다.
7608
7685
  *
7609
7686
  * @param color - hex (#RRGGBB) 또는 scheme color
7610
- * @param alpha - 투명도 (0~100) (기본값: 0(불투명))
7687
+ * @param alpha - 투명도 (0~100, 0=불투명). 소수점 셋째 자리까지 저장된다 (기본값: 기존 값 유지)
7611
7688
  */
7612
7689
  setSolidFill(color: string, alpha?: number): Promise<void>;
7613
7690
  /**
@@ -7628,9 +7705,9 @@ declare namespace Show {
7628
7705
  *
7629
7706
  * @param imageUrl - 이미지 URL
7630
7707
  * @param fillMode - 이미지 채우기 방식 (기본값: ImageFillMode.STRETCH)
7631
- * @param alpha - 투명도 (0~100) (기본값: 0(불투명))
7708
+ * @param alpha - 투명도 (0~100, 0=불투명) (기본값: 0)
7632
7709
  * @param detail - 세부 옵션. offset/scale/mirror/align 은 fillMode=ImageFillMode.TILE 일 때만 반영 (기본값: {})
7633
- * @returns 이미지 업로드 후 채우기 적용이 끝나면 resolve
7710
+ * @returns 이미지 업로드 후 채우기 적용이 끝나면 resolve. 대상 도형이 없으면(업로드 중 삭제 포함) SHAPE_NOT_FOUND 로 reject
7634
7711
  * @example shape.setImageFill(url, ImageFillMode.TILE, 0, { scale: { x: 50, y: 50 }, mirror: "x", align: "tl", rotateWithShape: true });
7635
7712
  */
7636
7713
  setImageFill(imageUrl: string, fillMode?: ImageFillMode, alpha?: number, detail?: ImageFillDetail): Promise<void>;
@@ -7639,28 +7716,29 @@ declare namespace Show {
7639
7716
  */
7640
7717
  removeFill(): Promise<void>;
7641
7718
  /**
7642
- * 패턴(무늬) 채우기를 설정한다. (getFill 왕복 대칭 — setFill 의 pattern 경로)
7719
+ * 패턴(무늬) 채우기를 설정한다. (getFill 왕복 대칭)
7643
7720
  *
7644
7721
  * @param preset - 무늬 프리셋 (apiConstants.PatternPreset)
7645
- * @param foreColor - 전경색 hex (#RRGGBB) 또는 scheme color (기본값: accent1(테마 강조색1))
7646
- * @param backColor - 배경색 hex (#RRGGBB) 또는 scheme color (기본값: bg1(테마 배경색1))
7647
- * @param foreAlpha - 전경색 투명도 (0~100) (기본값: 0(불투명))
7648
- * @param backAlpha - 배경색 투명도 (0~100) (기본값: 0(불투명))
7722
+ * @param foreColor - 전경색 hex (#RRGGBB) 또는 scheme color (기본은 테마 강조색1) (기본값: "accent1")
7723
+ * @param backColor - 배경색 hex (#RRGGBB) 또는 scheme color (기본은 테마 배경색1) (기본값: "bg1")
7724
+ * @param foreAlpha - 전경색 투명도 (0~100, 0=불투명) (기본값: 0)
7725
+ * @param backAlpha - 배경색 투명도 (0~100, 0=불투명) (기본값: 0)
7649
7726
  */
7650
7727
  setPatternFill(preset: PatternPreset, foreColor?: string, backColor?: string, foreAlpha?: number, backAlpha?: number): Promise<void>;
7651
7728
  /**
7652
7729
  * getFill() 이 반환한 채우기 객체를 그대로 적용한다. (getFill 대칭 — 도형→도형 채우기 복사)
7653
- * type 으로 분기해 대응 setter 를 호출한다. image 는 readback 의 embed 를 재사용해 같은 문서 안에서 복원한다.
7654
- * embed 가 없는 image 입력은 무시된다(새 이미지는 개별 setImageFill 사용).
7730
+ * image 는 조회 결과의 embed 를 재사용하므로 같은 문서 안에서만 복원된다.
7731
+ * embed 없는 image 는 적용할 그림이 없어 거부한다 (새 이미지는 setImageFill).
7655
7732
  *
7656
- * @param fill - getFill() 반환값
7733
+ * @param fill - getFill() 반환값. 생략하면 아무것도 변경하지 않는다
7734
+ * @throws {Error} image 인데 embed 가 없는 경우 (error.code = "INVALID_ARGUMENT")
7657
7735
  */
7658
- setFill(fill: Fill): Promise<void>;
7736
+ setFill(fill?: Fill): Promise<void>;
7659
7737
  /**
7660
7738
  * 선 색상을 설정한다.
7661
7739
  *
7662
7740
  * @param color - hex (#RRGGBB) 또는 scheme color
7663
- * @param alpha - 투명도 (0~100, UI 단위) (기본값: 0(불투명))
7741
+ * @param alpha - 투명도 (0~100, 0=불투명). 소수점 셋째 자리까지 저장된다 (기본값: 기존 값 유지)
7664
7742
  */
7665
7743
  setLineColor(color: string, alpha?: number): Promise<void>;
7666
7744
  /**
@@ -7707,130 +7785,59 @@ declare namespace Show {
7707
7785
  /**
7708
7786
  * getLineStyle() 이 반환한 선 스타일 객체를 그대로 적용한다. (getLineStyle 대칭 — 도형→도형 선 복사)
7709
7787
  *
7710
- * @param style - getLineStyle() 반환값 (basePathShape.LineStyle)
7788
+ * @param style - getLineStyle() 반환값. 생략하면 아무것도 변경하지 않는다
7711
7789
  */
7712
- setLineStyle(style: LineStyle): Promise<void>;
7790
+ setLineStyle(style?: LineStyle): Promise<void>;
7713
7791
  /**
7714
- * 외부 그림자를 적용한다.
7792
+ * 외부 그림자를 적용한다. (getEffects().outerShadow 대칭 - 반환 객체를 그대로 넘길 수 있다)
7793
+ * 생략한 필드는 기본값으로 채운다 (필드별 기본값은 OuterShadow 참조).
7794
+ * 도형이 갖는 그림자는 하나다 - 내부 그림자가 걸려 있으면 외부 그림자로 바뀐다.
7715
7795
  *
7716
- * @param shadow - 그림자 설정 (기본값: 전체 기본값)
7717
- * @param shadow.color - hex 또는 scheme color (기본값: "#000000")
7718
- * @param shadow.alpha - 투명도 (0~100, UI 단위) (기본값: 50)
7719
- * @param shadow.blur - 흐림 반경 (pt) (기본값: 8)
7720
- * @param shadow.dist - 거리 (pt) (기본값: 8)
7721
- * @param shadow.dir - 방향 (degree) (기본값: 90)
7722
- * @param shadow.sx - 가로 배율 (%) (기본값: 100)
7723
- * @param shadow.sy - 세로 배율 (%) (기본값: 100)
7724
- * @param shadow.kx - 가로 기울임 (degree) (기본값: 0)
7725
- * @param shadow.ky - 세로 기울임 (degree) (기본값: 0)
7726
- * @param shadow.algn - 정렬 기준 (기본값: RectAlign.CENTER)
7727
- * @param shadow.rotWithShape - 도형 회전 연동 (기본값: false)
7796
+ * @param shadow - 그림자 설정
7728
7797
  */
7729
- setOuterShadow(shadow?: {
7730
- color?: string;
7731
- alpha?: number;
7732
- blur?: number;
7733
- dist?: number;
7734
- dir?: number;
7735
- sx?: number;
7736
- sy?: number;
7737
- kx?: number;
7738
- ky?: number;
7739
- algn?: RectAlign;
7740
- rotWithShape?: boolean;
7741
- }): Promise<void>;
7798
+ setOuterShadow(shadow?: OuterShadow): Promise<void>;
7742
7799
  /**
7743
- * 내부 그림자를 적용한다.
7800
+ * 내부 그림자를 적용한다. (getEffects().innerShadow 대칭 - 반환 객체를 그대로 넘길 수 있다)
7801
+ * 생략한 필드는 기본값으로 채운다 (필드별 기본값은 InnerShadow 참조).
7802
+ * 도형이 갖는 그림자는 하나다 - 외부 그림자가 걸려 있으면 내부 그림자로 바뀐다.
7744
7803
  *
7745
- * @param shadow - 그림자 설정 (기본값: 전체 기본값)
7746
- * @param shadow.color - hex 또는 scheme color (기본값: "#000000")
7747
- * @param shadow.alpha - 투명도 (0~100, UI 단위) (기본값: 50)
7748
- * @param shadow.blur - 흐림 반경 (pt) (기본값: 8)
7749
- * @param shadow.dist - 거리 (pt) (기본값: 8)
7750
- * @param shadow.dir - 방향 (degree) (기본값: 90)
7804
+ * @param shadow - 그림자 설정
7751
7805
  */
7752
- setInnerShadow(shadow?: {
7753
- color?: string;
7754
- alpha?: number;
7755
- blur?: number;
7756
- dist?: number;
7757
- dir?: number;
7758
- }): Promise<void>;
7806
+ setInnerShadow(shadow?: InnerShadow): Promise<void>;
7759
7807
  /**
7760
- * 네온(광선) 효과를 적용한다.
7808
+ * 네온(광선) 효과를 적용한다. (getEffects().glow 대칭 - 반환 객체를 그대로 넘길 수 있다)
7809
+ * 생략한 필드는 기본값으로 채운다 (필드별 기본값은 Glow 참조).
7761
7810
  *
7762
- * @param glow - 네온(광선) 설정 (기본값: 전체 기본값)
7763
- * @param glow.color - hex 또는 scheme color (기본값: "#356FFF")
7764
- * @param glow.alpha - 투명도 (0~100, UI 단위) (기본값: 50)
7765
- * @param glow.rad - 광선 반경 (pt) (기본값: 10)
7811
+ * @param glow - 네온(광선) 설정
7766
7812
  */
7767
- setGlow(glow?: {
7768
- color?: string;
7769
- alpha?: number;
7770
- rad?: number;
7771
- }): Promise<void>;
7813
+ setGlow(glow?: Glow): Promise<void>;
7772
7814
  /**
7773
- * 옅은 테두리(softEdge) 효과를 적용한다.
7815
+ * 옅은 테두리(softEdge) 효과를 적용한다. (getEffects().softEdge 대칭 - 반환 객체를 그대로 넘길 수 있다)
7816
+ * 생략한 필드는 기본값으로 채운다 (필드별 기본값은 SoftEdge 참조).
7774
7817
  *
7775
- * @param softEdge - 옅은 테두리 설정 (기본값: 전체 기본값)
7776
- * @param softEdge.rad - 반경 (pt) (기본값: 5)
7818
+ * @param softEdge - 옅은 테두리 설정
7777
7819
  */
7778
- setSoftEdge(softEdge?: {
7779
- rad?: number;
7780
- }): Promise<void>;
7820
+ setSoftEdge(softEdge?: SoftEdge): Promise<void>;
7781
7821
  /**
7782
- * 반사 효과를 적용한다.
7783
- *
7784
- * @param reflection - 반사 설정 (기본값: 전체 기본값)
7785
- * @param reflection.blur - 흐림 반경 (pt) (기본값: 0.5)
7786
- * @param reflection.dist - 거리 (pt) (기본값: 8)
7787
- * @param reflection.stPos - 시작 위치 (0~100). 웹쇼 렌더는 시작 위치를 쓰지 않는다. (기본값: 0)
7788
- * @param reflection.endPos - 반사 크기 (0~100) (기본값: 50)
7789
- * @param reflection.startAlpha - 시작 투명도 (0~100, UI 단위) (기본값: 50)
7790
- * @param reflection.endAlpha - 끝 투명도 (0~100, UI 단위) (기본값: 99.7)
7791
- * @param reflection.dir - 방향 (degree). 반사 렌더는 방향을 쓰지 않는다. (기본값: 90)
7792
- * @param reflection.fadeDir - 페이드 방향 (degree). 웹쇼 렌더는 페이드 방향을 쓰지 않는다. (기본값: 90)
7793
- * @param reflection.sx - 가로 배율 (%) (기본값: 100)
7794
- * @param reflection.sy - 세로 배율 (%) (기본값: -100)
7795
- * @param reflection.kx - 가로 기울임 (degree) (기본값: 0)
7796
- * @param reflection.ky - 세로 기울임 (degree) (기본값: 0)
7797
- * @param reflection.algn - 정렬 기준 (기본값: RectAlign.BOTTOM_LEFT)
7798
- * @param reflection.rotWithShape - 도형 회전 연동 (기본값: false)
7799
- */
7800
- setReflection(reflection?: {
7801
- blur?: number;
7802
- dist?: number;
7803
- stPos?: number;
7804
- endPos?: number;
7805
- startAlpha?: number;
7806
- endAlpha?: number;
7807
- dir?: number;
7808
- fadeDir?: number;
7809
- sx?: number;
7810
- sy?: number;
7811
- kx?: number;
7812
- ky?: number;
7813
- algn?: RectAlign;
7814
- rotWithShape?: boolean;
7815
- }): Promise<void>;
7816
- /**
7817
- * 효과를 제거한다.
7822
+ * 반사 효과를 적용한다. (getEffects().reflection 대칭 - 반환 객체를 그대로 넘길 수 있다)
7823
+ * 생략한 필드는 기본값으로 채운다 (필드별 기본값은 Reflection 참조).
7818
7824
  *
7819
- * @param effectType - 제거할 효과 타입
7825
+ * @param reflection - 반사 설정
7820
7826
  */
7821
- removeEffect(effectType: EffectType): Promise<void>;
7827
+ setReflection(reflection?: Reflection): Promise<void>;
7822
7828
  /**
7823
- * 도형에 효과(그림자/광선/반사 등)를 직접 obj로 적용한다.
7824
- * 단순 케이스는 setOuterShadow/setInnerShadow/setGlow/setSoftEdge/setReflection 사용 권장.
7829
+ * 효과를 제거한다. 그 효과가 걸려 있지 않으면 아무 일도 하지 않는다.
7830
+ * 도형이 직접 가진 효과만 제거한다 - 도형 스타일(effectRef)에서 상속받은 효과는 제거할 수 없어,
7831
+ * getEffects() 가 돌려주는데도 아무 일도 하지 않는 경우가 있다.
7825
7832
  *
7826
- * @param effect - 적용할 효과 설정
7833
+ * @param effectType - 제거할 효과 타입
7827
7834
  */
7828
- setEffect(effect: Effect): Promise<void>;
7835
+ removeEffect(effectType: EffectType): Promise<void>;
7829
7836
  /**
7830
- * 도형에 3D 효과를 적용한다. scene3d 또는 sp3d 중 비어있는 인자는 적용하지 않는다.
7837
+ * 도형에 3D 효과를 적용한다. scene3d 와 sp3d 중 비어 있는 인자는 적용하지 않는다.
7831
7838
  *
7832
- * @param scene3d - 카메라(회전) 설정 (기본값: 미적용)
7833
- * @param sp3d - 입체(깊이) 설정 (기본값: 미적용)
7839
+ * @param scene3d - 카메라(회전) 설정. 생략하면 적용하지 않음
7840
+ * @param sp3d - 입체(깊이) 설정. 생략하면 적용하지 않음
7834
7841
  */
7835
7842
  set3d(scene3d?: Scene3d, sp3d?: Sp3d): Promise<void>;
7836
7843
  /**
@@ -7840,10 +7847,12 @@ declare namespace Show {
7840
7847
  /**
7841
7848
  * getEffects() 가 반환한 효과 객체를 그대로 적용한다. (getEffects 대칭 — 도형→도형 효과 복사)
7842
7849
  * 포함된 효과 키만 대응 setter 로 적용한다. scene3d/sp3d 는 set3d 로 함께 넘긴다.
7850
+ * 대상의 기존 효과를 지우지는 않는다 - 완전 복사하려면 removeEffect/remove3d 로 먼저 제거한 뒤 적용한다.
7851
+ * outerShadow 와 innerShadow 를 함께 넘기면 거부하지 않고 순서대로 적용해 나중 것만 남는다.
7843
7852
  *
7844
- * @param effects - getEffects() 반환값 (basePathShape.Effects)
7853
+ * @param effects - getEffects() 반환값. 생략하면 아무것도 변경하지 않는다
7845
7854
  */
7846
- setEffects(effects: Effects): Promise<void>;
7855
+ setEffects(effects?: Effects): Promise<void>;
7847
7856
  }
7848
7857
  /** 일반 도형과 텍스트 상자를 다루는 핸들로, 텍스트 조회·편집(getText/setText/insertText 등), 글자 서식(setFontStyle/setBold/setFontSize 등), 문단 서식(setAlignH/setLineSpacing/setBulletStyle 등), 텍스트 상자 옵션(setAlignV/setTextboxAutoFit), 도형 모양 조절값(getAdjustValues/setAdjustValue 등)을 제공한다. */
7849
7858
  export interface Shape extends BasePathShape {
@@ -7855,176 +7864,168 @@ declare namespace Show {
7855
7864
  readonly [__proxyBrand]?: 'Shape';
7856
7865
  /**
7857
7866
  * 대표 단락(range 가 걸친 첫 단락)의 단락 서식을 반환한다. (setParagraphStyle 대칭)
7858
- * 반환 객체를 그대로 다른 개체의 setParagraphStyle 에 넘길 수 있다. 값이 없는 속성은 키를 생략한다.
7859
- * 값은 레이아웃/마스터 상속이 반영된 해석값이다. 단락이 직접 지정한 값만 골라낼 수는 없다.
7860
- * 같은 단락에 그대로 되돌려주면 상속값과 같은 속성은 오버라이드로 굳지 않고 지워진다. (updateTextPPr 동작)
7861
- * 목록 수준은 서식 값이 아니라 상속 프리셋이라 이 객체에 담지 않는다. (getLevel 대칭)
7867
+ * 반환 객체를 그대로 다른 개체의 setParagraphStyle 에 넘길 수 있다. 값이 없는 속성은 키를 담지 않는다.
7868
+ * 값은 레이아웃/마스터 상속까지 반영해 실제 적용된 값이라 단락이 직접 지정한 값만 골라낼 수는 없고,
7869
+ * 같은 단락에 그대로 다시 넘기면 상속값과 같은 속성은 직접 지정으로 남지 않는다.
7870
+ * 목록 수준은 서식 값이 아니라 상속 프리셋이라 담지 않는다. (getLevel 대칭)
7862
7871
  *
7863
7872
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7864
- * @returns 단락 서식 (baseText.ParagraphStyle). 텍스트/단락 없으면 null
7873
+ * @returns 단락 서식. 텍스트/단락 없으면 null
7865
7874
  */
7866
- getParagraphStyle(range?: {
7867
- from: number;
7868
- to: number;
7869
- }): Promise<ParagraphStyle | null>;
7875
+ getParagraphStyle(range?: TextRange): Promise<ParagraphStyle | null>;
7870
7876
  /**
7871
7877
  * 대표 단락의 가로 정렬을 반환한다. (setAlignH 대칭)
7872
7878
  *
7873
7879
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7874
7880
  * @returns 가로 정렬. 텍스트/단락 없으면 null
7875
7881
  */
7876
- getAlignH(range?: {
7877
- from: number;
7878
- to: number;
7879
- }): Promise<TextAlignH | null>;
7882
+ getAlignH(range?: TextRange): Promise<TextAlignH | null>;
7880
7883
  /**
7881
7884
  * 대표 단락의 줄 간격 값을 반환한다. (setLineSpacing 대칭)
7882
7885
  *
7883
7886
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7884
7887
  * @returns 줄 간격 값 (MULTIPLE: 배수%, EXACT: pt). 텍스트/단락 없으면 null
7885
7888
  */
7886
- getLineSpacing(range?: {
7887
- from: number;
7888
- to: number;
7889
- }): Promise<number | null>;
7889
+ getLineSpacing(range?: TextRange): Promise<number | null>;
7890
7890
  /**
7891
7891
  * 대표 단락의 줄 간격 유형을 반환한다. (setLineSpacing 의 type 대칭)
7892
7892
  *
7893
7893
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7894
7894
  * @returns 줄 간격 유형. 텍스트/단락 없으면 null
7895
7895
  */
7896
- getLineSpacingType(range?: {
7897
- from: number;
7898
- to: number;
7899
- }): Promise<LineSpacingType | null>;
7896
+ getLineSpacingType(range?: TextRange): Promise<LineSpacingType | null>;
7900
7897
  /**
7901
7898
  * 대표 단락의 단락 앞 간격(UI "문단 위")을 반환한다. (setSpaceBefore 대칭)
7902
7899
  *
7903
7900
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7904
7901
  * @returns 단락 앞 간격 (pt). 배수(%) 저장/텍스트 없음이면 null
7905
7902
  */
7906
- getSpaceBefore(range?: {
7907
- from: number;
7908
- to: number;
7909
- }): Promise<number | null>;
7903
+ getSpaceBefore(range?: TextRange): Promise<number | null>;
7910
7904
  /**
7911
7905
  * 대표 단락의 단락 뒤 간격(UI "문단 아래")을 반환한다. (setSpaceAfter 대칭)
7912
7906
  *
7913
7907
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7914
7908
  * @returns 단락 뒤 간격 (pt). 배수(%) 저장/텍스트 없음이면 null
7915
7909
  */
7916
- getSpaceAfter(range?: {
7917
- from: number;
7918
- to: number;
7919
- }): Promise<number | null>;
7910
+ getSpaceAfter(range?: TextRange): Promise<number | null>;
7920
7911
  /**
7921
7912
  * 대표 단락의 왼쪽 여백(UI "텍스트 앞")을 반환한다. (setMarginLeft 대칭)
7922
7913
  *
7923
7914
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7924
7915
  * @returns 왼쪽 여백 (pt). 텍스트/단락 없으면 null
7925
7916
  */
7926
- getMarginLeft(range?: {
7927
- from: number;
7928
- to: number;
7929
- }): Promise<number | null>;
7917
+ getMarginLeft(range?: TextRange): Promise<number | null>;
7930
7918
  /**
7931
7919
  * 대표 단락의 첫 줄 들여쓰기(UI "첫 줄")를 반환한다. (setFirstLineIndent 대칭)
7932
7920
  *
7933
7921
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7934
7922
  * @returns 첫 줄 들여쓰기 (pt, 음수는 내어쓰기). 텍스트/단락 없으면 null
7935
7923
  */
7936
- getFirstLineIndent(range?: {
7937
- from: number;
7938
- to: number;
7939
- }): Promise<number | null>;
7924
+ getFirstLineIndent(range?: TextRange): Promise<number | null>;
7940
7925
  /**
7941
7926
  * 대표 단락의 목록 수준을 반환한다. (setLevel 대칭)
7942
7927
  *
7943
7928
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7944
7929
  * @returns 목록 수준 (1~9). 텍스트/단락 없으면 null
7945
7930
  */
7946
- getLevel(range?: {
7947
- from: number;
7948
- to: number;
7949
- }): Promise<number | null>;
7931
+ getLevel(range?: TextRange): Promise<number | null>;
7950
7932
  /**
7951
- * 텍스트를 plain text로 반환한다.
7933
+ * 대표 단락의 글머리 기호 스타일을 반환한다. 반환 필드를 풀어서 setBulletStyle(type, subType, startAt) 에 넘길 수 있다.
7934
+ * 값은 레이아웃/마스터 상속까지 반영해 실제 적용된 값이고, 없는 값(시작 번호)과 되넘길 수 없는 값(프리셋 밖 번호 유형)은 키를 담지 않는다.
7935
+ * 그림 글머리·프리셋 밖 문자는 조회 전용이라 그대로는 적용되지 않는다. (제약은 setBulletStyle 참조)
7952
7936
  *
7953
7937
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7938
+ * @returns 글머리 기호 스타일. 텍스트/단락 없으면 null
7939
+ */
7940
+ getBulletStyle(range?: TextRange): Promise<BulletStyle | null>;
7941
+ /**
7942
+ * 텍스트를 plain text로 반환한다. 문단 사이의 개행은 그대로 들어가지만,
7943
+ * 마지막 문단을 끝맺는 개행은 글자가 아니라 담지 않는다 (빈 텍스트는 "").
7944
+ *
7945
+ * @param range - 읽을 텍스트 구간 (UTF-16 코드 단위 offset) (기본값: 전체 텍스트)
7954
7946
  * @returns 해당 구간의 텍스트 (plain text). 텍스트 모델이 없거나 빈 구간이면 ""
7955
7947
  */
7956
- getText(range?: {
7957
- from: number;
7958
- to: number;
7959
- }): Promise<string>;
7948
+ getText(range?: TextRange): Promise<string>;
7960
7949
  /**
7961
- * 대표 run(첫 run)의 글꼴 스타일을 반환한다. (setFontStyle 대칭)
7962
- * 반환 객체를 그대로 다른 개체의 setFontStyle 에 넘길 수 있다. 값이 없는 속성은 키를 생략한다.
7950
+ * 대표 run(range 가 걸친 첫 run)의 글꼴 스타일을 반환한다. (setFontStyle 대칭)
7951
+ * 반환 객체를 그대로 다른 개체의 setFontStyle 에 넘길 수 있다. 값이 없는 속성은 키를 담지 않는다.
7952
+ * 값은 레이아웃/마스터/표 스타일 상속까지 반영해 실제 적용된 값이라 run 이 직접 지정한 값만 골라낼 수는 없다.
7963
7953
  *
7964
- * @returns 글꼴 스타일 (baseText.FontStyle). 런/스타일 없으면 빈 객체 `{}`, 텍스트 모델 없음(협업 삭제 등)이면 null
7954
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7955
+ * @returns 글꼴 스타일. run/스타일 없으면 빈 객체 `{}`, 대상 텍스트가 없거나(협업 중 삭제 등) 유효하지 않은 구간이면 null
7965
7956
  */
7966
- getFontStyle(): Promise<FontStyle | null>;
7957
+ getFontStyle(range?: TextRange): Promise<FontStyle | null>;
7967
7958
  /**
7968
- * 대표 run 의 굵게 여부를 반환한다. (setBold 대칭)
7959
+ * 대표 run 의 굵게 여부를 반환한다. (setBold 대칭 — 상속까지 반영된 실제 적용값)
7969
7960
  *
7970
- * @returns 굵게 여부. 명시 안 됨(상속)/텍스트 없음이면 null
7961
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7962
+ * @returns 굵게 여부. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
7971
7963
  */
7972
- getBold(): Promise<boolean | null>;
7964
+ getBold(range?: TextRange): Promise<boolean | null>;
7973
7965
  /**
7974
- * 대표 run 의 기울임 여부를 반환한다. (setItalic 대칭)
7966
+ * 대표 run 의 기울임 여부를 반환한다. (setItalic 대칭 — 상속까지 반영된 실제 적용값)
7975
7967
  *
7976
- * @returns 기울임 여부. 명시 안 됨/텍스트 없음이면 null
7968
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7969
+ * @returns 기울임 여부. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
7977
7970
  */
7978
- getItalic(): Promise<boolean | null>;
7971
+ getItalic(range?: TextRange): Promise<boolean | null>;
7979
7972
  /**
7980
- * 대표 run 의 밑줄 유형을 반환한다. (setUnderline 대칭)
7973
+ * 대표 run 의 밑줄 유형을 반환한다. (setUnderline 대칭 — 상속까지 반영된 실제 적용값)
7981
7974
  *
7982
- * @returns 밑줄 유형. 명시 안 됨/텍스트 없음이면 null
7975
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7976
+ * @returns 밑줄 유형. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
7983
7977
  */
7984
- getUnderline(): Promise<Underline | null>;
7978
+ getUnderline(range?: TextRange): Promise<Underline | null>;
7985
7979
  /**
7986
- * 대표 run 의 취소선 유형을 반환한다. (setStrike 대칭)
7980
+ * 대표 run 의 취소선 유형을 반환한다. (setStrike 대칭 — 상속까지 반영된 실제 적용값)
7987
7981
  *
7988
- * @returns 취소선 유형. 명시 안 됨/텍스트 없음이면 null
7982
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7983
+ * @returns 취소선 유형. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
7989
7984
  */
7990
- getStrike(): Promise<Strike | null>;
7985
+ getStrike(range?: TextRange): Promise<Strike | null>;
7991
7986
  /**
7992
- * 대표 run 의 글자 크기(pt)를 반환한다. (setFontSize 대칭)
7987
+ * 대표 run 의 글자 크기(pt)를 반환한다. (setFontSize 대칭 — 상속까지 반영된 실제 적용값)
7993
7988
  *
7994
- * @returns 글자 크기 (pt). 명시 안 됨/텍스트 없음이면 null
7989
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7990
+ * @returns 글자 크기 (pt). 대상 텍스트가 없거나 유효하지 않은 구간이면 null
7995
7991
  */
7996
- getFontSize(): Promise<number | null>;
7992
+ getFontSize(range?: TextRange): Promise<number | null>;
7997
7993
  /**
7998
- * 대표 run 의 글꼴 이름을 반환한다. (setFontFamily 대칭)
7994
+ * 대표 run 의 글꼴 이름을 반환한다. (setFontFamily 대칭 — 상속까지 반영된 실제 적용값)
7999
7995
  *
8000
- * @returns 글꼴 이름. 명시 안 됨/텍스트 없음이면 null
7996
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
7997
+ * @returns 글꼴 이름. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
8001
7998
  */
8002
- getFontFamily(): Promise<string | null>;
7999
+ getFontFamily(range?: TextRange): Promise<string | null>;
8003
8000
  /**
8004
- * 대표 run 의 글자 색상을 반환한다. (setTextColor 대칭)
8001
+ * 대표 run 의 글자 색상을 반환한다. (setTextColor 대칭 — 상속까지 반영된 실제 적용값)
8005
8002
  *
8006
- * @returns 글자 색상 (hex "#RRGGBB"/scheme). solid 아님/명시 안 됨/텍스트 없음이면 null
8003
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8004
+ * @returns 글자 색상 (hex "#RRGGBB" — scheme color 도 hex 로 풀려서 나온다). solid 채우기가 아니거나 대상 텍스트가 없거나 유효하지 않은 구간이면 null
8007
8005
  */
8008
- getTextColor(): Promise<string | null>;
8006
+ getTextColor(range?: TextRange): Promise<string | null>;
8009
8007
  /**
8010
- * 텍스트 구간의 하이퍼링크를 반환한다. (setTextHyperlink 대칭 —
8011
- * 반환 객체를 그대로 넘겨 하이퍼링크를 복사할 수 있다)
8012
- * range 를 주면 그 구간의 첫 글자, 없으면 텍스트 첫 글자가 속한 run 기준이다.
8008
+ * 텍스트 구간의 하이퍼링크를 반환한다. (setTextHyperlink 대칭 — 반환 객체를 그대로 넘겨 복사할 수 있다)
8009
+ * range 를 주면 그 구간의 첫 글자, range 가 없으면 텍스트의 첫 글자가 속한 run 을 기준으로 한다.
8013
8010
  * 도형 자체에 걸린 하이퍼링크는 getHyperlink 로 읽는다.
8014
8011
  *
8015
8012
  * @param range - 조회할 텍스트 구간 (기본값: 텍스트 첫 글자)
8016
- * @returns 하이퍼링크 정보 (baseShape 의 Hyperlink). 링크 없음/텍스트 없음/미노출 action 이면 null
8013
+ * @returns 하이퍼링크 정보 (getHyperlink 와 같은 Hyperlink 객체). 링크 없음/텍스트 없음/미노출 action 이면 null
8017
8014
  */
8018
- getTextHyperlink(range?: {
8019
- from: number;
8020
- to: number;
8021
- }): Promise<Hyperlink | null>;
8015
+ getTextHyperlink(range?: TextRange): Promise<Hyperlink | null>;
8022
8016
  /**
8023
8017
  * 텍스트 상자 자동 맞춤 유형을 반환한다. (setTextboxAutoFit 대칭)
8024
8018
  *
8025
- * @returns 자동 맞춤 유형. 텍스트 모델 없으면 null
8019
+ * @returns 자동 맞춤 유형. 대상 텍스트가 없으면 null
8026
8020
  */
8027
8021
  getTextboxAutoFit(): Promise<AutoFitType | null>;
8022
+ /**
8023
+ * 텍스트 세로 정렬을 반환한다. (setAlignV 대칭)
8024
+ * TextAlignV 는 TOP 이 0 인 숫자 enum 이라, 값이 있는지는 truthy 검사가 아니라 null 비교로 본다.
8025
+ *
8026
+ * @returns 세로 정렬. 대상 텍스트가 없으면 null
8027
+ */
8028
+ getAlignV(): Promise<TextAlignV | null>;
8028
8029
  /**
8029
8030
  * 텍스트를 설정한다. 인자 조합에 따라 다음과 같이 동작한다.
8030
8031
  * - range 없음: 전체 텍스트를 text 로 교체
@@ -8032,17 +8033,14 @@ declare namespace Show {
8032
8033
  * - text 가 빈 문자열("")이면 교체 대신 해당 범위를 삭제
8033
8034
  *
8034
8035
  * 삭제 없이 끼워넣는 삽입은 insertText 를 사용한다.
8035
- * (단, from이 텍스트 끝(마지막 글자 다음 위치)이면 지울 글자가 없어 끝 삽입으로 동작한다)
8036
+ * (단, from 이 텍스트 끝이면 지울 글자가 없어 끝 삽입으로 동작).
8036
8037
  *
8037
- * 대체된 자리의 글자 서식은 구간 시작 위치의 런 서식을, 문단 서식은 기존 문단의 서식을 따른다.
8038
+ * 대체된 자리의 글자 서식은 구간 시작 위치의 글자 서식을, 문단 서식은 기존 문단의 서식을 따른다.
8038
8039
  *
8039
8040
  * @param text - 설정할 텍스트. 빈 문자열("")이면 삭제로 동작
8040
- * @param range - 교체할 텍스트 구간 to = from + 글자수 - 1 (0-based) 예: "가나다" 전체 = {from: 0, to: 2}, "가나다" 중 "가" = {from: 0, to: 0} (기본값: 전체 텍스트)
8041
+ * @param range - 교체할 텍스트 구간 to = from + 글자수 - 1 (0-based) 예: "가나다" 전체 = {from: 0, to: 2}, "가나다" 중 "가" = {from: 0, to: 0} offset 은 UTF-16 코드 단위라 서로게이트 페어를 가르는 range 는 반쪽이 아니라 그 글자 전체가 대상이 된다 (range 를 받는 서식 setter 도 같다) (기본값: 전체 텍스트)
8041
8042
  */
8042
- setText(text: string, range?: {
8043
- from: number;
8044
- to: number;
8045
- }): Promise<void>;
8043
+ setText(text: string, range?: TextRange): Promise<void>;
8046
8044
  /**
8047
8045
  * 텍스트를 삽입한다.
8048
8046
  * 삽입한 글자의 서식은 삽입 지점 바로 앞 글자의 런 서식을 따른다.
@@ -8057,101 +8055,71 @@ declare namespace Show {
8057
8055
  * @param style - 글꼴 스타일 설정
8058
8056
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8059
8057
  */
8060
- setFontStyle(style: FontStyle, range?: {
8061
- from: number;
8062
- to: number;
8063
- }): Promise<void>;
8058
+ setFontStyle(style: FontStyle, range?: TextRange): Promise<void>;
8064
8059
  /**
8065
- * 글자 굵게 설정.
8060
+ * 글자를 굵게 설정한다.
8066
8061
  *
8067
8062
  * @param enabled - true: 굵게, false: 해제
8068
8063
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8069
8064
  */
8070
- setBold(enabled: boolean, range?: {
8071
- from: number;
8072
- to: number;
8073
- }): Promise<void>;
8065
+ setBold(enabled: boolean, range?: TextRange): Promise<void>;
8074
8066
  /**
8075
- * 글자 기울임 설정.
8067
+ * 글자 기울임을 설정한다.
8076
8068
  *
8077
8069
  * @param enabled - true: 기울임, false: 해제
8078
8070
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8079
8071
  */
8080
- setItalic(enabled: boolean, range?: {
8081
- from: number;
8082
- to: number;
8083
- }): Promise<void>;
8072
+ setItalic(enabled: boolean, range?: TextRange): Promise<void>;
8084
8073
  /**
8085
- * 글자 밑줄 설정.
8074
+ * 글자 밑줄을 설정한다.
8086
8075
  *
8087
8076
  * @param underline - 밑줄 유형
8088
8077
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8089
8078
  */
8090
- setUnderline(underline: Underline, range?: {
8091
- from: number;
8092
- to: number;
8093
- }): Promise<void>;
8079
+ setUnderline(underline: Underline, range?: TextRange): Promise<void>;
8094
8080
  /**
8095
- * 글자 취소선 설정.
8081
+ * 글자 취소선을 설정한다.
8096
8082
  *
8097
8083
  * @param strike - 취소선 유형
8098
8084
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8099
8085
  */
8100
- setStrike(strike: Strike, range?: {
8101
- from: number;
8102
- to: number;
8103
- }): Promise<void>;
8086
+ setStrike(strike: Strike, range?: TextRange): Promise<void>;
8104
8087
  /**
8105
- * 글자 크기 설정.
8088
+ * 글자 크기를 설정한다.
8106
8089
  *
8107
8090
  * @param fontSize - pt 단위
8108
8091
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8109
8092
  */
8110
- setFontSize(fontSize: number, range?: {
8111
- from: number;
8112
- to: number;
8113
- }): Promise<void>;
8093
+ setFontSize(fontSize: number, range?: TextRange): Promise<void>;
8114
8094
  /**
8115
- * 글꼴 설정.
8095
+ * 글꼴을 설정한다.
8116
8096
  *
8117
8097
  * @param fontFamily - 글꼴 이름
8118
8098
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8119
8099
  */
8120
- setFontFamily(fontFamily: string, range?: {
8121
- from: number;
8122
- to: number;
8123
- }): Promise<void>;
8100
+ setFontFamily(fontFamily: string, range?: TextRange): Promise<void>;
8124
8101
  /**
8125
- * 글자 색상 설정.
8102
+ * 글자 색상을 설정한다.
8126
8103
  *
8127
8104
  * @param color - hex (#RRGGBB) 또는 scheme color
8128
8105
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8129
8106
  */
8130
- setTextColor(color: string, range?: {
8131
- from: number;
8132
- to: number;
8133
- }): Promise<void>;
8107
+ setTextColor(color: string, range?: TextRange): Promise<void>;
8134
8108
  /**
8135
8109
  * 텍스트에 하이퍼링크를 설정한다. (getTextHyperlink 대칭 — 반환 객체를 그대로 넘겨 링크를 복사할 수 있다)
8136
- * 도형 전체에 링크를 거는 setHyperlink 와 달리 글자(run)에 걸려 하이퍼링크 서식으로 표시된다.
8137
- * other(program/macro/ole 등)와 유효하지 않은 대상(없는 슬라이드 id·ShowJumpType 밖의 값)은 무시한다.
8110
+ * 도형 전체에 링크를 거는 setHyperlink 와 달리 링크가 글자(run) 단위로 걸리며 하이퍼링크 서식으로 표시된다.
8111
+ * 지원하지 않는 종류나 유효하지 않은 대상(없는 슬라이드 id 등)은 무시한다.
8138
8112
  *
8139
- * @param hyperlink - getTextHyperlink() 반환값 (baseShape 의 Hyperlink). type 이 없으면 무시한다
8113
+ * @param hyperlink - getTextHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
8140
8114
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8141
8115
  */
8142
- setTextHyperlink(hyperlink: Hyperlink, range?: {
8143
- from: number;
8144
- to: number;
8145
- }): Promise<void>;
8116
+ setTextHyperlink(hyperlink: Hyperlink, range?: TextRange): Promise<void>;
8146
8117
  /**
8147
8118
  * 텍스트의 하이퍼링크를 제거한다. (도형 자체에 걸린 하이퍼링크는 removeHyperlink)
8148
8119
  *
8149
8120
  * @param range - 제거할 텍스트 구간 (기본값: 전체 텍스트)
8150
8121
  */
8151
- removeTextHyperlink(range?: {
8152
- from: number;
8153
- to: number;
8154
- }): Promise<void>;
8122
+ removeTextHyperlink(range?: TextRange): Promise<void>;
8155
8123
  /**
8156
8124
  * 지정한 offset 위치에 특수문자(symbol)를 삽입한다.
8157
8125
  *
@@ -8165,147 +8133,126 @@ declare namespace Show {
8165
8133
  * @param align - 가로 정렬
8166
8134
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8167
8135
  */
8168
- setAlignH(align: TextAlignH, range?: {
8169
- from: number;
8170
- to: number;
8171
- }): Promise<void>;
8136
+ setAlignH(align: TextAlignH, range?: TextRange): Promise<void>;
8172
8137
  /**
8173
8138
  * 단락 서식을 한 번에 설정한다. range 를 주면 그 구간이 걸친 단락에만 적용한다.
8174
- * 문단 모양 대화상자의 입력 항목과 1:1 로 대응하며, 대화상자와 같이 한 액션으로 적용해 실행 취소 단위가 하나다.
8175
8139
  * 값을 준 속성만 바뀐다. null/undefined 는 "변경 없음"으로 무시하며, 지정한 값을 상속 상태로 되돌리는 방법은 아직 없다.
8176
8140
  * 단일 속성은 setLineSpacing/setMarginLeft/setFirstLineIndent/setSpaceBefore/setSpaceAfter 사용 권장.
8177
- * 목록 수준은 부수 효과(글머리 기호·글자 크기)가 달라 여기 담지 않는다. (setLevel 참고)
8178
- * alignH 만 별도 액션(setAlignH)으로 나가므로 다른 속성과 함께 주면 실행 취소 단위가 2개로 나뉜다.
8141
+ * 목록 수준은 바꿀 때 딸려오는 부수 효과(글머리 기호·글자 크기)가 있어 여기 담지 않는다. (setLevel 참고)
8179
8142
  *
8180
8143
  * @param style - 단락 서식 설정
8181
8144
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8182
8145
  */
8183
- setParagraphStyle(style: ParagraphStyle, range?: {
8184
- from: number;
8185
- to: number;
8186
- }): Promise<void>;
8146
+ setParagraphStyle(style: ParagraphStyle, range?: TextRange): Promise<void>;
8187
8147
  /**
8188
8148
  * 줄 간격을 설정한다. range 를 주면 그 구간이 걸친 단락에만 적용한다.
8189
- * MULTIPLE 이면 "100%" 형태, EXACT 이면 pt 입력을 twip view 값으로 변환한다
8149
+ * lineSpacing 의 단위는 유형에 따라 다르다 - MULTIPLE 이면 배수 백분율(150=1.5배), EXACT 이면 pt 다.
8190
8150
  *
8191
8151
  * @param lineSpacing - 줄 간격 값 (MULTIPLE: 배수%, EXACT: pt)
8192
8152
  * @param type - 줄 간격 유형 (기본값: LineSpacingType.MULTIPLE)
8193
8153
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8194
8154
  */
8195
- setLineSpacing(lineSpacing: number, type?: LineSpacingType, range?: {
8196
- from: number;
8197
- to: number;
8198
- }): Promise<void>;
8155
+ setLineSpacing(lineSpacing: number, type?: LineSpacingType, range?: TextRange): Promise<void>;
8199
8156
  /**
8200
8157
  * 단락 앞 간격(UI "문단 위")을 설정한다.
8201
8158
  *
8202
8159
  * @param spaceBefore - 단락 앞 간격 (pt)
8203
8160
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8204
8161
  */
8205
- setSpaceBefore(spaceBefore: number, range?: {
8206
- from: number;
8207
- to: number;
8208
- }): Promise<void>;
8162
+ setSpaceBefore(spaceBefore: number, range?: TextRange): Promise<void>;
8209
8163
  /**
8210
8164
  * 단락 뒤 간격(UI "문단 아래")을 설정한다.
8211
8165
  *
8212
8166
  * @param spaceAfter - 단락 뒤 간격 (pt)
8213
8167
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8214
8168
  */
8215
- setSpaceAfter(spaceAfter: number, range?: {
8216
- from: number;
8217
- to: number;
8218
- }): Promise<void>;
8169
+ setSpaceAfter(spaceAfter: number, range?: TextRange): Promise<void>;
8219
8170
  /**
8220
- * 단락 전체의 왼쪽 여백(UI "텍스트 앞")을 설정한다. 첫 줄만 밀려면 setFirstLineIndent 를 쓴다.
8171
+ * 단락 전체의 왼쪽 여백(UI "텍스트 앞")을 설정한다. 첫 줄만 들여쓰려면 setFirstLineIndent 를 사용한다.
8221
8172
  *
8222
8173
  * @param marginLeft - 왼쪽 여백 (pt)
8223
8174
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8224
8175
  */
8225
- setMarginLeft(marginLeft: number, range?: {
8226
- from: number;
8227
- to: number;
8228
- }): Promise<void>;
8176
+ setMarginLeft(marginLeft: number, range?: TextRange): Promise<void>;
8229
8177
  /**
8230
8178
  * 단락 첫 줄의 들여쓰기(UI "첫 줄")를 설정한다. 둘째 줄부터는 marginLeft 를 따른다.
8231
- * 양수는 들여쓰기, 음수는 내어쓰기, 0 은 없음이다. (UI 의 없음/들여쓰기/내어쓰기 구분을 부호 하나로 표현한다)
8232
- * 글머리 기호 목록의 계층 깊이를 바꾸려는 것이면 setLevel 이다.
8179
+ * 양수는 들여쓰기, 음수는 내어쓰기, 0 은 들여쓰기 없음이다.
8180
+ * 글머리 기호 목록의 계층 깊이를 바꾸려면 setLevel 을 사용한다.
8233
8181
  *
8234
8182
  * @param firstLineIndent - 첫 줄 들여쓰기 (pt)
8235
8183
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8236
8184
  */
8237
- setFirstLineIndent(firstLineIndent: number, range?: {
8238
- from: number;
8239
- to: number;
8240
- }): Promise<void>;
8185
+ setFirstLineIndent(firstLineIndent: number, range?: TextRange): Promise<void>;
8241
8186
  /**
8242
8187
  * 목록 수준(개요 계층 깊이)을 설정한다. range 가 걸친 단락을 모두 같은 수준으로 맞춘다.
8243
8188
  * pt 단위 들여쓰기(setFirstLineIndent/setMarginLeft)와 달리 수준은 상속 프리셋 선택이라,
8244
- * 바꾸면 그 수준의 글머리 기호와 글자 크기가 함께 따라온다.
8245
- * marginLeft 는 새 수준의 값으로 덮인다. setMarginLeft 로 지정한 값도 버려지므로
8246
- * 둘을 함께 쓸 때는 setLevel 을 먼저 호출한다. (firstLineIndent 는 유지된다)
8247
- * 대상 텍스트가 허용하는 범위(제목 개체는 1 단계뿐)로 clamp 한다.
8189
+ * 바꾸면 그 수준의 글머리 기호·글자 크기가 따라오고 marginLeft 는 새 수준의 값으로 덮인다.
8190
+ * setMarginLeft 로 지정한 값도 버려지므로 둘을 함께 쓸 때는 setLevel 을 먼저 호출한다. (firstLineIndent 는 유지)
8191
+ * 대상 텍스트가 허용하는 범위(제목 개체는 1 수준뿐)로 제한한다.
8248
8192
  *
8249
8193
  * @param level - 목록 수준 (1=최상위 ~ 9)
8250
8194
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8251
8195
  */
8252
- setLevel(level: number, range?: {
8253
- from: number;
8254
- to: number;
8255
- }): Promise<void>;
8196
+ setLevel(level: number, range?: TextRange): Promise<void>;
8256
8197
  /**
8257
- * 글머리 기호 스타일을 설정한다.
8198
+ * 글머리 기호 스타일을 설정한다. (getBulletStyle 대칭)
8199
+ * 그림 글머리(BulletType.BLIP)는 적용을 지원하지 않는 조회 전용 유형이라 거부한다.
8200
+ * CharType 프리셋 밖의 문자도 적용할 수 없다 (조회 전용이라 받을 인자가 없다).
8258
8201
  *
8259
8202
  * @param bulletType - 글머리 기호 유형
8260
8203
  * @param subType - BulletType.AUTO_NUM: 번호 매기기 유형 (기본값 NumberedType.NUMBER_WITH_DOT), BulletType.CHAR: 글머리 문자 유형 (기본값 CharType.DOT)
8261
8204
  * @param startAt - 시작 번호 (BulletType.AUTO_NUM 일 때만 사용) (기본값: 1)
8262
8205
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8206
+ * @throws {Error} bulletType 이 BulletType.BLIP(미지원 타입)이거나 subType 이 bulletType 의 값 집합 밖인 경우 (error.code = "INVALID_ARGUMENT")
8263
8207
  */
8264
- setBulletStyle(bulletType: BulletType, subType?: NumberedType | CharType, startAt?: number, range?: {
8265
- from: number;
8266
- to: number;
8267
- }): Promise<void>;
8208
+ setBulletStyle(bulletType: Exclude<BulletType, "buBlip">, subType?: NumberedType | CharType, startAt?: number, range?: TextRange): Promise<void>;
8268
8209
  /**
8269
- * 텍스트 세로 정렬을 설정한다.
8210
+ * 텍스트 세로 정렬을 설정한다. (getAlignV 대칭)
8270
8211
  *
8271
8212
  * @param align - 세로 정렬
8272
8213
  */
8273
8214
  setAlignV(align: TextAlignV): Promise<void>;
8274
8215
  /**
8275
- * 텍스트 상자 자동 맞춤 유형을 설정한다.
8216
+ * 텍스트 상자 자동 맞춤 유형을 설정한다. 이미 같은 유형이면 아무것도 하지 않는다.
8276
8217
  *
8277
8218
  * @param autoAlignType - 자동 맞춤 유형
8278
8219
  */
8279
8220
  setTextboxAutoFit(autoAlignType: AutoFitType): Promise<void>;
8280
8221
  /**
8281
- * 일반 도형에 정의된 조절값과 조절 가능한 범위를 반환한다. 반환된 name은 조절값 조회와 변경 API에서 사용한다.
8222
+ * 일반 도형에 정의된 조절값과 조절 가능한 범위를 반환한다. 반환된 name 은 조절값 조회와 변경 API 에서 사용한다.
8223
+ *
8224
+ * @returns 조절값 목록. 대상 도형이 없으면(협업 중 삭제 등) null
8225
+ */
8226
+ getAdjustValues(): Promise<AdjustValue[] | null>;
8227
+ /**
8228
+ * 3D 회전 시 텍스트를 평면으로 유지하는지 반환한다. (setFlatTx 대칭)
8282
8229
  *
8283
- * @returns 조절값 목록
8230
+ * @returns 텍스트 평면 유지 여부. 대상 도형이 없으면 null
8284
8231
  */
8285
- getAdjustValues(): Promise<AdjustValue[]>;
8232
+ isFlatTx(): Promise<boolean | null>;
8286
8233
  /**
8287
- * 3D 회전 시 텍스트를 평면으로 유지할지 설정한다.
8234
+ * 3D 회전 시 텍스트를 평면으로 유지할지 설정한다. (isFlatTx 대칭)
8288
8235
  *
8289
- * @param enabled - true이면 텍스트 평면 유지, false이면 해제
8236
+ * @param enabled - true 이면 텍스트 평면 유지, false 이면 해제
8290
8237
  */
8291
8238
  setFlatTx(enabled: boolean): Promise<void>;
8292
8239
  /**
8293
- * 일반 도형의 조절값(adjust value) 하나를 변경한다. 여러 조절값을 함께 변경하려면 setAdjustValues를 사용한다.
8240
+ * 일반 도형의 조절값(adjust value) 하나를 변경한다. 여러 조절값을 함께 변경하려면 setAdjustValues 를 사용한다.
8294
8241
  *
8295
8242
  * @param name - 조절값 이름(getAdjustValues 결과)
8296
- * @param value - 조절값. 정수로 반올림되며 허용 범위를 벗어나면 최솟값 또는 최댓값으로 제한됨
8297
- * @throws {Error} name이 현재 도형에 없는 조절값인 경우
8243
+ * @param value - 조절값. 정수로 반올림되며 허용 범위를 벗어나면 최솟값 또는 최댓값으로 제한됨 (getAdjustValues 의 min/max 가 null 인 경우처럼 범위를 알 수 없으면 제한하지 않는다)
8244
+ * @throws {Error} name 이 현재 도형에 없는 조절값인 경우 (error.code = "INVALID_ARGUMENT")
8298
8245
  */
8299
8246
  setAdjustValue(name: string, value: number): Promise<void>;
8300
8247
  /**
8301
8248
  * 일반 도형의 여러 조절값(adjust value)을 한 번에 변경한다.
8302
8249
  *
8303
8250
  * @param avList - 변경할 조절값 목록
8304
- * @throws {Error} name이 현재 도형에 없는 조절값인 경우
8251
+ * @throws {Error} name 이 현재 도형에 없는 조절값인 경우 (error.code = "INVALID_ARGUMENT")
8305
8252
  */
8306
8253
  setAdjustValues(avList: AdjustValueUpdate[]): Promise<void>;
8307
8254
  }
8308
- /** 이미지 도형을 다루는 핸들로, 원본 크기 되돌리기(resetImageSize)와 이미지 자르기(cropImage)를 제공하며, 위치·크기·채우기·선·효과는 BasePathShape 공통 API 를 그대로 쓴다. */
8255
+ /** 이미지 도형을 다루는 핸들로, 원본 크기 되돌리기(resetSize)와 이미지 자르기 조회·설정(getCrop/setCrop)을 제공하며, 위치·크기·채우기·선·효과는 BasePathShape 공통 API 를 그대로 쓴다. */
8309
8256
  export interface Image extends BasePathShape {
8310
8257
  /**
8311
8258
  * 선언 전용 명목 브랜드 — 멤버 구성이 같은 핸들 타입이 서로 대입 가능해져 가드
@@ -8314,22 +8261,28 @@ declare namespace Show {
8314
8261
  */
8315
8262
  readonly [__proxyBrand]?: 'Image';
8316
8263
  /**
8317
- * 이미지를 원본 크기로 되돌린다.
8318
- * blip 의 width/height (pixel) 를 EMU 로 변환하여 xfrm 을 갱신하고, srcRect (crop) 가 있으면 함께 제거한다.
8264
+ * 이미지에 적용된 자르기(crop) 상태를 반환한다. (setCrop 대칭 - 반환 객체를 그대로 넘길 수 있다)
8265
+ * 모든 값의 단위는 퍼센트다 (-100~100). 자르지 않은 방향은 0 이고, 음수는 바깥 여백이다.
8266
+ *
8267
+ * @returns 자르기 상태. 대상 이미지가 없으면 null
8319
8268
  */
8320
- resetImageSize(): Promise<void>;
8269
+ getCrop(): Promise<ImageCrop | null>;
8321
8270
  /**
8322
- * 이미지를 지정한 방향으로 자른다 (srcRect 업데이트).
8323
- * 모든 인자 단위: 퍼센트 (0~100, UI 단위).
8271
+ * 이미지를 문서에 실린 원본 크기로 되돌린다. 자르기(crop)가 있으면 함께 제거한다.
8272
+ */
8273
+ resetSize(): Promise<void>;
8274
+ /**
8275
+ * 이미지를 지정한 방향으로 자른다. (getCrop 대칭 - 반환 객체를 그대로 넘길 수 있다)
8276
+ * 지정한 방향만 적용하고 생략한 방향은 기존 값을 유지한다. 자르기를 없애려면 0 을 명시한다.
8277
+ * 모든 값의 단위는 퍼센트다 (-100~100). 양수는 그 방향을 잘라 내고, 음수는 바깥 여백을 만든다.
8278
+ * 병합 결과가 지금 값과 같으면 아무것도 하지 않는다.
8324
8279
  *
8325
- * @param left - 왼쪽 crop 퍼센트 (기본값: 기존 값 유지)
8326
- * @param top - 위쪽 crop 퍼센트 (기본값: 기존 값 유지)
8327
- * @param right - 오른쪽 crop 퍼센트 (기본값: 기존 값 유지)
8328
- * @param bottom - 아래쪽 crop 퍼센트 (기본값: 기존 값 유지)
8280
+ * @param crop - 자르기 설정
8281
+ * @throws {Error} 병합 결과의 left+right 또는 top+bottom 이 100 이상이라 남는 영역이 없는 경우 (error.code = "INVALID_ARGUMENT")
8329
8282
  */
8330
- cropImage(left?: number, top?: number, right?: number, bottom?: number): Promise<void>;
8283
+ setCrop(crop: Partial<ImageCrop>): Promise<void>;
8331
8284
  }
8332
- /** 연결선을 다루는 핸들로, 시작·끝 화살표 모양 설정(setLineHeadEnd/setLineTailEnd)을 제공하며, 선 색·두께·점선 등 선 서식은 BasePathShape 공통 API 를 그대로 쓴다. */
8285
+ /** 연결선을 다루는 핸들로, 시작·끝 화살표 조회·설정(getHeadEnd/getTailEnd/setHeadEnd/setTailEnd)을 제공하고 선 색·두께·점선 등 선 서식은 BasePathShape 공통 API 를 그대로 쓰며, 회전·반전은 지원하지 않아(에디터 UI 도 같은 제약) 물려받은 setRotation/flip 은 액션을 만들지 않고 무시된다. */
8333
8286
  export interface Line extends BasePathShape {
8334
8287
  /**
8335
8288
  * 선언 전용 명목 브랜드 — 멤버 구성이 같은 핸들 타입이 서로 대입 가능해져 가드
@@ -8338,21 +8291,37 @@ declare namespace Show {
8338
8291
  */
8339
8292
  readonly [__proxyBrand]?: 'Line';
8340
8293
  /**
8341
- * 연결선의 시작 화살표(headEnd)를 설정한다.
8294
+ * 연결선의 시작 화살표(headEnd)를 반환한다. (setHeadEnd 대칭 - 반환 객체를 그대로 넘길 수 있다)
8295
+ *
8296
+ * @returns 시작 화살표 설정. 대상 연결선이 없으면 null. 화살표가 없는 상태는 null 이 아니라 type 이 LineEndType.NONE 인 객체다
8297
+ */
8298
+ getHeadEnd(): Promise<LineEnd | null>;
8299
+ /**
8300
+ * 연결선의 끝 화살표(tailEnd)를 반환한다. (setTailEnd 대칭 - 반환 객체를 그대로 넘길 수 있다)
8301
+ *
8302
+ * @returns 끝 화살표 설정. 대상 연결선이 없으면 null. 화살표가 없는 상태는 null 이 아니라 type 이 LineEndType.NONE 인 객체다
8303
+ */
8304
+ getTailEnd(): Promise<LineEnd | null>;
8305
+ /**
8306
+ * 연결선의 시작 화살표(headEnd)를 설정한다. (getHeadEnd 대칭 - 반환 객체를 그대로 넘길 수 있다)
8307
+ * 화살표를 없애려면 type 에 LineEndType.NONE 을 준다.
8308
+ * width/length 를 생략하면 기존 크기가 아니라 기본값(MEDIUM)이 적용된다.
8342
8309
  *
8343
- * @param type - 화살표 타입
8344
- * @param width - 화살표 너비 (기본값: LineEndSize.MEDIUM)
8345
- * @param length - 화살표 길이 (기본값: LineEndSize.MEDIUM)
8310
+ * @param lineEnd - 화살표 설정
8346
8311
  */
8347
- setLineHeadEnd(type: LineEndType, width?: LineEndSize, length?: LineEndSize): Promise<void>;
8312
+ setHeadEnd(lineEnd: Partial<LineEnd> & {
8313
+ type: LineEndType;
8314
+ }): Promise<void>;
8348
8315
  /**
8349
- * 연결선의 끝 화살표(tailEnd)를 설정한다.
8316
+ * 연결선의 끝 화살표(tailEnd)를 설정한다. (getTailEnd 대칭 - 반환 객체를 그대로 넘길 수 있다)
8317
+ * 화살표를 없애려면 type 에 LineEndType.NONE 을 준다.
8318
+ * width/length 를 생략하면 기존 크기가 아니라 기본값(MEDIUM)이 적용된다.
8350
8319
  *
8351
- * @param type - 화살표 타입
8352
- * @param width - 화살표 너비 (기본값: LineEndSize.MEDIUM)
8353
- * @param length - 화살표 길이 (기본값: LineEndSize.MEDIUM)
8320
+ * @param lineEnd - 화살표 설정
8354
8321
  */
8355
- setLineTailEnd(type: LineEndType, width?: LineEndSize, length?: LineEndSize): Promise<void>;
8322
+ setTailEnd(lineEnd: Partial<LineEnd> & {
8323
+ type: LineEndType;
8324
+ }): Promise<void>;
8356
8325
  }
8357
8326
  /** 그룹 도형을 다루는 핸들로, 하위 도형 조회(getChildren)와 그룹 해제(ungroup)를 제공하며, 위치·크기·정렬·순서는 BaseShape 공통 API 를 그대로 쓴다. */
8358
8327
  export interface Group extends BaseShape {
@@ -8365,14 +8334,16 @@ declare namespace Show {
8365
8334
  /**
8366
8335
  * 그룹의 자식 도형 목록을 반환한다.
8367
8336
  *
8368
- * @returns 자식 도형 목록
8337
+ * @returns 자식 도형 목록. 그룹 도형이 없으면(협업 중 삭제 등) 빈 배열
8369
8338
  */
8370
8339
  getChildren(): Promise<(Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control)[]>;
8371
8340
  /**
8372
- * 그룹을 해제하여 자식 도형들을 슬라이드 루트로 분리한다.
8373
- * 해제 후 이 Group 인스턴스는 더 이상 유효하지 않다.
8341
+ * 그룹을 해제하여 자식 도형을 슬라이드 최상위로 분리한다.
8342
+ * 해제 후 이 Group 인스턴스와 미리 얻어 둔 자식 프록시는 무효가 된다 (자식이 새 id 를 받는다).
8343
+ *
8344
+ * @returns 분리된 자식 도형 배열
8374
8345
  */
8375
- ungroup(): Promise<void>;
8346
+ ungroup(): Promise<(Shape | Image | Line | Group | Chart | Table | Diagram | OleObject | Control)[]>;
8376
8347
  }
8377
8348
  /** 차트 도형을 다루는 핸들로, 차트 종류·스타일(setType/setStyle), 제목·축 제목(setTitle/setAxisTitle), 범례·데이터 라벨 위치(setLegendPosition/setDataLabelPosition), 눈금선(setGridLine) 편집과 현재 서식 상태 조회(getType/getTitle/getState 등)를 제공한다. */
8378
8349
  export interface Chart extends BaseShape {
@@ -8496,17 +8467,17 @@ declare namespace Show {
8496
8467
  /**
8497
8468
  * 표의 행 개수를 반환한다.
8498
8469
  *
8499
- * @returns 행 개수
8470
+ * @returns 행 개수. 표가 없으면 0
8500
8471
  */
8501
8472
  getRowCount(): Promise<number>;
8502
8473
  /**
8503
8474
  * 표의 열 개수를 반환한다.
8504
8475
  *
8505
- * @returns 열 개수
8476
+ * @returns 열 개수. 표가 없으면 0
8506
8477
  */
8507
8478
  getColCount(): Promise<number>;
8508
8479
  /**
8509
- * 병합된 셀 내부 좌표를 지정하면 해당 병합 영역의 대표 셀을 반환한다.
8480
+ * 지정 좌표의 셀을 반환한다. 병합 영역 내부 좌표를 지정하면 그 병합 영역의 대표 셀을 반환한다.
8510
8481
  *
8511
8482
  * @param row - 행 인덱스 (0-based)
8512
8483
  * @param col - 열 인덱스 (0-based)
@@ -8522,11 +8493,13 @@ declare namespace Show {
8522
8493
  getCells(): Promise<TableCell[]>;
8523
8494
  /**
8524
8495
  * 조건에 맞는 셀 배열을 반환한다.
8525
- * 복수 조건은 AND로 결합. range 는 셀 본체가 범위와 겹치면 매칭 (병합 대표 셀이 범위 밖에 있어도 셀 일부가 범위 안이면 결과에 포함됨).
8526
- * 그 외 조건은 병합된 셀의 대표 셀 좌표/속성 기준으로 평가.
8496
+ * 복수 조건은 AND 로 결합한다. range 는 셀 본체가 범위와 겹치면 매칭된다
8497
+ * (병합 대표 셀이 범위 밖에 있어도 셀 일부가 범위 안이면 결과에 포함된다).
8498
+ * 그 외 조건은 병합된 셀의 대표 셀 좌표/속성 기준으로 평가한다.
8527
8499
  *
8528
- * @param filter - 검색 조건 (기본값: 전체 셀)
8500
+ * @param filter - 검색 조건. null 도 조건 없음으로 본다 (기본값: 전체 셀)
8529
8501
  * @returns 조건에 맞는 셀 목록
8502
+ * @throws {Error} range 가 표 범위를 벗어난 경우 (error.code = "INVALID_ARGUMENT")
8530
8503
  */
8531
8504
  findCells(filter?: CellFilter): Promise<TableCell[]>;
8532
8505
  /**
@@ -8560,13 +8533,29 @@ declare namespace Show {
8560
8533
  */
8561
8534
  getColumn(colIndex: number): Promise<TableCell[]>;
8562
8535
  /**
8563
- * 표 스타일을 변경한다.
8536
+ * 표에 적용된 스타일 이름을 반환한다. (setStyle 대칭)
8537
+ * 반환한 이름은 그대로 setStyle 에 되먹일 수 있다. 다만 문서에만 실려 있고 편집기 갤러리에는
8538
+ * 없는 스타일이면 doc.getTableStyleNames() 목록에는 나오지 않는다.
8539
+ *
8540
+ * @returns 표 스타일 이름. 스타일이 없거나 이름이 없는 스타일(문서가 이름을 싣지 않은 경우)이면 null
8541
+ */
8542
+ getStyleName(): Promise<string | null>;
8543
+ /**
8544
+ * 표 스타일 옵션(머리글 행, 줄무늬 행 등)의 활성화 여부를 반환한다. (setStyleOption 대칭)
8545
+ *
8546
+ * @param option - 옵션 유형 (apiConstants.TableStyleOption)
8547
+ * @returns 활성화 여부. 표나 표 속성을 읽을 수 없으면 null
8548
+ */
8549
+ getStyleOption(option: TableStyleOption): Promise<boolean | null>;
8550
+ /**
8551
+ * 표 스타일을 변경한다. (getStyleName 대칭)
8564
8552
  *
8565
- * @param styleName - 표 스타일 이름 (doc.getTableStyleNames() 결과). 목록에 없는 이름이면 throw
8553
+ * @param styleName - 표 스타일 이름 (doc.getTableStyleNames() 결과)
8554
+ * @throws {Error} 목록에 없는 이름인 경우 (error.code = "SCHEME_NOT_FOUND")
8566
8555
  */
8567
8556
  setStyle(styleName: string): Promise<void>;
8568
8557
  /**
8569
- * 표 스타일 옵션(머리글 행, 줄무늬 행 등)을 변경한다.
8558
+ * 표 스타일 옵션(머리글 행, 줄무늬 행 등)을 변경한다. (getStyleOption 대칭)
8570
8559
  *
8571
8560
  * @param option - 옵션 유형 (apiConstants.TableStyleOption)
8572
8561
  * @param enabled - 활성화 여부
@@ -8577,8 +8566,8 @@ declare namespace Show {
8577
8566
  *
8578
8567
  * @param startRow - 병합 시작 행 인덱스 (0-based)
8579
8568
  * @param startCol - 병합 시작 열 인덱스 (0-based)
8580
- * @param endRow - 병합 끝 행 인덱스
8581
- * @param endCol - 병합 끝 열 인덱스
8569
+ * @param endRow - 병합 끝 행 인덱스 (0-based, inclusive)
8570
+ * @param endCol - 병합 끝 열 인덱스 (0-based, inclusive)
8582
8571
  */
8583
8572
  mergeCell(startRow: number, startCol: number, endRow: number, endCol: number): Promise<void>;
8584
8573
  /**
@@ -8586,8 +8575,8 @@ declare namespace Show {
8586
8575
  *
8587
8576
  * @param startRow - 해제 시작 행 인덱스 (0-based)
8588
8577
  * @param startCol - 해제 시작 열 인덱스 (0-based)
8589
- * @param endRow - 해제 끝 행 인덱스
8590
- * @param endCol - 해제 끝 열 인덱스
8578
+ * @param endRow - 해제 끝 행 인덱스 (0-based, inclusive)
8579
+ * @param endCol - 해제 끝 열 인덱스 (0-based, inclusive)
8591
8580
  */
8592
8581
  unmergeCell(startRow: number, startCol: number, endRow: number, endCol: number): Promise<void>;
8593
8582
  /**
@@ -8600,10 +8589,12 @@ declare namespace Show {
8600
8589
  */
8601
8590
  insertRow(baseRowIndex: number, position: InsertPosition, insertNum: number): Promise<void>;
8602
8591
  /**
8603
- * 지정 범위의 행을 삭제한다.
8592
+ * 지정 범위의 행을 삭제한다. 모든 행을 지울 수는 없다 - 한 행짜리 표에서 그 행을 지우려 하면 오류가 난다.
8593
+ * 표 자체를 없애려면 Slide.deleteShape 를 쓴다.
8604
8594
  *
8605
8595
  * @param startRow - 삭제 시작 행 인덱스 (0-based)
8606
- * @param endRow - 삭제 끝 행 인덱스
8596
+ * @param endRow - 삭제 끝 행 인덱스 (0-based, inclusive)
8597
+ * @throws {Error} 삭제 후 남는 행이 없는 경우 (error.code = "INVALID_ARGUMENT")
8607
8598
  */
8608
8599
  deleteRow(startRow: number, endRow: number): Promise<void>;
8609
8600
  /**
@@ -8616,24 +8607,26 @@ declare namespace Show {
8616
8607
  */
8617
8608
  insertCol(baseColIndex: number, position: InsertPosition, insertNum: number): Promise<void>;
8618
8609
  /**
8619
- * 지정 범위의 열을 삭제한다.
8610
+ * 지정 범위의 열을 삭제한다. 모든 열을 지울 수는 없다 - 한 열짜리 표에서 그 열을 지우려 하면 오류가 난다.
8611
+ * 표 자체를 없애려면 Slide.deleteShape 를 쓴다.
8620
8612
  *
8621
8613
  * @param startCol - 삭제 시작 열 인덱스 (0-based)
8622
- * @param endCol - 삭제 끝 열 인덱스
8614
+ * @param endCol - 삭제 끝 열 인덱스 (0-based, inclusive)
8615
+ * @throws {Error} 삭제 후 남는 열이 없는 경우 (error.code = "INVALID_ARGUMENT")
8623
8616
  */
8624
8617
  deleteCol(startCol: number, endCol: number): Promise<void>;
8625
8618
  /**
8626
8619
  * 지정 행의 높이를 변경한다.
8627
8620
  *
8628
8621
  * @param rowIndex - 행 인덱스 (0-based)
8629
- * @param newHeight - 새 높이 (px 단위)
8622
+ * @param newHeight - 새 높이 (px 단위). rowIndex 가 표의 행 수를 벗어나면 무시된다
8630
8623
  */
8631
8624
  setRowHeight(rowIndex: number, newHeight: number): Promise<void>;
8632
8625
  /**
8633
8626
  * 지정 열의 너비를 변경한다.
8634
8627
  *
8635
8628
  * @param colIndex - 열 인덱스 (0-based)
8636
- * @param newWidth - 새 너비 (px 단위)
8629
+ * @param newWidth - 새 너비 (px 단위). colIndex 가 표의 열 수를 벗어나면 무시된다
8637
8630
  */
8638
8631
  setColWidth(colIndex: number, newWidth: number): Promise<void>;
8639
8632
  }
@@ -8646,176 +8639,168 @@ declare namespace Show {
8646
8639
  isShape(): this is Shape;
8647
8640
  /**
8648
8641
  * 대표 단락(range 가 걸친 첫 단락)의 단락 서식을 반환한다. (setParagraphStyle 대칭)
8649
- * 반환 객체를 그대로 다른 개체의 setParagraphStyle 에 넘길 수 있다. 값이 없는 속성은 키를 생략한다.
8650
- * 값은 레이아웃/마스터 상속이 반영된 해석값이다. 단락이 직접 지정한 값만 골라낼 수는 없다.
8651
- * 같은 단락에 그대로 되돌려주면 상속값과 같은 속성은 오버라이드로 굳지 않고 지워진다. (updateTextPPr 동작)
8652
- * 목록 수준은 서식 값이 아니라 상속 프리셋이라 이 객체에 담지 않는다. (getLevel 대칭)
8642
+ * 반환 객체를 그대로 다른 개체의 setParagraphStyle 에 넘길 수 있다. 값이 없는 속성은 키를 담지 않는다.
8643
+ * 값은 레이아웃/마스터 상속까지 반영해 실제 적용된 값이라 단락이 직접 지정한 값만 골라낼 수는 없고,
8644
+ * 같은 단락에 그대로 다시 넘기면 상속값과 같은 속성은 직접 지정으로 남지 않는다.
8645
+ * 목록 수준은 서식 값이 아니라 상속 프리셋이라 담지 않는다. (getLevel 대칭)
8653
8646
  *
8654
8647
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8655
- * @returns 단락 서식 (baseText.ParagraphStyle). 텍스트/단락 없으면 null
8648
+ * @returns 단락 서식. 텍스트/단락 없으면 null
8656
8649
  */
8657
- getParagraphStyle(range?: {
8658
- from: number;
8659
- to: number;
8660
- }): Promise<ParagraphStyle | null>;
8650
+ getParagraphStyle(range?: TextRange): Promise<ParagraphStyle | null>;
8661
8651
  /**
8662
8652
  * 대표 단락의 가로 정렬을 반환한다. (setAlignH 대칭)
8663
8653
  *
8664
8654
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8665
8655
  * @returns 가로 정렬. 텍스트/단락 없으면 null
8666
8656
  */
8667
- getAlignH(range?: {
8668
- from: number;
8669
- to: number;
8670
- }): Promise<TextAlignH | null>;
8657
+ getAlignH(range?: TextRange): Promise<TextAlignH | null>;
8671
8658
  /**
8672
8659
  * 대표 단락의 줄 간격 값을 반환한다. (setLineSpacing 대칭)
8673
8660
  *
8674
8661
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8675
8662
  * @returns 줄 간격 값 (MULTIPLE: 배수%, EXACT: pt). 텍스트/단락 없으면 null
8676
8663
  */
8677
- getLineSpacing(range?: {
8678
- from: number;
8679
- to: number;
8680
- }): Promise<number | null>;
8664
+ getLineSpacing(range?: TextRange): Promise<number | null>;
8681
8665
  /**
8682
8666
  * 대표 단락의 줄 간격 유형을 반환한다. (setLineSpacing 의 type 대칭)
8683
8667
  *
8684
8668
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8685
8669
  * @returns 줄 간격 유형. 텍스트/단락 없으면 null
8686
8670
  */
8687
- getLineSpacingType(range?: {
8688
- from: number;
8689
- to: number;
8690
- }): Promise<LineSpacingType | null>;
8671
+ getLineSpacingType(range?: TextRange): Promise<LineSpacingType | null>;
8691
8672
  /**
8692
8673
  * 대표 단락의 단락 앞 간격(UI "문단 위")을 반환한다. (setSpaceBefore 대칭)
8693
8674
  *
8694
8675
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8695
8676
  * @returns 단락 앞 간격 (pt). 배수(%) 저장/텍스트 없음이면 null
8696
8677
  */
8697
- getSpaceBefore(range?: {
8698
- from: number;
8699
- to: number;
8700
- }): Promise<number | null>;
8678
+ getSpaceBefore(range?: TextRange): Promise<number | null>;
8701
8679
  /**
8702
8680
  * 대표 단락의 단락 뒤 간격(UI "문단 아래")을 반환한다. (setSpaceAfter 대칭)
8703
8681
  *
8704
8682
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8705
8683
  * @returns 단락 뒤 간격 (pt). 배수(%) 저장/텍스트 없음이면 null
8706
8684
  */
8707
- getSpaceAfter(range?: {
8708
- from: number;
8709
- to: number;
8710
- }): Promise<number | null>;
8685
+ getSpaceAfter(range?: TextRange): Promise<number | null>;
8711
8686
  /**
8712
8687
  * 대표 단락의 왼쪽 여백(UI "텍스트 앞")을 반환한다. (setMarginLeft 대칭)
8713
8688
  *
8714
8689
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8715
8690
  * @returns 왼쪽 여백 (pt). 텍스트/단락 없으면 null
8716
8691
  */
8717
- getMarginLeft(range?: {
8718
- from: number;
8719
- to: number;
8720
- }): Promise<number | null>;
8692
+ getMarginLeft(range?: TextRange): Promise<number | null>;
8721
8693
  /**
8722
8694
  * 대표 단락의 첫 줄 들여쓰기(UI "첫 줄")를 반환한다. (setFirstLineIndent 대칭)
8723
8695
  *
8724
8696
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8725
8697
  * @returns 첫 줄 들여쓰기 (pt, 음수는 내어쓰기). 텍스트/단락 없으면 null
8726
8698
  */
8727
- getFirstLineIndent(range?: {
8728
- from: number;
8729
- to: number;
8730
- }): Promise<number | null>;
8699
+ getFirstLineIndent(range?: TextRange): Promise<number | null>;
8731
8700
  /**
8732
8701
  * 대표 단락의 목록 수준을 반환한다. (setLevel 대칭)
8733
8702
  *
8734
8703
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8735
8704
  * @returns 목록 수준 (1~9). 텍스트/단락 없으면 null
8736
8705
  */
8737
- getLevel(range?: {
8738
- from: number;
8739
- to: number;
8740
- }): Promise<number | null>;
8706
+ getLevel(range?: TextRange): Promise<number | null>;
8741
8707
  /**
8742
- * 텍스트를 plain text로 반환한다.
8708
+ * 대표 단락의 글머리 기호 스타일을 반환한다. 반환 필드를 풀어서 setBulletStyle(type, subType, startAt) 에 넘길 수 있다.
8709
+ * 값은 레이아웃/마스터 상속까지 반영해 실제 적용된 값이고, 없는 값(시작 번호)과 되넘길 수 없는 값(프리셋 밖 번호 유형)은 키를 담지 않는다.
8710
+ * 그림 글머리·프리셋 밖 문자는 조회 전용이라 그대로는 적용되지 않는다. (제약은 setBulletStyle 참조)
8743
8711
  *
8744
8712
  * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8713
+ * @returns 글머리 기호 스타일. 텍스트/단락 없으면 null
8714
+ */
8715
+ getBulletStyle(range?: TextRange): Promise<BulletStyle | null>;
8716
+ /**
8717
+ * 텍스트를 plain text로 반환한다. 문단 사이의 개행은 그대로 들어가지만,
8718
+ * 마지막 문단을 끝맺는 개행은 글자가 아니라 담지 않는다 (빈 텍스트는 "").
8719
+ *
8720
+ * @param range - 읽을 텍스트 구간 (UTF-16 코드 단위 offset) (기본값: 전체 텍스트)
8745
8721
  * @returns 해당 구간의 텍스트 (plain text). 텍스트 모델이 없거나 빈 구간이면 ""
8746
8722
  */
8747
- getText(range?: {
8748
- from: number;
8749
- to: number;
8750
- }): Promise<string>;
8723
+ getText(range?: TextRange): Promise<string>;
8751
8724
  /**
8752
- * 대표 run(첫 run)의 글꼴 스타일을 반환한다. (setFontStyle 대칭)
8753
- * 반환 객체를 그대로 다른 개체의 setFontStyle 에 넘길 수 있다. 값이 없는 속성은 키를 생략한다.
8725
+ * 대표 run(range 가 걸친 첫 run)의 글꼴 스타일을 반환한다. (setFontStyle 대칭)
8726
+ * 반환 객체를 그대로 다른 개체의 setFontStyle 에 넘길 수 있다. 값이 없는 속성은 키를 담지 않는다.
8727
+ * 값은 레이아웃/마스터/표 스타일 상속까지 반영해 실제 적용된 값이라 run 이 직접 지정한 값만 골라낼 수는 없다.
8754
8728
  *
8755
- * @returns 글꼴 스타일 (baseText.FontStyle). 런/스타일 없으면 빈 객체 `{}`, 텍스트 모델 없음(협업 삭제 등)이면 null
8729
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8730
+ * @returns 글꼴 스타일. run/스타일 없으면 빈 객체 `{}`, 대상 텍스트가 없거나(협업 중 삭제 등) 유효하지 않은 구간이면 null
8756
8731
  */
8757
- getFontStyle(): Promise<FontStyle | null>;
8732
+ getFontStyle(range?: TextRange): Promise<FontStyle | null>;
8758
8733
  /**
8759
- * 대표 run 의 굵게 여부를 반환한다. (setBold 대칭)
8734
+ * 대표 run 의 굵게 여부를 반환한다. (setBold 대칭 — 상속까지 반영된 실제 적용값)
8760
8735
  *
8761
- * @returns 굵게 여부. 명시 안 됨(상속)/텍스트 없음이면 null
8736
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8737
+ * @returns 굵게 여부. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
8762
8738
  */
8763
- getBold(): Promise<boolean | null>;
8739
+ getBold(range?: TextRange): Promise<boolean | null>;
8764
8740
  /**
8765
- * 대표 run 의 기울임 여부를 반환한다. (setItalic 대칭)
8741
+ * 대표 run 의 기울임 여부를 반환한다. (setItalic 대칭 — 상속까지 반영된 실제 적용값)
8766
8742
  *
8767
- * @returns 기울임 여부. 명시 안 됨/텍스트 없음이면 null
8743
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8744
+ * @returns 기울임 여부. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
8768
8745
  */
8769
- getItalic(): Promise<boolean | null>;
8746
+ getItalic(range?: TextRange): Promise<boolean | null>;
8770
8747
  /**
8771
- * 대표 run 의 밑줄 유형을 반환한다. (setUnderline 대칭)
8748
+ * 대표 run 의 밑줄 유형을 반환한다. (setUnderline 대칭 — 상속까지 반영된 실제 적용값)
8772
8749
  *
8773
- * @returns 밑줄 유형. 명시 안 됨/텍스트 없음이면 null
8750
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8751
+ * @returns 밑줄 유형. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
8774
8752
  */
8775
- getUnderline(): Promise<Underline | null>;
8753
+ getUnderline(range?: TextRange): Promise<Underline | null>;
8776
8754
  /**
8777
- * 대표 run 의 취소선 유형을 반환한다. (setStrike 대칭)
8755
+ * 대표 run 의 취소선 유형을 반환한다. (setStrike 대칭 — 상속까지 반영된 실제 적용값)
8778
8756
  *
8779
- * @returns 취소선 유형. 명시 안 됨/텍스트 없음이면 null
8757
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8758
+ * @returns 취소선 유형. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
8780
8759
  */
8781
- getStrike(): Promise<Strike | null>;
8760
+ getStrike(range?: TextRange): Promise<Strike | null>;
8782
8761
  /**
8783
- * 대표 run 의 글자 크기(pt)를 반환한다. (setFontSize 대칭)
8762
+ * 대표 run 의 글자 크기(pt)를 반환한다. (setFontSize 대칭 — 상속까지 반영된 실제 적용값)
8784
8763
  *
8785
- * @returns 글자 크기 (pt). 명시 안 됨/텍스트 없음이면 null
8764
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8765
+ * @returns 글자 크기 (pt). 대상 텍스트가 없거나 유효하지 않은 구간이면 null
8786
8766
  */
8787
- getFontSize(): Promise<number | null>;
8767
+ getFontSize(range?: TextRange): Promise<number | null>;
8788
8768
  /**
8789
- * 대표 run 의 글꼴 이름을 반환한다. (setFontFamily 대칭)
8769
+ * 대표 run 의 글꼴 이름을 반환한다. (setFontFamily 대칭 — 상속까지 반영된 실제 적용값)
8790
8770
  *
8791
- * @returns 글꼴 이름. 명시 안 됨/텍스트 없음이면 null
8771
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8772
+ * @returns 글꼴 이름. 대상 텍스트가 없거나 유효하지 않은 구간이면 null
8792
8773
  */
8793
- getFontFamily(): Promise<string | null>;
8774
+ getFontFamily(range?: TextRange): Promise<string | null>;
8794
8775
  /**
8795
- * 대표 run 의 글자 색상을 반환한다. (setTextColor 대칭)
8776
+ * 대표 run 의 글자 색상을 반환한다. (setTextColor 대칭 — 상속까지 반영된 실제 적용값)
8796
8777
  *
8797
- * @returns 글자 색상 (hex "#RRGGBB"/scheme). solid 아님/명시 안 됨/텍스트 없음이면 null
8778
+ * @param range - 읽을 텍스트 구간 (기본값: 전체 텍스트)
8779
+ * @returns 글자 색상 (hex "#RRGGBB" — scheme color 도 hex 로 풀려서 나온다). solid 채우기가 아니거나 대상 텍스트가 없거나 유효하지 않은 구간이면 null
8798
8780
  */
8799
- getTextColor(): Promise<string | null>;
8781
+ getTextColor(range?: TextRange): Promise<string | null>;
8800
8782
  /**
8801
- * 텍스트 구간의 하이퍼링크를 반환한다. (setTextHyperlink 대칭 —
8802
- * 반환 객체를 그대로 넘겨 하이퍼링크를 복사할 수 있다)
8803
- * range 를 주면 그 구간의 첫 글자, 없으면 텍스트 첫 글자가 속한 run 기준이다.
8783
+ * 텍스트 구간의 하이퍼링크를 반환한다. (setTextHyperlink 대칭 — 반환 객체를 그대로 넘겨 복사할 수 있다)
8784
+ * range 를 주면 그 구간의 첫 글자, range 가 없으면 텍스트의 첫 글자가 속한 run 을 기준으로 한다.
8804
8785
  * 도형 자체에 걸린 하이퍼링크는 getHyperlink 로 읽는다.
8805
8786
  *
8806
8787
  * @param range - 조회할 텍스트 구간 (기본값: 텍스트 첫 글자)
8807
- * @returns 하이퍼링크 정보 (baseShape 의 Hyperlink). 링크 없음/텍스트 없음/미노출 action 이면 null
8788
+ * @returns 하이퍼링크 정보 (getHyperlink 와 같은 Hyperlink 객체). 링크 없음/텍스트 없음/미노출 action 이면 null
8808
8789
  */
8809
- getTextHyperlink(range?: {
8810
- from: number;
8811
- to: number;
8812
- }): Promise<Hyperlink | null>;
8790
+ getTextHyperlink(range?: TextRange): Promise<Hyperlink | null>;
8813
8791
  /**
8814
8792
  * 텍스트 상자 자동 맞춤 유형을 반환한다. (setTextboxAutoFit 대칭)
8815
8793
  *
8816
- * @returns 자동 맞춤 유형. 텍스트 모델 없으면 null
8794
+ * @returns 자동 맞춤 유형. 대상 텍스트가 없으면 null
8817
8795
  */
8818
8796
  getTextboxAutoFit(): Promise<AutoFitType | null>;
8797
+ /**
8798
+ * 텍스트 세로 정렬을 반환한다. (setAlignV 대칭)
8799
+ * TextAlignV 는 TOP 이 0 인 숫자 enum 이라, 값이 있는지는 truthy 검사가 아니라 null 비교로 본다.
8800
+ *
8801
+ * @returns 세로 정렬. 대상 텍스트가 없으면 null
8802
+ */
8803
+ getAlignV(): Promise<TextAlignV | null>;
8819
8804
  /**
8820
8805
  * 텍스트를 설정한다. 인자 조합에 따라 다음과 같이 동작한다.
8821
8806
  * - range 없음: 전체 텍스트를 text 로 교체
@@ -8823,17 +8808,14 @@ declare namespace Show {
8823
8808
  * - text 가 빈 문자열("")이면 교체 대신 해당 범위를 삭제
8824
8809
  *
8825
8810
  * 삭제 없이 끼워넣는 삽입은 insertText 를 사용한다.
8826
- * (단, from이 텍스트 끝(마지막 글자 다음 위치)이면 지울 글자가 없어 끝 삽입으로 동작한다)
8811
+ * (단, from 이 텍스트 끝이면 지울 글자가 없어 끝 삽입으로 동작).
8827
8812
  *
8828
- * 대체된 자리의 글자 서식은 구간 시작 위치의 런 서식을, 문단 서식은 기존 문단의 서식을 따른다.
8813
+ * 대체된 자리의 글자 서식은 구간 시작 위치의 글자 서식을, 문단 서식은 기존 문단의 서식을 따른다.
8829
8814
  *
8830
8815
  * @param text - 설정할 텍스트. 빈 문자열("")이면 삭제로 동작
8831
- * @param range - 교체할 텍스트 구간 to = from + 글자수 - 1 (0-based) 예: "가나다" 전체 = {from: 0, to: 2}, "가나다" 중 "가" = {from: 0, to: 0} (기본값: 전체 텍스트)
8816
+ * @param range - 교체할 텍스트 구간 to = from + 글자수 - 1 (0-based) 예: "가나다" 전체 = {from: 0, to: 2}, "가나다" 중 "가" = {from: 0, to: 0} offset 은 UTF-16 코드 단위라 서로게이트 페어를 가르는 range 는 반쪽이 아니라 그 글자 전체가 대상이 된다 (range 를 받는 서식 setter 도 같다) (기본값: 전체 텍스트)
8832
8817
  */
8833
- setText(text: string, range?: {
8834
- from: number;
8835
- to: number;
8836
- }): Promise<void>;
8818
+ setText(text: string, range?: TextRange): Promise<void>;
8837
8819
  /**
8838
8820
  * 텍스트를 삽입한다.
8839
8821
  * 삽입한 글자의 서식은 삽입 지점 바로 앞 글자의 런 서식을 따른다.
@@ -8848,101 +8830,71 @@ declare namespace Show {
8848
8830
  * @param style - 글꼴 스타일 설정
8849
8831
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8850
8832
  */
8851
- setFontStyle(style: FontStyle, range?: {
8852
- from: number;
8853
- to: number;
8854
- }): Promise<void>;
8833
+ setFontStyle(style: FontStyle, range?: TextRange): Promise<void>;
8855
8834
  /**
8856
- * 글자 굵게 설정.
8835
+ * 글자를 굵게 설정한다.
8857
8836
  *
8858
8837
  * @param enabled - true: 굵게, false: 해제
8859
8838
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8860
8839
  */
8861
- setBold(enabled: boolean, range?: {
8862
- from: number;
8863
- to: number;
8864
- }): Promise<void>;
8840
+ setBold(enabled: boolean, range?: TextRange): Promise<void>;
8865
8841
  /**
8866
- * 글자 기울임 설정.
8842
+ * 글자 기울임을 설정한다.
8867
8843
  *
8868
8844
  * @param enabled - true: 기울임, false: 해제
8869
8845
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8870
8846
  */
8871
- setItalic(enabled: boolean, range?: {
8872
- from: number;
8873
- to: number;
8874
- }): Promise<void>;
8847
+ setItalic(enabled: boolean, range?: TextRange): Promise<void>;
8875
8848
  /**
8876
- * 글자 밑줄 설정.
8849
+ * 글자 밑줄을 설정한다.
8877
8850
  *
8878
8851
  * @param underline - 밑줄 유형
8879
8852
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8880
8853
  */
8881
- setUnderline(underline: Underline, range?: {
8882
- from: number;
8883
- to: number;
8884
- }): Promise<void>;
8854
+ setUnderline(underline: Underline, range?: TextRange): Promise<void>;
8885
8855
  /**
8886
- * 글자 취소선 설정.
8856
+ * 글자 취소선을 설정한다.
8887
8857
  *
8888
8858
  * @param strike - 취소선 유형
8889
8859
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8890
8860
  */
8891
- setStrike(strike: Strike, range?: {
8892
- from: number;
8893
- to: number;
8894
- }): Promise<void>;
8861
+ setStrike(strike: Strike, range?: TextRange): Promise<void>;
8895
8862
  /**
8896
- * 글자 크기 설정.
8863
+ * 글자 크기를 설정한다.
8897
8864
  *
8898
8865
  * @param fontSize - pt 단위
8899
8866
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8900
8867
  */
8901
- setFontSize(fontSize: number, range?: {
8902
- from: number;
8903
- to: number;
8904
- }): Promise<void>;
8868
+ setFontSize(fontSize: number, range?: TextRange): Promise<void>;
8905
8869
  /**
8906
- * 글꼴 설정.
8870
+ * 글꼴을 설정한다.
8907
8871
  *
8908
8872
  * @param fontFamily - 글꼴 이름
8909
8873
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8910
8874
  */
8911
- setFontFamily(fontFamily: string, range?: {
8912
- from: number;
8913
- to: number;
8914
- }): Promise<void>;
8875
+ setFontFamily(fontFamily: string, range?: TextRange): Promise<void>;
8915
8876
  /**
8916
- * 글자 색상 설정.
8877
+ * 글자 색상을 설정한다.
8917
8878
  *
8918
8879
  * @param color - hex (#RRGGBB) 또는 scheme color
8919
8880
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8920
8881
  */
8921
- setTextColor(color: string, range?: {
8922
- from: number;
8923
- to: number;
8924
- }): Promise<void>;
8882
+ setTextColor(color: string, range?: TextRange): Promise<void>;
8925
8883
  /**
8926
8884
  * 텍스트에 하이퍼링크를 설정한다. (getTextHyperlink 대칭 — 반환 객체를 그대로 넘겨 링크를 복사할 수 있다)
8927
- * 도형 전체에 링크를 거는 setHyperlink 와 달리 글자(run)에 걸려 하이퍼링크 서식으로 표시된다.
8928
- * other(program/macro/ole 등)와 유효하지 않은 대상(없는 슬라이드 id·ShowJumpType 밖의 값)은 무시한다.
8885
+ * 도형 전체에 링크를 거는 setHyperlink 와 달리 링크가 글자(run) 단위로 걸리며 하이퍼링크 서식으로 표시된다.
8886
+ * 지원하지 않는 종류나 유효하지 않은 대상(없는 슬라이드 id 등)은 무시한다.
8929
8887
  *
8930
- * @param hyperlink - getTextHyperlink() 반환값 (baseShape 의 Hyperlink). type 이 없으면 무시한다
8888
+ * @param hyperlink - getTextHyperlink() 반환값과 같은 Hyperlink 객체. type 이 없으면 무시한다
8931
8889
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8932
8890
  */
8933
- setTextHyperlink(hyperlink: Hyperlink, range?: {
8934
- from: number;
8935
- to: number;
8936
- }): Promise<void>;
8891
+ setTextHyperlink(hyperlink: Hyperlink, range?: TextRange): Promise<void>;
8937
8892
  /**
8938
8893
  * 텍스트의 하이퍼링크를 제거한다. (도형 자체에 걸린 하이퍼링크는 removeHyperlink)
8939
8894
  *
8940
8895
  * @param range - 제거할 텍스트 구간 (기본값: 전체 텍스트)
8941
8896
  */
8942
- removeTextHyperlink(range?: {
8943
- from: number;
8944
- to: number;
8945
- }): Promise<void>;
8897
+ removeTextHyperlink(range?: TextRange): Promise<void>;
8946
8898
  /**
8947
8899
  * 지정한 offset 위치에 특수문자(symbol)를 삽입한다.
8948
8900
  *
@@ -8956,114 +8908,87 @@ declare namespace Show {
8956
8908
  * @param align - 가로 정렬
8957
8909
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8958
8910
  */
8959
- setAlignH(align: TextAlignH, range?: {
8960
- from: number;
8961
- to: number;
8962
- }): Promise<void>;
8911
+ setAlignH(align: TextAlignH, range?: TextRange): Promise<void>;
8963
8912
  /**
8964
8913
  * 단락 서식을 한 번에 설정한다. range 를 주면 그 구간이 걸친 단락에만 적용한다.
8965
- * 문단 모양 대화상자의 입력 항목과 1:1 로 대응하며, 대화상자와 같이 한 액션으로 적용해 실행 취소 단위가 하나다.
8966
8914
  * 값을 준 속성만 바뀐다. null/undefined 는 "변경 없음"으로 무시하며, 지정한 값을 상속 상태로 되돌리는 방법은 아직 없다.
8967
8915
  * 단일 속성은 setLineSpacing/setMarginLeft/setFirstLineIndent/setSpaceBefore/setSpaceAfter 사용 권장.
8968
- * 목록 수준은 부수 효과(글머리 기호·글자 크기)가 달라 여기 담지 않는다. (setLevel 참고)
8969
- * alignH 만 별도 액션(setAlignH)으로 나가므로 다른 속성과 함께 주면 실행 취소 단위가 2개로 나뉜다.
8916
+ * 목록 수준은 바꿀 때 딸려오는 부수 효과(글머리 기호·글자 크기)가 있어 여기 담지 않는다. (setLevel 참고)
8970
8917
  *
8971
8918
  * @param style - 단락 서식 설정
8972
8919
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8973
8920
  */
8974
- setParagraphStyle(style: ParagraphStyle, range?: {
8975
- from: number;
8976
- to: number;
8977
- }): Promise<void>;
8921
+ setParagraphStyle(style: ParagraphStyle, range?: TextRange): Promise<void>;
8978
8922
  /**
8979
8923
  * 줄 간격을 설정한다. range 를 주면 그 구간이 걸친 단락에만 적용한다.
8980
- * MULTIPLE 이면 "100%" 형태, EXACT 이면 pt 입력을 twip view 값으로 변환한다
8924
+ * lineSpacing 의 단위는 유형에 따라 다르다 - MULTIPLE 이면 배수 백분율(150=1.5배), EXACT 이면 pt 다.
8981
8925
  *
8982
8926
  * @param lineSpacing - 줄 간격 값 (MULTIPLE: 배수%, EXACT: pt)
8983
8927
  * @param type - 줄 간격 유형 (기본값: LineSpacingType.MULTIPLE)
8984
8928
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8985
8929
  */
8986
- setLineSpacing(lineSpacing: number, type?: LineSpacingType, range?: {
8987
- from: number;
8988
- to: number;
8989
- }): Promise<void>;
8930
+ setLineSpacing(lineSpacing: number, type?: LineSpacingType, range?: TextRange): Promise<void>;
8990
8931
  /**
8991
8932
  * 단락 앞 간격(UI "문단 위")을 설정한다.
8992
8933
  *
8993
8934
  * @param spaceBefore - 단락 앞 간격 (pt)
8994
8935
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8995
8936
  */
8996
- setSpaceBefore(spaceBefore: number, range?: {
8997
- from: number;
8998
- to: number;
8999
- }): Promise<void>;
8937
+ setSpaceBefore(spaceBefore: number, range?: TextRange): Promise<void>;
9000
8938
  /**
9001
8939
  * 단락 뒤 간격(UI "문단 아래")을 설정한다.
9002
8940
  *
9003
8941
  * @param spaceAfter - 단락 뒤 간격 (pt)
9004
8942
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
9005
8943
  */
9006
- setSpaceAfter(spaceAfter: number, range?: {
9007
- from: number;
9008
- to: number;
9009
- }): Promise<void>;
8944
+ setSpaceAfter(spaceAfter: number, range?: TextRange): Promise<void>;
9010
8945
  /**
9011
- * 단락 전체의 왼쪽 여백(UI "텍스트 앞")을 설정한다. 첫 줄만 밀려면 setFirstLineIndent 를 쓴다.
8946
+ * 단락 전체의 왼쪽 여백(UI "텍스트 앞")을 설정한다. 첫 줄만 들여쓰려면 setFirstLineIndent 를 사용한다.
9012
8947
  *
9013
8948
  * @param marginLeft - 왼쪽 여백 (pt)
9014
8949
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
9015
8950
  */
9016
- setMarginLeft(marginLeft: number, range?: {
9017
- from: number;
9018
- to: number;
9019
- }): Promise<void>;
8951
+ setMarginLeft(marginLeft: number, range?: TextRange): Promise<void>;
9020
8952
  /**
9021
8953
  * 단락 첫 줄의 들여쓰기(UI "첫 줄")를 설정한다. 둘째 줄부터는 marginLeft 를 따른다.
9022
- * 양수는 들여쓰기, 음수는 내어쓰기, 0 은 없음이다. (UI 의 없음/들여쓰기/내어쓰기 구분을 부호 하나로 표현한다)
9023
- * 글머리 기호 목록의 계층 깊이를 바꾸려는 것이면 setLevel 이다.
8954
+ * 양수는 들여쓰기, 음수는 내어쓰기, 0 은 들여쓰기 없음이다.
8955
+ * 글머리 기호 목록의 계층 깊이를 바꾸려면 setLevel 을 사용한다.
9024
8956
  *
9025
8957
  * @param firstLineIndent - 첫 줄 들여쓰기 (pt)
9026
8958
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
9027
8959
  */
9028
- setFirstLineIndent(firstLineIndent: number, range?: {
9029
- from: number;
9030
- to: number;
9031
- }): Promise<void>;
8960
+ setFirstLineIndent(firstLineIndent: number, range?: TextRange): Promise<void>;
9032
8961
  /**
9033
8962
  * 목록 수준(개요 계층 깊이)을 설정한다. range 가 걸친 단락을 모두 같은 수준으로 맞춘다.
9034
8963
  * pt 단위 들여쓰기(setFirstLineIndent/setMarginLeft)와 달리 수준은 상속 프리셋 선택이라,
9035
- * 바꾸면 그 수준의 글머리 기호와 글자 크기가 함께 따라온다.
9036
- * marginLeft 는 새 수준의 값으로 덮인다. setMarginLeft 로 지정한 값도 버려지므로
9037
- * 둘을 함께 쓸 때는 setLevel 을 먼저 호출한다. (firstLineIndent 는 유지된다)
9038
- * 대상 텍스트가 허용하는 범위(제목 개체는 1 단계뿐)로 clamp 한다.
8964
+ * 바꾸면 그 수준의 글머리 기호·글자 크기가 따라오고 marginLeft 는 새 수준의 값으로 덮인다.
8965
+ * setMarginLeft 로 지정한 값도 버려지므로 둘을 함께 쓸 때는 setLevel 을 먼저 호출한다. (firstLineIndent 는 유지)
8966
+ * 대상 텍스트가 허용하는 범위(제목 개체는 1 수준뿐)로 제한한다.
9039
8967
  *
9040
8968
  * @param level - 목록 수준 (1=최상위 ~ 9)
9041
8969
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
9042
8970
  */
9043
- setLevel(level: number, range?: {
9044
- from: number;
9045
- to: number;
9046
- }): Promise<void>;
8971
+ setLevel(level: number, range?: TextRange): Promise<void>;
9047
8972
  /**
9048
- * 글머리 기호 스타일을 설정한다.
8973
+ * 글머리 기호 스타일을 설정한다. (getBulletStyle 대칭)
8974
+ * 그림 글머리(BulletType.BLIP)는 적용을 지원하지 않는 조회 전용 유형이라 거부한다.
8975
+ * CharType 프리셋 밖의 문자도 적용할 수 없다 (조회 전용이라 받을 인자가 없다).
9049
8976
  *
9050
8977
  * @param bulletType - 글머리 기호 유형
9051
8978
  * @param subType - BulletType.AUTO_NUM: 번호 매기기 유형 (기본값 NumberedType.NUMBER_WITH_DOT), BulletType.CHAR: 글머리 문자 유형 (기본값 CharType.DOT)
9052
8979
  * @param startAt - 시작 번호 (BulletType.AUTO_NUM 일 때만 사용) (기본값: 1)
9053
8980
  * @param range - 적용할 텍스트 구간 (기본값: 전체 텍스트)
8981
+ * @throws {Error} bulletType 이 BulletType.BLIP(미지원 타입)이거나 subType 이 bulletType 의 값 집합 밖인 경우 (error.code = "INVALID_ARGUMENT")
9054
8982
  */
9055
- setBulletStyle(bulletType: BulletType, subType?: NumberedType | CharType, startAt?: number, range?: {
9056
- from: number;
9057
- to: number;
9058
- }): Promise<void>;
8983
+ setBulletStyle(bulletType: Exclude<BulletType, "buBlip">, subType?: NumberedType | CharType, startAt?: number, range?: TextRange): Promise<void>;
9059
8984
  /**
9060
- * 텍스트 세로 정렬을 설정한다.
8985
+ * 텍스트 세로 정렬을 설정한다. (getAlignV 대칭)
9061
8986
  *
9062
8987
  * @param align - 세로 정렬
9063
8988
  */
9064
8989
  setAlignV(align: TextAlignV): Promise<void>;
9065
8990
  /**
9066
- * 텍스트 상자 자동 맞춤 유형을 설정한다.
8991
+ * 텍스트 상자 자동 맞춤 유형을 설정한다. 이미 같은 유형이면 아무것도 하지 않는다.
9067
8992
  *
9068
8993
  * @param autoAlignType - 자동 맞춤 유형
9069
8994
  */
@@ -9080,22 +9005,35 @@ declare namespace Show {
9080
9005
  * @returns 열 인덱스 (0-based)
9081
9006
  */
9082
9007
  getColIndex(): Promise<number>;
9008
+ /**
9009
+ * 셀이 가로로 차지하는 열 수를 반환한다. 병합되지 않았으면 1 이다.
9010
+ *
9011
+ * @returns 열 병합 수. 표가 없거나 해당 위치에 셀이 없으면 null
9012
+ */
9013
+ getColSpan(): Promise<number | null>;
9014
+ /**
9015
+ * 셀이 세로로 차지하는 행 수를 반환한다. 병합되지 않았으면 1 이다.
9016
+ *
9017
+ * @returns 행 병합 수. 표가 없거나 해당 위치에 셀이 없으면 null
9018
+ */
9019
+ getRowSpan(): Promise<number | null>;
9083
9020
  /**
9084
9021
  * 셀에 명시적으로 설정된 배경 채우기를 반환한다. (setSolidFill 대칭)
9085
- * 스타일 상속분은 포함하지 않으며(tcPr 에 명시된 fill 만), alpha 는 setSolidFill 과 동일한
9086
- * 투명도(0~100, 0=불투명)로 역변환되어 반환된다.
9022
+ * 스타일 상속분은 포함하지 않으며(셀에 직접 지정한 채우기만), alpha 는 setSolidFill 과 같은
9023
+ * 투명도(0~100, 0=불투명)로 반환한다.
9087
9024
  *
9088
- * @returns 채우기 정보. 명시적 fill 없으면 `{ type: FillType.NONE }`, 표 모델 없음(stale)이면 null
9025
+ * @returns 채우기 정보. 명시적 fill 없으면 `{ type: FillType.NONE }`, 표가 없으면 null
9089
9026
  */
9090
9027
  getFill(): Promise<Fill | null>;
9091
9028
  /**
9092
9029
  * 지정 위치의 셀 테두리 스타일을 반환한다. (setBorderStyle 대칭)
9093
- * 해당 위치에 명시적 테두리가 없으면 null. ALL 등 복수 위치는 조회 미지원(null).
9030
+ * ALL 일괄 조회는 지원하지 않는다 - 한 변씩 조회한다.
9094
9031
  *
9095
- * @param position - 테두리 위치 (TOP/BOTTOM/LEFT/RIGHT/DIAGONAL_DOWN/DIAGONAL_UP)
9096
- * @returns 테두리 스타일. 없으면 null
9032
+ * @param position - 테두리 위치
9033
+ * @returns 테두리 스타일. 해당 위치에 명시적 테두리가 없으면 null
9034
+ * @throws {Error} position 이 BorderPosition.ALL(조회 미지원)인 경우 (error.code = "INVALID_ARGUMENT")
9097
9035
  */
9098
- getBorderStyle(position: BorderPosition): Promise<BorderStyle | null>;
9036
+ getBorderStyle(position: Exclude<BorderPosition, "all">): Promise<BorderStyle | null>;
9099
9037
  /**
9100
9038
  * 셀 안의 모든 텍스트를 제거한다.
9101
9039
  */
@@ -9104,24 +9042,28 @@ declare namespace Show {
9104
9042
  * 셀 배경을 단색으로 채운다.
9105
9043
  *
9106
9044
  * @param color - hex (#RRGGBB) 또는 scheme color
9107
- * @param alpha - 투명도 (0~100, 100=완전 투명) (기본값: 0(불투명))
9045
+ * @param alpha - 투명도 (0~100, 0=불투명, 100=완전 투명). 생략하면 기존 투명도 유지
9108
9046
  */
9109
9047
  setSolidFill(color: string, alpha?: number): Promise<void>;
9110
9048
  /**
9111
9049
  * getFill() 이 반환한 채우기 객체를 그대로 적용한다. (getFill 대칭 — 셀 채우기 복사)
9112
- * 셀은 단색만 지원하므로 solid 만 적용하고 gradient/image/pattern/none 은 무시한다.
9050
+ * 셀 채우기 설정은 단색만 지원한다 — getFill() 이 다른 타입(none/gradient 등)을 돌려준 셀의 값은 되넘길 수 없다.
9113
9051
  *
9114
- * @param fill - getFill() 반환값
9052
+ * @param fill - 적용할 단색 채우기
9053
+ * @throws {Error} fill.type 이 solid 가 아닌 경우 (error.code = "INVALID_ARGUMENT")
9115
9054
  */
9116
- setFill(fill: Fill): Promise<void>;
9055
+ setFill(fill: Fill & {
9056
+ type: "solidFill";
9057
+ }): Promise<void>;
9117
9058
  /**
9118
- * 셀 테두리 스타일을 설정한다. color/width/lineDash 를 모두 생략하면 아무 것도 변경하지 않는다.
9119
- * 색상은 hex / scheme color 모두 ValueMapper.colorToFillObj 가 자동 판정.
9059
+ * 셀 테두리 스타일을 설정한다. 생략한 속성은 유지되지 않고 기본값이 되므로, 일부만 바꾸려면
9060
+ * getBorderStyle() 반환값에 바꿀 속성을 덮어 함께 넘긴다. 셋을 모두 생략하면 아무것도 바꾸지 않는다.
9061
+ * ALL 은 위/아래/왼쪽/오른쪽 4변만 설정한다 - 대각선은 포함하지 않는다. 색상은 hex / scheme color 모두 자동 판정.
9120
9062
  *
9121
9063
  * @param position - 테두리 위치
9122
- * @param color - hex (#RRGGBB) 또는 scheme color name (기본값: 기존 값 유지)
9123
- * @param width - 선 두께 (pt 단위) (기본값: 기존 값 유지)
9124
- * @param lineDash - 선 대시 유형 (기본값: 기존 값 유지)
9064
+ * @param color - hex (#RRGGBB) 또는 scheme color name
9065
+ * @param width - 선 두께 (pt 단위)
9066
+ * @param lineDash - 선 대시 유형
9125
9067
  */
9126
9068
  setBorderStyle(position: BorderPosition, color?: string, width?: number, lineDash?: LineDash): Promise<void>;
9127
9069
  }