Skip to content

Latest commit

 

History

History
994 lines (653 loc) · 26.1 KB

README.md

File metadata and controls

994 lines (653 loc) · 26.1 KB
Raw

WARNING: this project may no longer work after July 2021

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.

google-docs-utils

Utilities for interaction with Google Docs using JavaScript.

Content

What for?

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:

  • you can't just use 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.
  • you can't just change text of element using 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.

Installation

Node.js

  • with npm:
npm install google-docs-utils
  • with yarn:
yarn add google-docs-utils

Browser

Use these CDN links:

  • for development:
https://unpkg.com/google-docs-utils@latest/dist/iife/index.js
  • for production:
https://unpkg.com/google-docs-utils@latest/dist/iife/index.min.js

Then access this library via GoogleDocsUtils global variable.

Usage

Node.js

// 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';

Browser

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);

API

getEditorElement

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.

getPagesElements

GoogleDocsUtils.getPagesElements(): HTMLElement[];

Returns all rendered editor pages.

getLinesElements

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.

getLinesTextElements

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.

getLinesText

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.

getLineText

GoogleDocsUtils.getLineText(lineIndex, [startIndex], [endIndex]): string | null;

Returns text of specific line.

lineIndex

  • required: true
  • type: number

Index 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

  • required: false
  • type: number
  • default: undefined

Start index for substring(). If not specified, then start of line is assumed.

endIndex

  • required: false
  • type: number
  • default: undefined

End index for substring(). If not specified, then end of line is assumed.

getWordElements

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.

getSelectionOverlayElements

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.

getSelection

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

  • type: string

Original text of word node.

SelectionData.selectedText

  • type: string

Selected text.

SelectionData.selectionStart

  • type: number

Index where selection starts. It can be used for substring(). It is relative to word node, not entire line.

SelectionData.selectionEnd

  • type: number

Index where selection ends. It can be used for substring(). It is relative to word node, not entire line.

SelectionData.textElement

  • type: HTMLElement

HTML element which contains actual text.

SelectionData.selectionElement

  • type: HTMLElement

HTML element which contains selection overlay element. Every not empty [][] will have same selectionElement.

SelectionData.textRect

  • type: DOMRectReadOnly

DOMRect of textElement.

SelectionData.selectionRect

  • type: DOMRectReadOnly

DOMRect of selectionElement. Every not empty [][] will have same selectionRect.

getCursorElement

GoogleDocsUtils.getCursorElement(): HTMLElement;

Returns cursor element.

getActiveCursorElement

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.

getCaretElement

GoogleDocsUtils.getCaretElement(): HTMLElement;

Returns caret element.

getCaret

GoogleDocsUtils.getCaret(): CaretData;

Returns data about caret.

CaretData.element

  • type: HTMLElement

Caret element.

CaretData.wordElement

  • type: HTMLElement

Element which contains text of line on which caret is placed.

CaretData.lineIndex

  • type: number

Global index of line.

CaretData.positionIndexRelativeToWord

  • type: number

Before 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.

getCaretWord

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

  • type: string

Full word on which caret is placed.

CaretWordData.text

  • type: string

Full text of line on which caret is placed.

CaretWordData.indexStart

  • type: number

On which index word starts in text. Can be used for substring().

CaretWordData.indexEnd

  • type: number

On which index word ends in text. Can be used for substring().

getTextEventTarget

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.

clearTextContent

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

  • required: true
  • type: string

Raw text of line that was extracted using textContent or innerText.

addEventListener

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.

selectionchange

This event is fired when the current text selection on a document is changed.

pressOn

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:

Character

GoogleDocsUtils.pressOn.Character(
  char,
  {
    ctrlKey = false,
    shiftKey = false
  } = {}
): void;

char

  • required: true
  • type: string

Single character to press on. Case sensitive.

Space

GoogleDocsUtils.pressOn.Space(): void;

Delete

GoogleDocsUtils.pressOn.Delete(
  {
    ctrlKey = false
  } = {}
): void;

Difference between Delete and Backspace is matters.

Backspace

GoogleDocsUtils.pressOn.Backspace(
  {
    ctrlKey = false
  } = {}
): void;

Difference between Delete and Backspace is matters.

Enter

GoogleDocsUtils.pressOn.Enter(): void;

Tab

GoogleDocsUtils.pressOn.Tab(): void;

ArrowLeft

GoogleDocsUtils.pressOn.ArrowLeft(
  {
    ctrlKey = false,
    shiftKey = false
  } = {}
): void;

ArrowRight

GoogleDocsUtils.pressOn.ArrowRight(
  {
    ctrlKey = false,
    shiftKey = false
  } = {}
): void;

ArrowUp

GoogleDocsUtils.pressOn.ArrowUp(
  {
    ctrlKey = false,
    shiftKey = false
  } = {}
): void;

ArrowDown

GoogleDocsUtils.pressOn.ArrowDown(
  {
    ctrlKey = false,
    shiftKey = false
  } = {}
): void;

Home

GoogleDocsUtils.pressOn.Home(
  {
    ctrlKey = false,
    shiftKey = false
  } = {}
): void;

End

GoogleDocsUtils.pressOn.End(
  {
    ctrlKey = false,
    shiftKey = false
  } = {}
): void;

Undo

GoogleDocsUtils.pressOn.Undo(): void;

Redo

GoogleDocsUtils.pressOn.Redo(): void;

Bold

GoogleDocsUtils.pressOn.Bold(): void;

