Google Docs plans to switch to canvas based rendering instead of HTML based rendering. Expected date is around the end of July 2021.
This library relies on HTML based rendering. It is means that all existing functionality will stop working with new canvas based rendering. Highly unlikely that all existing functionality will be adopted to canvas based rendering.
See #10 for more.
See this for temporary workaround.
Utilities for interaction with Google Docs using JavaScript.
Google Docs uses its own complex logic for displaying, storing and handling of page elements. It is good for ensuring that across many different browsers the editor is working as expected, but it makes hard to interact with document programmatically.
Examples:
window.getSelection() to get selected text. Google Docs creates two independent elements: one for text and one for selection overlay. Any events for normal selection will be canceled by Google Docs.element.textContent = 'newText', because Google Docs stores current editor state internally. So, autosaving will be not triggered. Also, on further user typing, previous text will be restored while newText will be removed.element.innerText.length will give different result than you expect because Google Docs adds special symbols (NBSP, ZWNJ) to display text correctly across different browsers.Why do you need to handle such nuances by yourself when you can just use already working solutions? So, it is what it for.
npm:npm install google-docs-utilsyarn:yarn add google-docs-utilsUse these CDN links:
https://unpkg.com/google-docs-utils@latest/dist/iife/index.jshttps://unpkg.com/google-docs-utils@latest/dist/iife/index.min.jsThen access this library via GoogleDocsUtils global variable.
// load all methods
const GoogleDocsUtils = require('google-docs-utils');
// using ES6
import * as GoogleDocsUtils from 'google-docs-utils';
// load specific methods
import {getSelection} from 'google-docs-utils';GoogleDocsUtils global variable will be created when you load this library. Access the methods via this variable.
Example:
GoogleDocsUtils.getSelection();You can load the script using any way you like. For example, you can manually load this library through developer console:
var script = document.createElement('script');
script.type = 'text/javascript';
script.src = 'https://unpkg.com/google-docs-utils@latest/dist/iife/index.js';
document.head.appendChild(script);GoogleDocsUtils.getEditorElement(): HTMLElement;Returns current active editor element. You may consider it as a root element. It contains only editor itself, not control bar and other elements.
GoogleDocsUtils.getPagesElements(): HTMLElement[];Returns all rendered editor pages.
GoogleDocsUtils.getLinesElements(): HTMLElement[];Returns all lines of all rendered editor pages. Note that it also contains header lines of every page. So, GoogleDocsUtils.getLinesElements()[0] results to header line of first page, and GoogleDocsUtils.getLinesElements()[1] results to first line of first page.
GoogleDocsUtils.getLinesTextElements(): HTMLElement[];Returns all text elements of all rendered editor pages. Note that it also contains header text elements of every page, even if header is empty.
GoogleDocsUtils.getLinesText(): string[];Returns text content of every line of all rendered pages. If line is empty, then empty string will be used as a value for that line.
GoogleDocsUtils.getLineText(lineIndex, [startIndex], [endIndex]): string | null;Returns text of specific line.
lineIndex
truenumberIndex of specific line, which starts from 0. Note that it also points to header lines. So, for example, 0 points to header line of first page, and 1 points to first line of first page.
If lineIndex is greater than total count of all rendered lines, then null will be returned instead of string.
startIndex
falsenumberundefinedStart index for substring(). If not specified, then start of line is assumed.
endIndex
falsenumberundefinedEnd index for substring(). If not specified, then end of line is assumed.
GoogleDocsUtils.getWordElements(): Array<HTMLElement[]>;Returns all nodes of all rendered lines which contains actual text of line. There is no point to change text of line through textContent or innerText, because these changes will be not recognized correctly.
[] - represents line, [][] - represents all word nodes of that line.
If text of line contains various formatting (font, bold, etc.), then it will be splitted into several word nodes. For example, "some [Arial font] text [Roboto font]" will be splitted into two nodes, "some text [Arial font]" will be represented as one node and "another [Arial font, normal] text [Arial font, bold]" will be splitted into two nodes.
GoogleDocsUtils.getSelectionOverlayElements(): Array<HTMLElement | null>;Returns all selection overlay elements of all rendered lines. If there are no selection for some line, then null will be used as a value for that line. Don't remove this element manually, because these DOM changes will be not recognized by Google Docs correctly.
GoogleDocsUtils.getSelection(): Array<null | Array<GetSelectionResult | null>>;Returns data about selection for every rendered line. Note that header line is also included in returned array.
If line not selected at all, then [] will be equal to null, otherwise it will be an array that describes selection of all word nodes (see getWordElements() documentation for more). [][] will be equal to null if that word node not part of selection, otherwise it will be an object that describes selection of that word node.
SelectionData.text
stringOriginal text of word node.
SelectionData.selectedText
stringSelected text.
SelectionData.selectionStart
numberIndex where selection starts. It can be used for substring(). It is relative to word node, not entire line.
SelectionData.selectionEnd
numberIndex where selection ends. It can be used for substring(). It is relative to word node, not entire line.
SelectionData.textElement
HTMLElementHTML element which contains actual text.
SelectionData.selectionElement
HTMLElementHTML element which contains selection overlay element. Every not empty [][] will have same selectionElement.
SelectionData.textRect
DOMRectReadOnlyDOMRect of textElement.
SelectionData.selectionRect
DOMRectReadOnlyDOMRect of selectionElement. Every not empty [][] will have same selectionRect.
GoogleDocsUtils.getCursorElement(): HTMLElement;Returns cursor element.
GoogleDocsUtils.getActiveCursorElement(): HTMLElement | null;Returns active cursor element. "Active" means page is focused (cursor is blinking). null will be returned if cursor is not active.
GoogleDocsUtils.getCaretElement(): HTMLElement;Returns caret element.
GoogleDocsUtils.getCaret(): CaretData;Returns data about caret.
CaretData.element
HTMLElementCaret element.
CaretData.wordElement
HTMLElementElement which contains text of line on which caret is placed.
CaretData.lineIndex
numberGlobal index of line.
CaretData.positionIndexRelativeToWord
numberBefore what letter caret is placed. For example, caret is placed before w letter in one two three text. positionIndexRelativeToWord will be equal to 5 in that case.
This index relates to word node, not entire line. For example, if line contains two words with different fonts, then there will be two word nodes.
GoogleDocsUtils.getCaretWord(): CaretWordData;Returns data about word on which caret is currently placed.
Note that this method will not work with languages which doesn't have upper and lower symbols. For example: Chinese, Japanese, Arabic, Hebrew, etc.
CaretWordData.word
stringFull word on which caret is placed.
CaretWordData.text
stringFull text of line on which caret is placed.
CaretWordData.indexStart
numberOn which index word starts in text. Can be used for substring().
CaretWordData.indexEnd
numberOn which index word ends in text. Can be used for substring().
GoogleDocsUtils.getTextEventTarget(): HTMLElement | Document;This element can be used to interact with text events, in particular with keyboard events (keyup, keydown, keypress). You can dispatch text events to that element and add event listeners to that element:
GoogleDocsUtils.getTextEventTarget().dispatchEvent()GoogleDocsUtils.getTextEventTarget().addEventListener()You can't just interact with current document, because Google Docs uses separate element (iframe at the moment) to handle keyboard events. This element is always active (document.activeElement), and all text events will be handled by that element.
Note that you can't interact with other events. For example, with mouse events. You also can't interact with selection events, because Google Docs implemented its own selection mechanism. Use getSelection instead.
GoogleDocsUtils.clearTextContent(text): string;Clears text that was extracted using textContent or innerText. It is important to handle extracted text, because it may contain special invisible symbols like ZWNJ or NBSP - these symbols will lead to unexpected result.
text
truestringRaw text of line that was extracted using textContent or innerText.
GoogleDocsUtils.addEventListener(type: string, listener: (event: GoogleDocsEvent) => any): void;Sets up a function that will be called whenever the specified event will occur.
type
Case-sensitive type of event. See below documentation for all possible events.
listener
Callback function. There can be many functions for single event. Order of calling is same as order of adding. On call every function will receive event details as argument.
GoogleDocsEvent.type
The name of the event. Case-insensitive.
This event is fired when the current text selection on a document is changed.
This namespace provides methods to imitate physical single key press. You can use this to interact with current editor content: clear current selection using Delete key, delete current character using Backspace key, move on new line using Enter key, etc.
Some methods can accept on/off status of modificator keys (Ctrl, Shift, etc). Not every method support it, so, if it is present, then modificator with true provides different behavior than with false. By default all modificators are disabled.
If this default typing system not suits for you, you still can implement your own typing system - just send keyboard events to getTextEventTarget.
This namespace provides following methods:
GoogleDocsUtils.pressOn.Character(
char,
{
ctrlKey = false,
shiftKey = false
} = {}
): void;char
truestringSingle character to press on. Case sensitive.
GoogleDocsUtils.pressOn.Space(): void;GoogleDocsUtils.pressOn.Delete(
{
ctrlKey = false
} = {}
): void;Difference between Delete and Backspace is matters.
GoogleDocsUtils.pressOn.Backspace(
{
ctrlKey = false
} = {}
): void;Difference between Delete and Backspace is matters.
GoogleDocsUtils.pressOn.Enter(): void;GoogleDocsUtils.pressOn.Tab(): void;GoogleDocsUtils.pressOn.ArrowLeft(
{
ctrlKey = false,
shiftKey = false
} = {}
): void;GoogleDocsUtils.pressOn.ArrowRight(
{
ctrlKey = false,
shiftKey = false
} = {}
): void;GoogleDocsUtils.pressOn.ArrowUp(
{
ctrlKey = false,
shiftKey = false
} = {}
): void;GoogleDocsUtils.pressOn.ArrowDown(
{
ctrlKey = false,
shiftKey = false
} = {}
): void;GoogleDocsUtils.pressOn.Home(
{
ctrlKey = false,
shiftKey = false
} = {}
): void;GoogleDocsUtils.pressOn.End(
{
ctrlKey = false,
shiftKey = false
} = {}
): void;GoogleDocsUtils.pressOn.Undo(): void;GoogleDocsUtils.pressOn.Redo(): void;GoogleDocsUtils.pressOn.Bold(): void;GoogleDocsUtils.pressOn.Italic(): void;GoogleDocsUtils.pressOn.Underline(): void;GoogleDocsUtils.pressOn.PrintDialog(): void;GoogleDocsUtils.typeText(text): void;Types provided text character by character at current caret position. Imitates physical key press events. Can take a long time to type long text. Uses default pressOn.
text
truestringText to type.
GoogleDocsUtils.isTextSelected(): boolean;Returns status that indicates if text selection is exists on either single or multiple lines.
GoogleDocsUtils.isDocumentActive(): boolean;Returns status that indicates if document is in active state. Active state means that document is focused (cursor is blinked).
GoogleDocsUtils.focusDocument(): boolean;Focuses on current document. "Focus" means that document is active and available for editing: cursor is blinking or selection active.
Returns true if there was any actions to perform a focus, otherwise false if document already was active and nothing was performed.
This namespace provides methods to remove different document objects (text, selection, etc).
GoogleDocsUtils.remove.PrevWord(): void;Removes word according to the following logic:
GoogleDocsUtils.remove.NextWord(): void;Removes word according to the following logic:
GoogleDocsUtils.remove.Selection(): boolean;Removes current selection. Returns true if selection was removed, otherwise returns false if nothing to remove (because nothing is selected).
This namespace provides methods to move cursor over document.
GoogleDocsUtils.moveCursorTo.PrevCharacter(): void;Moves cursor to character that is placed to the left of current cursor position. If that character placed on previous line, then previous line will be used.
GoogleDocsUtils.moveCursorTo.NextCharacter(): void;Moves cursor to character that is placed to the right of current cursor position. If that character placed on next line, then next line will be used.
GoogleDocsUtils.moveCursorTo.PrevLine(): void;Moves cursor to the previous line and tries to keep cursor position. If there is no previous line, then moves cursor to the start of current paragraph.
GoogleDocsUtils.moveCursorTo.NextLine(): void;Moves cursor to the next line and tries to keep cursor position. If there is no next line, then moves cursor to the end of current paragraph.
GoogleDocsUtils.moveCursorTo.PrevWord(): void;Moves cursor to word according to the following logic:
GoogleDocsUtils.moveCursorTo.NextWord(): void;Moves cursor to word according to the following logic:
GoogleDocsUtils.moveCursorTo.PrevParagraph(): void;Moves cursor to paragraph according to the following logic:
GoogleDocsUtils.moveCursorTo.NextParagraph(): void;Moves cursor to paragraph according to the following logic:
GoogleDocsUtils.moveCursorTo.LineStart(): void;Moves cursor to the start of current line.
GoogleDocsUtils.moveCursorTo.LineEnd(): void;Moves cursor to the start of current line.
GoogleDocsUtils.moveCursorTo.DocumentStart(): void;Moves cursor to the start of document.
GoogleDocsUtils.moveCursorTo.DocumentEnd(): void;Moves cursor to the end of document.
This namespace provides methods to select text content in document.
GoogleDocsUtils.select.All(): void;Selects text of entire document.
GoogleDocsUtils.select.PrevCharacter(): void;Selects a character that is placed to the left of current cursor position. Following logic will be used, with priority of actions from top to bottom:
GoogleDocsUtils.select.NextCharacter(): void;Selects a character that is placed to the right of current cursor position. Following logic will be used, with priority of actions from top to bottom:
GoogleDocsUtils.select.PrevWord(): void;Same as PrevCharacter, but performs an action with word.
GoogleDocsUtils.select.NextWord(): void;Same as NextCharacter, but performs an action with word.
GoogleDocsUtils.select.PrevLine(): void;Selects N number of characters to the left where N is a max length of line.
GoogleDocsUtils.select.NextLine(): void;Same as PrevLine, but uses right direction.
GoogleDocsUtils.select.PrevParagraph(): void;Selects a paragraph that is placed to the left of current cursor position. Following logic will be used, with priority of actions from top to bottom:
GoogleDocsUtils.select.NextParagraph(): void;Selects a paragraph that is placed to the right of current cursor position. Following logic will be used, with priority of actions from top to bottom:
GoogleDocsUtils.select.TextBetweenCursorAndLineStart(): void;Selects a text between current cursor position and current line start.
GoogleDocsUtils.select.TextBetweenCursorAndLineEnd(): void;Same as TextBetweenCursorAndLineStart, but interacts with current line end.
GoogleDocsUtils.select.TextBetweenCursorAndDocumentStart(): void;Same as TextBetweenCursorAndLineStart, but interacts with document start.
GoogleDocsUtils.select.TextBetweenCursorAndDocumentEnd(): void;Same as TextBetweenCursorAndLineStart, but interacts with document end.
This library may not work correctly in some conditions. It is because it still not well tested and not well developed. However, there are already some known limitations that can (but won't necessarily will) lead to problems.
So, if possible, avoid these conditions:
If you experiencing some issues with these or undocumented conditions, then feel free to create issue.
This project uses following structure for version naming: <MAJOR RELEASE>.<BREAKING CHANGES>.<NON BREAKING CHANGES>.
Contributions of all sizes are welcome. Feel free!
Use issues to report a bug, request a feature or ask a question.
Also, consider making a pull request to add your own implementation of missing functionality. Big thanks for that!
Initialiy it was a fork of JensPLarsen/ChromeExtension-GoogleDocsUtil. Starting from 2.0.0 version the project was completely rewritten, but core concepts were keeped.
MIT.