UNPKG

@ckeditor/ckeditor5-utils

Version:

Miscellaneous utilities used by CKEditor 5.

ckeditor.com/ckeditor-5

ckeditor/ckeditor5

74 lines (73 loc) • 5.19 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
/** * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options */ type IfTrue<T> = T extends true ? true : never; /** * Makes any page `HTMLElement` or `Range` (`target`) visible inside the browser viewport. * This helper will scroll all `target` ancestors and the web browser viewport to reveal the target to * the user. If the `target` is already visible, nothing will happen. * * @param options Additional configuration of the scrolling behavior. * @param options.target A target, which supposed to become visible to the user. * @param options.viewportOffset An offset from the edge of the viewport (in pixels) * the `target` will be moved by if the viewport is scrolled. It enhances the user experience * by keeping the `target` some distance from the edge of the viewport and thus making it easier to * read or edit by the user. * @param options.ancestorOffset An offset from the boundary of scrollable ancestors (if any) * the `target` will be moved by if the viewport is scrolled. It enhances the user experience * by keeping the `target` some distance from the edge of the ancestors and thus making it easier to * read or edit by the user. * @param options.alignToTop When set `true`, the helper will make sure the `target` is scrolled up * to the top boundary of the viewport and/or scrollable ancestors if scrolled up. When not set * (default), the `target` will be revealed by scrolling as little as possible. This option will * not affect `targets` that must be scrolled down because they will appear at the top of the boundary * anyway. * * ``` * scrollViewportToShowTarget() with scrollViewportToShowTarget() with * Initial state alignToTop unset (default) alignToTop = true * * ┌────────────────────────────────┬─┐ ┌────────────────────────────────┬─┐ ┌────────────────────────────────┬─┐ * │ │▲│ │ │▲│ │ [ Target to be revealed ] │▲│ * │ │ │ │ │ │ │ │ │ * │ │█│ │ │ │ │ │ │ * │ │█│ │ │ │ │ │ │ * │ │ │ │ │█│ │ │ │ * │ │ │ │ │█│ │ │█│ * │ │ │ │ │ │ │ │█│ * │ │▼│ │ [ Target to be revealed ] │▼│ │ │▼│ * └────────────────────────────────┴─┘ └────────────────────────────────┴─┘ └────────────────────────────────┴─┘ * * * [ Target to be revealed ] *``` * * @param options.forceScroll When set `true`, the `target` will be aligned to the top of the viewport * and scrollable ancestors whether it is already visible or not. This option will only work when `alignToTop` * is `true` */ export declare function scrollViewportToShowTarget<T extends boolean, U extends IfTrue<T>>({ target, viewportOffset, ancestorOffset, alignToTop, forceScroll }: { readonly target: HTMLElement | Range; readonly viewportOffset?: number | { top: number; bottom: number; left: number; right: number; }; readonly ancestorOffset?: number; readonly alignToTop?: T; readonly forceScroll?: U; }): void; /** * Makes any page `HTMLElement` or `Range` (target) visible within its scrollable ancestors, * e.g. if they have `overflow: scroll` CSS style. * * @param target A target, which supposed to become visible to the user. * @param ancestorOffset An offset between the target and the boundary of scrollable ancestors * to be maintained while scrolling. * @param limiterElement The outermost ancestor that should be scrolled. If specified, it can prevent * scrolling the whole page. */ export declare function scrollAncestorsToShowTarget(target: HTMLElement | Range, ancestorOffset?: number, limiterElement?: HTMLElement): void; export {};