Italic

GoogleDocsUtils.pressOn.Italic(): void;

Underline

GoogleDocsUtils.pressOn.Underline(): void;

PrintDialog

GoogleDocsUtils.pressOn.PrintDialog(): void;

typeText

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

  • required: true
  • type: string

Text to type.

isTextSelected

GoogleDocsUtils.isTextSelected(): boolean;

Returns status that indicates if text selection is exists on either single or multiple lines.

isDocumentActive

GoogleDocsUtils.isDocumentActive(): boolean;

Returns status that indicates if document is in active state. Active state means that document is focused (cursor is blinked).

focusDocument

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.

remove

This namespace provides methods to remove different document objects (text, selection, etc).

PrevWord

GoogleDocsUtils.remove.PrevWord(): void;

Removes word according to the following logic:

  • if previous word is present, then it will be removed
  • else content from current line will be divided with previous line

NextWord

GoogleDocsUtils.remove.NextWord(): void;

Removes word according to the following logic:

  • if next word is present, then it will be removed
  • else content from current line will be divided with next line

Selection

GoogleDocsUtils.remove.Selection(): boolean;

Removes current selection. Returns true if selection was removed, otherwise returns false if nothing to remove (because nothing is selected).

moveCursorTo

This namespace provides methods to move cursor over document.

PrevCharacter

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.

NextCharacter

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.

PrevLine

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.

NextLine

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.

PrevWord

GoogleDocsUtils.moveCursorTo.PrevWord(): void;

Moves cursor to word according to the following logic:

  • if it is start of current line, then to the end of previous word on previous line
  • else if it is start of current word, then to the start of previous word
  • else moves to the start of current word

NextWord

GoogleDocsUtils.moveCursorTo.NextWord(): void;

Moves cursor to word according to the following logic:

  • if it is end of current line, then to the start of next word on next line
  • else if it is end of current word, then to the end of next word
  • else moves to the end of current word

PrevParagraph

GoogleDocsUtils.moveCursorTo.PrevParagraph(): void;

Moves cursor to paragraph according to the following logic:

  • if it is start of current paragraph, then to the start of previous paragraph
  • else moves to the start of current paragraph

NextParagraph

GoogleDocsUtils.moveCursorTo.NextParagraph(): void;

Moves cursor to paragraph according to the following logic:

  • if it is end of current paragraph, then to the end of next paragraph
  • else moves to the end of current paragraph

LineStart

GoogleDocsUtils.moveCursorTo.LineStart(): void;

Moves cursor to the start of current line.

LineEnd

GoogleDocsUtils.moveCursorTo.LineEnd(): void;

Moves cursor to the start of current line.

DocumentStart

GoogleDocsUtils.moveCursorTo.DocumentStart(): void;

Moves cursor to the start of document.

DocumentEnd

GoogleDocsUtils.moveCursorTo.DocumentEnd(): void;

Moves cursor to the end of document.

select

This namespace provides methods to select text content in document.

All

GoogleDocsUtils.select.All(): void;

Selects text of entire document.

PrevCharacter

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:

  • if at least one character already selected with reverse selection (opposite direction), then lastly selected character will be deselected
  • if at least one character already selected, then next one will be selected. If that next character located on previous line, than that previous line will be used
  • if nothing selected, then first character will be selected

NextCharacter

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:

  • if at least one character already selected with reverse selection (opposite direction), then lastly selected character will be deselected
  • if at least one character already selected, then next one will be selected. If that next character located on next line, than that next line will be used
  • if nothing selected, then first character will be selected

PrevWord

GoogleDocsUtils.select.PrevWord(): void;

Same as PrevCharacter, but performs an action with word.

NextWord

GoogleDocsUtils.select.NextWord(): void;

Same as NextCharacter, but performs an action with word.

PrevLine

GoogleDocsUtils.select.PrevLine(): void;

Selects N number of characters to the left where N is a max length of line.

NextLine

GoogleDocsUtils.select.NextLine(): void;

Same as PrevLine, but uses right direction.

PrevParagraph

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:

  • if it is start of current paragraph, then previous paragraph will be selected
  • else text between current paragraph start and current cursor position will be selected

NextParagraph

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:

  • if it is end of current paragraph, then next paragraph will be NOT selected
  • else text between current paragraph end and current cursor position will be selected

TextBetweenCursorAndLineStart

GoogleDocsUtils.select.TextBetweenCursorAndLineStart(): void;

Selects a text between current cursor position and current line start.

TextBetweenCursorAndLineEnd

GoogleDocsUtils.select.TextBetweenCursorAndLineEnd(): void;

Same as TextBetweenCursorAndLineStart, but interacts with current line end.

TextBetweenCursorAndDocumentStart

GoogleDocsUtils.select.TextBetweenCursorAndDocumentStart(): void;

Same as TextBetweenCursorAndLineStart, but interacts with document start.

TextBetweenCursorAndDocumentEnd

GoogleDocsUtils.select.TextBetweenCursorAndDocumentEnd(): void;

Same as TextBetweenCursorAndLineStart, but interacts with document end.

Known limitations

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:

  • using of non-English text.
  • using of various formatting (font, bold, etc.).

If you experiencing some issues with these or undocumented conditions, then feel free to create issue.

Version naming

This project uses following structure for version naming: <MAJOR RELEASE>.<BREAKING CHANGES>.<NON BREAKING CHANGES>.

Contributing

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!

Project history

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.

License

MIT.