From 9b4a628206b103c8523975fca5f570d78e3f1ee1 Mon Sep 17 00:00:00 2001 From: Yangshun Tay Date: Tue, 3 Dec 2019 12:55:51 -0800 Subject: [PATCH] Improve docs syntax and formatting (#2267) Summary: **Summary** Reformat the docs in preparation for Docusaurus 2: - Add syntax highlighting for the code blocks - Remove `.html` from the Markdown link extensions. Docusaurus 1 allows clean URL but Docusaurus 2 doesn't, so this is necessary - Wrap API headings in code blocks - Change the level of some API headings so that they appear in the right table of contents **Test Plan** Run Docusaurus website locally and click through. Try it out - https://draft-js-pc0wv8qnv.now.sh Pull Request resolved: https://github.com/facebook/draft-js/pull/2267 Reviewed By: claudiopro Differential Revision: D18758620 Pulled By: yangshun fbshipit-source-id: 73b9572e521cbf891abcf5099fec65f0cbef91d2 --- docs/APIReference-APIMigration.md | 18 +- docs/APIReference-AtomicBlockUtils.md | 8 +- docs/APIReference-CharacterMetadata.md | 36 ++- docs/APIReference-CompositeDecorator.md | 2 +- docs/APIReference-ContentBlock.md | 92 ++++--- docs/APIReference-ContentState.md | 130 +++++---- docs/APIReference-Data-Conversion.md | 12 +- docs/APIReference-Editor.md | 259 ++++++++++-------- docs/APIReference-EditorChangeType.md | 30 +- docs/APIReference-EditorState.md | 154 ++++++----- docs/APIReference-Entity.md | 29 +- docs/APIReference-KeyBindingUtil.md | 16 +- docs/APIReference-Modifier.md | 63 +++-- docs/APIReference-RichUtils.md | 48 ++-- docs/APIReference-SelectionState.md | 107 ++++---- docs/Advanced-Topics-Custom-Block-Render.md | 8 +- docs/Advanced-Topics-Decorators.md | 2 +- ...nced-Topics-EditorState-Race-Conditions.md | 22 +- docs/Advanced-Topics-Entities.md | 8 +- docs/Advanced-Topics-Inline-Styles.md | 4 +- docs/Advanced-Topics-Issues-and-Pitfalls.md | 12 +- docs/Advanced-Topics-Nested-Lists.md | 2 +- docs/Overview.md | 6 +- docs/QuickStart-API-Basics.md | 8 +- docs/QuickStart-Rich-Styling.md | 15 +- 25 files changed, 615 insertions(+), 476 deletions(-) diff --git a/docs/APIReference-APIMigration.md b/docs/APIReference-APIMigration.md index 797b6ae64a..1f92e2253f 100644 --- a/docs/APIReference-APIMigration.md +++ b/docs/APIReference-APIMigration.md @@ -23,7 +23,7 @@ Here is a quick list of what has been changed and how to update your application **Old Syntax** -``` +```js const entityKey = Entity.create( urlType, 'IMMUTABLE', @@ -33,7 +33,7 @@ const entityKey = Entity.create( **New Syntax** -``` +```js const contentStateWithEntity = contentState.createEntity( urlType, 'IMMUTABLE', @@ -46,14 +46,14 @@ const entityKey = contentStateWithEntity.getLastCreatedEntityKey(); **Old Syntax** -``` +```js const entityInstance = Entity.get(entityKey); // entityKey is a string key associated with that entity when it was created ``` **New Syntax** -``` +```js const entityInstance = contentState.getEntity(entityKey); // entityKey is a string key associated with that entity when it was created ``` @@ -62,7 +62,7 @@ const entityInstance = contentState.getEntity(entityKey); **Old Syntax** -``` +```js const compositeDecorator = new CompositeDecorator([ { strategy: (contentBlock, callback) => exampleFindTextRange(contentBlock, callback), @@ -73,7 +73,7 @@ const compositeDecorator = new CompositeDecorator([ **New Syntax** -``` +```js const compositeDecorator = new CompositeDecorator([ { strategy: ( @@ -90,7 +90,7 @@ Note that ExampleTokenComponent will receive contentState as a prop. Why does the 'contentState' get passed into the decorator strategy now? Because we may need it if our strategy is to find certain entities in the contentBlock: -``` +```js const mutableEntityStrategy = function(contentBlock, callback, contentState) { contentBlock.findEntityRanges( (character) => { @@ -113,7 +113,7 @@ const mutableEntityStrategy = function(contentBlock, callback, contentState) { **Old Syntax** -``` +```js function findLinkEntities(contentBlock, callback) { contentBlock.findEntityRanges( (character) => { @@ -130,7 +130,7 @@ function findLinkEntities(contentBlock, callback) { **New Syntax** -``` +```js function findLinkEntities(contentBlock, callback, contentState) { contentBlock.findEntityRanges( (character) => { diff --git a/docs/APIReference-AtomicBlockUtils.md b/docs/APIReference-AtomicBlockUtils.md index ef3aea4070..24206e25e3 100644 --- a/docs/APIReference-AtomicBlockUtils.md +++ b/docs/APIReference-AtomicBlockUtils.md @@ -11,9 +11,9 @@ parameters and return `EditorState` objects. ## Static Methods -### insertAtomicBlock +### `insertAtomicBlock()` -``` +```js insertAtomicBlock: function( editorState: EditorState, entityKey: string, @@ -21,9 +21,9 @@ insertAtomicBlock: function( ): EditorState ``` -### moveAtomicBlock +### `moveAtomicBlock()` -``` +```js moveAtomicBlock: function( editorState: EditorState, atomicBlock: ContentBlock, diff --git a/docs/APIReference-CharacterMetadata.md b/docs/APIReference-CharacterMetadata.md index 4519f192ca..aa34f9ef25 100644 --- a/docs/APIReference-CharacterMetadata.md +++ b/docs/APIReference-CharacterMetadata.md @@ -21,7 +21,7 @@ operations are already implemented and available via utility modules. The getter methods, however, may come in handy at render time. See the API reference on -[ContentBlock](/docs/api-reference-content-block.html#representing-styles-and-entities) +[ContentBlock](/docs/api-reference-content-block#representing-styles-and-entities) for information on how `CharacterMetadata` is used within `ContentBlock`. ## Overview @@ -76,11 +76,12 @@ for information on how `CharacterMetadata` is used within `ContentBlock`. Under the hood, these methods will utilize pooling to return a matching object, or return a new object if none exists. -### create +### `create()` -``` +```js static create(config?: CharacterMetadataConfig): CharacterMetadata ``` + Generates a `CharacterMetadata` object from the provided configuration. This function should be used in lieu of a constructor. @@ -89,29 +90,31 @@ configuration already exists. If so, the pooled object will be returned. Otherwise, a new `CharacterMetadata` will be pooled for this configuration, and returned. -### applyStyle +### `applyStyle()` -``` +```js static applyStyle( record: CharacterMetadata, style: string ): CharacterMetadata ``` + Apply an inline style to this `CharacterMetadata`. -### removeStyle +### `removeStyle()` -``` +```js static removeStyle( record: CharacterMetadata, style: string ): CharacterMetadata ``` + Remove an inline style from this `CharacterMetadata`. -### applyEntity +### `applyEntity()` -``` +```js static applyEntity( record: CharacterMetadata, entityKey: ?string @@ -123,26 +126,29 @@ Apply an entity key -- or provide `null` to remove an entity key -- on this ## Methods -### getStyle +### `getStyle()` -``` +```js getStyle(): DraftInlineStyle ``` + Returns the `DraftInlineStyle` for this character, an `OrderedSet` of strings that represents the inline style to apply for the character at render time. -### hasStyle +### `hasStyle()` -``` +```js hasStyle(style: string): boolean ``` + Returns whether this character has the specified style. -### getEntity +### `getEntity()` -``` +```js getEntity(): ?string ``` + Returns the entity key (if any) for this character, as mapped to the global set of entities tracked by the [`Entity`](https://github.com/facebook/draft-js/blob/master/src/model/entity/DraftEntity.js) module. diff --git a/docs/APIReference-CompositeDecorator.md b/docs/APIReference-CompositeDecorator.md index 57db79f256..d96b9c9b94 100644 --- a/docs/APIReference-CompositeDecorator.md +++ b/docs/APIReference-CompositeDecorator.md @@ -5,4 +5,4 @@ title: CompositeDecorator ## Advanced Topic Article -See the [advanced topic article on Decorators](/docs/advanced-topics-decorators.html#compositedecorator). +See the [advanced topic article on Decorators](/docs/advanced-topics-decorators#compositedecorator). diff --git a/docs/APIReference-ContentBlock.md b/docs/APIReference-ContentBlock.md index 543565190d..f8bacba1fb 100644 --- a/docs/APIReference-ContentBlock.md +++ b/docs/APIReference-ContentBlock.md @@ -156,103 +156,101 @@ supplied text. ## Methods -### getKey() +### `getKey()` -``` +```js getKey(): string ``` Returns the string key for this `ContentBlock`. Block keys are alphanumeric string. It is recommended to use `generateRandomKey` to generate block keys. -### getType() +### `getType()` -``` +```js getType(): DraftBlockType ``` Returns the type for this `ContentBlock`. Type values are largely analogous to block-level HTML elements. -### getText() +### `getText()` -``` +```js getText(): string ``` Returns the full plaintext for this `ContentBlock`. This value does not contain any styling, decoration, or HTML information. -### getCharacterList() +### `getCharacterList()` -``` +```js getCharacterList(): List ``` -Returns an immutable `List` of `CharacterMetadata` objects, one for each -character in the `ContentBlock`. (See [CharacterMetadata](/docs/api-reference-character-metadata.html) -for details.) + +Returns an immutable `List` of `CharacterMetadata` objects, one for each character in the `ContentBlock`. (See [CharacterMetadata](/docs/api-reference-character-metadata) for details.) This `List` contains all styling and entity information for the block. -### getLength() +### `getLength()` -``` +```js getLength(): number ``` + Returns the length of the plaintext for the `ContentBlock`. -This value uses the standard JavaScript `length` property for the string, and -is therefore not Unicode-aware -- surrogate pairs will be counted as two -characters. +This value uses the standard JavaScript `length` property for the string, and is therefore not Unicode-aware -- surrogate pairs will be counted as two characters. -### getDepth() +### `getDepth()` -``` +```js getDepth(): number ``` -Returns the depth value for this block, if any. This is currently used only -for list items. +Returns the depth value for this block, if any. This is currently used only for list items. -### getInlineStyleAt() +### `getInlineStyleAt()` -``` +```js getInlineStyleAt(offset: number): DraftInlineStyle ``` -Returns the `DraftInlineStyle` value (an `OrderedSet`) at a given offset -within this `ContentBlock`. -### getEntityAt() +Returns the `DraftInlineStyle` value (an `OrderedSet`) at a given offset within this `ContentBlock`. -``` +### `getEntityAt()` + +```js getEntityAt(offset: number): ?string ``` -Returns the entity key value (or `null` if none) at a given offset within this -`ContentBlock`. -### getData() +Returns the entity key value (or `null` if none) at a given offset within this `ContentBlock`. -``` +### `getData()` + +```js getData(): Map ``` + Returns block-level metadata. -### findStyleRanges() +### `findStyleRanges()` -``` +```js findStyleRanges( filterFn: (value: CharacterMetadata) => boolean, callback: (start: number, end: number) => void ): void ``` -Executes a callback for each contiguous range of styles within this -`ContentBlock`. -### findEntityRanges() +Executes a callback for each contiguous range of styles within this `ContentBlock`. -``` +### `findEntityRanges()` + +```js findEntityRanges( filterFn: (value: CharacterMetadata) => boolean, callback: (start: number, end: number) => void ): void ``` -Executes a callback for each contiguous range of entities within this -`ContentBlock`. + +Executes a callback for each contiguous range of entities within this `ContentBlock`. ## Properties @@ -261,20 +259,26 @@ Executes a callback for each contiguous range of entities within this > Use [Immutable Map API](http://facebook.github.io/immutable-js/docs/#/Map) > for the `ContentBlock` constructor or to set properties. -### key +### `key` + See `getKey()`. -### text +### `text` + See `getText()`. -### type +### `type` + See `getType()`. -### characterList +### `characterList` + See `getCharacterList()`. -### depth +### `depth` + See `getDepth()`. -### data +### `data` + See `getData()`. diff --git a/docs/APIReference-ContentState.md b/docs/APIReference-ContentState.md index 2e4b4939b5..a7f5bf9f0f 100644 --- a/docs/APIReference-ContentState.md +++ b/docs/APIReference-ContentState.md @@ -142,9 +142,10 @@ objects. > Use [Immutable Map API](http://facebook.github.io/immutable-js/docs/#/Map) to > set properties. -> +> > **Example** -> ``` +> +> ```js > const editorState = EditorState.createEmpty(); > const contentState = editorState.getCurrentContent(); > const contentStateWithSelectionBefore = contentState.set('selectionBefore', SelectionState.createEmpty(contentState.getBlockForKey('1pu4d'))); @@ -170,36 +171,39 @@ objects. ## Static Methods -### createFromText +### `createFromText()` -``` +```js static createFromText( text: string, delimiter?: string ): ContentState ``` + Generates a `ContentState` from a string, with a delimiter to split the string into `ContentBlock` objects. If no delimiter is provided, '`\n`' is used. -### createFromBlockArray +### `createFromBlockArray()` -``` +```js static createFromBlockArray( blocks: Array, entityMap: ?OrderedMap ): ContentState ``` + Generates a `ContentState` from an array of `ContentBlock` objects. The default `selectionBefore` and `selectionAfter` states have the cursor at the start of the content. ## Methods -### getEntityMap +### `getEntityMap()` -``` +```js getEntityMap(): EntityMap ``` + Returns an object store containing all `DraftEntity` records that have been created. In upcoming v0.11.0 the map returned will be an Immutable ordered map of `DraftEntity` records. @@ -208,47 +212,51 @@ In most cases, you should be able to use the convenience methods below to target specific `DraftEntity` records or obtain information about the state of the content. -### getBlockMap +### `getBlockMap()` -``` +```js getBlockMap(): BlockMap ``` + Returns the full ordered map of `ContentBlock` objects representing the state of an entire document. In most cases, you should be able to use the convenience methods below to target specific `ContentBlock` objects or obtain information about the state of the content. -### getSelectionBefore +### `getSelectionBefore()` -``` +```js getSelectionBefore(): SelectionState ``` + Returns the `SelectionState` displayed in the editor before rendering `blockMap`. When performing an `undo` action in the editor, the `selectionBefore` of the current `ContentState` is used to place the selection range in the appropriate position. -### getSelectionAfter +### `getSelectionAfter()` -``` +```js getSelectionAfter(): SelectionState ``` + Returns the `SelectionState` displayed in the editor after rendering `blockMap`. When performing any action in the editor that leads to this `blockMap` being rendered, the selection range will be placed in the `selectionAfter` position. -### getBlockForKey +### `getBlockForKey()` -``` +```js getBlockForKey(key: string): ContentBlock ``` + Returns the `ContentBlock` corresponding to the given block key. #### Example -``` +```js var {editorState} = this.state; var startKey = editorState.getSelection().getStartKey(); var selectedBlockType = editorState @@ -257,131 +265,144 @@ var selectedBlockType = editorState .getType(); ``` -### getKeyBefore +### `getKeyBefore()` -``` +```js getKeyBefore(key: string): ?string ``` + Returns the key before the specified key in `blockMap`, or null if this is the first key. -### getKeyAfter +### `getKeyAfter()` -``` +```js getKeyAfter(key: string): ?string ``` + Returns the key after the specified key in `blockMap`, or null if this is the last key. -### getBlockBefore +### `getBlockBefore()` -``` +```js getBlockBefore(key: string): ?ContentBlock ``` + Returns the `ContentBlock` before the specified key in `blockMap`, or null if this is the first key. -### getBlockAfter +### `getBlockAfter()` -``` +```js getBlockAfter(key: string): ?ContentBlock ``` + Returns the `ContentBlock` after the specified key in `blockMap`, or null if this is the last key. -### getBlocksAsArray +### `getBlocksAsArray()` -``` +```js getBlocksAsArray(): Array ``` + Returns the values of `blockMap` as an array. You generally won't need to use this method, since `getBlockMap` provides an `OrderedMap` that you should use for iteration. -### getFirstBlock +### `getFirstBlock()` -``` +```js getFirstBlock(): ContentBlock ``` + Returns the first `ContentBlock`. -### getLastBlock +### `getLastBlock()` -``` +```js getLastBlock(): ContentBlock ``` + Returns the last `ContentBlock`. -### getPlainText +### `getPlainText()` -``` +```js getPlainText(delimiter?: string): string ``` + Returns the full plaintext value of the contents, joined with a delimiter. If no delimiter is specified, the line feed character (`\u000A`) is used. -### getLastCreatedEntityKey +### `getLastCreatedEntityKey()` -``` +```js getLastCreatedEntityKey(): string ``` + Returns the string key that can be used to reference the most recently created `DraftEntity` record. This is because entities are referenced by their string key in ContentState. The string value should be used within CharacterMetadata objects to track the entity for annotated characters. -### hasText +### `hasText()` -``` +```js hasText(): boolean ``` + Returns whether the contents contain any text at all. -### createEntity +### `createEntity()` -``` +```js createEntity( type: DraftEntityType, mutability: DraftEntityMutability, data?: Object ): ContentState ``` -Returns `ContentState` record updated to include the newly created -DraftEntity record in it's `EntityMap`. Call `getLastCreatedEntityKey` to get -the key of the newly created `DraftEntity` record. -### getEntity +Returns `ContentState` record updated to include the newly created `DraftEntity` record in it's `EntityMap`. Call `getLastCreatedEntityKey` to get the key of the newly created `DraftEntity` record. -``` +### `getEntity()` + +```js getEntity(key: string): DraftEntityInstance ``` + Returns the DraftEntityInstance for the specified key. Throws if no instance exists for that key. -### mergeEntityData +### `mergeEntityData()` -``` +```js mergeEntityData( key: string, toMerge: {[key: string]: any} ): ContentState ``` + Since DraftEntityInstance objects are immutable, you cannot update an entity's metadata through typical mutative means. The mergeData method allows you to apply updates to the specified entity. -### replaceEntityData +### `replaceEntityData()` -``` +```js replaceEntityData( key: string, newData: {[key: string]: any} ): ContentState ``` + The replaceData method is similar to the mergeData method, except it will totally discard the existing data value for the instance and replace it with the specified newData. -### addEntity +### `addEntity()` -``` +```js addEntity(instance: DraftEntityInstance): ContentState ``` + In most cases, you will use contentState.createEntity(). This is a convenience method that you probably will not need in typical Draft usage. @@ -395,11 +416,14 @@ editing. > Use [Immutable Map API](http://facebook.github.io/immutable-js/docs/#/Map) to > set properties. -### blockMap +### `blockMap` + See `getBlockMap()`. -### selectionBefore +### `selectionBefore` + See `getSelectionBefore()`. -### selectionAfter +### `selectionAfter` + See `getSelectionAfter()`. diff --git a/docs/APIReference-Data-Conversion.md b/docs/APIReference-Data-Conversion.md index 5239be0868..3180e9cd2c 100644 --- a/docs/APIReference-Data-Conversion.md +++ b/docs/APIReference-Data-Conversion.md @@ -22,18 +22,18 @@ objects. ## Functions -### convertFromRaw +### `convertFromRaw()` -``` +```js convertFromRaw(rawState: RawDraftContentState): ContentState ``` Given a raw state, convert it to a `ContentState`. This is useful when restoring contents to use within a Draft editor. -### convertToRaw +### `convertToRaw()` -``` +```js convertToRaw(contentState: ContentState): RawDraftContentState ``` @@ -42,9 +42,9 @@ when saving an editor state for storage, conversion to other formats, or other usage within an application. -### convertFromHTML +### `convertFromHTML()` -``` +```js const sampleMarkup = 'Bold text, Italic text

' + 'Example link'; diff --git a/docs/APIReference-Editor.md b/docs/APIReference-Editor.md index 550ba044a3..33a620bded 100644 --- a/docs/APIReference-Editor.md +++ b/docs/APIReference-Editor.md @@ -9,41 +9,48 @@ component itself, `Editor`. Props are defined within ## Props -### Basics +## Basics -See [API Basics](/docs/quickstart-api-basics.html) for an introduction. +See [API Basics](/docs/quickstart-api-basics) for an introduction. -#### editorState -``` +### `editorState` + +```js editorState: EditorState ``` + The `EditorState` object to be rendered by the `Editor`. -#### onChange -``` +### `onChange` + +```js onChange: (editorState: EditorState) => void ``` + The `onChange` function to be executed by the `Editor` when edits and selection changes occur. -### Presentation (Optional) +## Presentation (Optional) -#### placeholder -``` +### `placeholder` + +```js placeholder?: string ``` + Optional placeholder string to display when the editor is empty. Note: You can use CSS to style or hide your placeholder as needed. For instance, -in the [rich editor example](https://github.com/facebook/draft-js/tree/master/examples/draft-0-10-0/rich), -the placeholder is hidden when the user changes block styling in an empty editor. +in the [rich editor example](https://github.com/facebook/draft-js/tree/master/examples/draft-0-10-0/rich), the placeholder is hidden when the user changes block styling in an empty editor. This is because the placeholder may not line up with the cursor when the style is changed. -#### textAlignment -``` +### `textAlignment` + +```js textAlignment?: DraftTextAlignment ``` + Optionally set the overriding text alignment for this editor. This alignment value will apply to the entire contents, regardless of default text direction for input text. @@ -53,107 +60,101 @@ to fit it within your UI design. If this value is not set, text alignment will be based on the characters within the editor, on a per-block basis. -#### textDirectionality -``` +### `textDirectionality` + +```js textDirectionality?: DraftTextDirectionality ``` -Optionally set the overriding text directionality for this editor. The values -include 'RTL' for right-to-left text, like Hebrew or Arabic, and 'LTR' for -left-to-right text, like English or Spanish. This directionality will apply to -the entire contents, regardless of default text direction for input text. + +Optionally set the overriding text directionality for this editor. The values include 'RTL' for right-to-left text, like Hebrew or Arabic, and 'LTR' for left-to-right text, like English or Spanish. This directionality will apply to the entire contents, regardless of default text direction for input text. If this value is not set, text directionality will be based on the characters within the editor, on a per-block basis. -#### blockRendererFn -``` +### `blockRendererFn` + +```js blockRendererFn?: (block: ContentBlock) => ?Object ``` -Optionally set a function to define custom block rendering. See -[Advanced Topics: Block Components](/docs/advanced-topics-block-components.html) -for details on usage. -#### blockRendererMap -``` +Optionally set a function to define custom block rendering. See [Advanced Topics: Block Components](/docs/advanced-topics-block-components) for details on usage. + +### `blockRendererMap` + +```js blockRendererMap?: DraftBlockRenderMap ``` -Provide a map of block rendering configurations. Each block type maps to -element tag and an optional react element wrapper. This configuration -is used for both rendering and paste processing. See -[Advanced Topics: Custom Block Rendering](https://draftjs.org/docs/advanced-topics-custom-block-render-map.html) -for details on usage. +Provide a map of block rendering configurations. Each block type maps to element tag and an optional react element wrapper. This configuration is used for both rendering and paste processing. See +[Advanced Topics: Custom Block Rendering](/docs/advanced-topics-custom-block-render-map) for details on usage. -#### blockStyleFn -``` +### `blockStyleFn` + +```js blockStyleFn?: (block: ContentBlock) => string ``` -Optionally set a function to define class names to apply to the given block -when it is rendered. See -[Advanced Topics: Block Styling](/docs/advanced-topics-block-styling.html) -for details on usage. -#### customStyleMap -``` +Optionally set a function to define class names to apply to the given block when it is rendered. See [Advanced Topics: Block Styling](/docs/advanced-topics-block-styling) for details on usage. + +### customStyleMap + +```js customStyleMap?: Object ``` -Optionally define a map of inline styles to apply to spans of text with the specified -style. See -[Advanced Topics: Inline Styles](/docs/advanced-topics-inline-styles.html) -for details on usage. -#### customStyleFn -``` +Optionally define a map of inline styles to apply to spans of text with the specified style. See [Advanced Topics: Inline Styles](/docs/advanced-topics-inline-styles) for details on usage. + +### `customStyleFn` + +```js customStyleFn?: (style: DraftInlineStyle, block: ContentBlock) => ?Object ``` -Optionally define a function to transform inline styles to CSS objects that are applied -to spans of text. See -[Advanced Topics: Inline Styles](/docs/advanced-topics-inline-styles.html) -for details on usage. -### Behavior (Optional) +Optionally define a function to transform inline styles to CSS objects that are applied to spans of text. See [Advanced Topics: Inline Styles](/docs/advanced-topics-inline-styles) for details on usage. -### autoCapitalize?: string +## Behavior (Optional) -``` +### `autoCapitalize` + +```js autoCapitalize?: string ``` Set if auto capitalization is turned on and how it behaves. More about platform availability and usage can [be found on mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#attr-autocapitalize). -### autoComplete?: string +### `autoComplete` -``` +```js autoComplete?: string ``` Set if auto complete is turned on and how it behaves. More about platform availability and usage can [be found on mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#attr-autocomplete). -### autoCorrect?: string +### `autoCorrect` -``` +```js autoCorrect?: string ``` -Set if auto correct is turned on and how it behaves. More about platform availability and usage can [be found on mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#attr-autocorrect). +Set if auto correct is turned on and how it behaves. More about platform availability and usage can [be found on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#attr-autocorrect). +### `readOnly` -#### readOnly -``` +```js readOnly?: boolean ``` -Set whether the editor should be rendered as static DOM, with all editability -disabled. -This is useful when supporting interaction within -[custom block components](/docs/advanced-topics-block-components.html) -or if you only want to display content for a static use case. +Set whether the editor should be rendered as static DOM, with all editability disabled. + +This is useful when supporting interaction within [custom block components](/docs/advanced-topics-block-components) or if you only want to display content for a static use case. Default is `false`. -#### spellCheck -``` +### `spellCheck` + +```js spellCheck?: boolean ``` + Set whether spellcheck is turned on for your editor. Note that in OSX Safari, enabling spellcheck also enables autocorrect, if the user @@ -162,26 +163,30 @@ needed to observe spellcheck events are not fired in IE. Default is `false`. -#### stripPastedStyles -``` +### `stripPastedStyles` + +```js stripPastedStyles?: boolean ``` + Set whether to remove all information except plaintext from pasted content. This should be used if your editor does not support rich styles. Default is `false`. -### DOM and Accessibility (Optional) +## DOM and Accessibility (Optional) + +### `tabIndex` -#### tabIndex -#### ARIA props +### ARIA props These props allow you to set accessibility properties on your editor. See [DraftEditorProps](https://github.com/facebook/draft-js/blob/master/src/component/base/DraftEditorProps.js) for the exhaustive list of supported attributes. -#### editorKey -``` +### `editorKey` + +```js editorKey?: string ``` @@ -197,32 +202,49 @@ If you _do_ set this prop, the key should be unique _per-editor_, as it is used to determine if styles should be preserved when pasting text within an editor. -### Cancelable Handlers (Optional) +## Cancelable Handlers (Optional) These prop functions are provided to allow custom event handling for a small set of useful events. By returning `'handled'` from your handler, you indicate that the event is handled and the Draft core should do nothing more with it. By returning `'not-handled'`, you defer to Draft to handle the event. -#### handleReturn -``` -handleReturn?: (e: SyntheticKeyboardEvent, editorState: EditorState) => DraftHandleValue +### `handleReturn` + +```js +handleReturn?: ( + e: SyntheticKeyboardEvent, + editorState: EditorState, +) => DraftHandleValue ``` + Handle a `RETURN` keydown event. Example usage: Choosing a mention tag from a rendered list of results to trigger applying the mention entity to your content. -#### handleKeyCommand -``` -handleKeyCommand?: (command: string, editorState: EditorState, eventTimeStamp: number) => DraftHandleValue +### `handleKeyCommand` + +```js +handleKeyCommand?: ( + command: string, + editorState: EditorState, + eventTimeStamp: number, +) => DraftHandleValue ``` + Handle the named editor command. See -[Advanced Topics: Key Bindings](/docs/advanced-topics-key-bindings.html) +[Advanced Topics: Key Bindings](/docs/advanced-topics-key-bindings) for details on usage. -#### handleBeforeInput -``` -handleBeforeInput?: (chars: string, editorState: EditorState, eventTimeStamp: number) => DraftHandleValue +### `handleBeforeInput` + +```js +handleBeforeInput?: ( + chars: string, + editorState: EditorState, + eventTimeStamp: number, +) => DraftHandleValue ``` + Handle the characters to be inserted from a `beforeInput` event. Returning `'handled'` causes the default behavior of the `beforeInput` event to be prevented (i.e. it is the same as calling the `preventDefault` method on the event). @@ -232,38 +254,57 @@ convert that `ContentBlock` into an `unordered-list-item`. At Facebook, we also use this to convert typed ASCII quotes into "smart" quotes, and to convert typed emoticons into images. -#### handlePastedText -``` -handlePastedText?: (text: string, html?: string, editorState: EditorState) => DraftHandleValue +### `handlePastedText` + +```js +handlePastedText?: ( + text: string, + html?: string, + editorState: EditorState, +) => DraftHandleValue ``` + Handle text and html(for rich text) that has been pasted directly into the editor. Returning true will prevent the default paste behavior. -#### handlePastedFiles -``` +### `handlePastedFiles` + +```js handlePastedFiles?: (files: Array) => DraftHandleValue ``` + Handle files that have been pasted directly into the editor. -#### handleDroppedFiles -``` -handleDroppedFiles?: (selection: SelectionState, files: Array) => DraftHandleValue +### `handleDroppedFiles` + +```js +handleDroppedFiles?: ( + selection: SelectionState, + files: Array, +) => DraftHandleValue ``` + Handle files that have been dropped into the editor. -#### handleDrop -``` -handleDrop?: (selection: SelectionState, dataTransfer: Object, isInternal: DraftDragType) => DraftHandleValue +### `handleDrop` + +```js +handleDrop?: ( + selection: SelectionState, + dataTransfer: Object, + isInternal: DraftDragType, +) => DraftHandleValue ``` + Handle other drop operations. -### Key Handlers (Optional) +## Key Handlers (Optional) Draft lets you supply a custom `keyDown` handler that wraps or overrides its default one. -#### keyBindingFn +### `keyBindingFn` -``` +```js keyBindingFn?: (e: SyntheticKeyboardEvent) => ?string ``` @@ -273,33 +314,35 @@ corresponding to a `DraftEditorCommand` or a custom editor command of your own creation. Example: At Facebook, this is used to provide keyboard interaction for the mentions autocomplete menu that appears when typing a friend's name. You can find a more detailed explanation of this -[here](/docs/advanced-topics-key-bindings.html). +[here](/docs/advanced-topics-key-bindings). -### Mouse events +## Mouse events -### onFocus -``` +### `onFocus` + +```js onFocus?: (e: SyntheticFocusEvent) => void ``` -### onBlur -``` +### `onBlur` + +```js onBlur?: (e: SyntheticFocusEvent) => void ``` ## Methods -#### focus +### `focus` -``` +```js focus(): void ``` Force focus back onto the editor node. -#### blur +### `blur` -``` +```js blur(): void ``` diff --git a/docs/APIReference-EditorChangeType.md b/docs/APIReference-EditorChangeType.md index e2a371acf7..87b3cb50b1 100644 --- a/docs/APIReference-EditorChangeType.md +++ b/docs/APIReference-EditorChangeType.md @@ -22,68 +22,68 @@ static typechecking on your project. Flow will enforce the use of an appropriate ## Values -#### `adjust-depth` +### `adjust-depth` The `depth` value of one or more `ContentBlock` objects is being changed. -#### `apply-entity` +### `apply-entity` An entity is being applied (or removed via `null`) to one or more characters. -#### `backspace-character` +### `backspace-character` A single character is being backward-removed. -#### `change-block-data` +### `change-block-data` The `data` value of one or more `ContentBlock` objects is being changed. -#### `change-block-type` +### `change-block-type` The `type` value of one or more `ContentBlock` objects is being changed. -#### `change-inline-style` +### `change-inline-style` An inline style is being applied or removed for one or more characters. -#### `move-block` +### `move-block` A block is being moved within the [BlockMap](https://github.com/facebook/draft-js/blob/master/src/model/immutable/BlockMap.js). -#### `delete-character` +### `delete-character` A single character is being forward-removed. -#### `insert-characters` +### `insert-characters` One or more characters is being inserted at a selection state. -#### `insert-fragment` +### `insert-fragment` A "fragment" of content (i.e. a [BlockMap](https://github.com/facebook/draft-js/blob/master/src/model/immutable/BlockMap.js)) is being inserted at a selection state. -#### `redo` +### `redo` A redo operation is being performed. Since redo behavior is handled by the Draft core, it is unlikely that you will need to use this explicitly. -#### `remove-range` +### `remove-range` Multiple characters or blocks are being removed. -#### `spellcheck-change` +### `spellcheck-change` A spellcheck or autocorrect change is being performed. This is used to inform the core editor whether to try to allow native undo behavior. -#### `split-block` +### `split-block` A single `ContentBlock` is being split into two, for instance when the user presses return. -#### `undo` +### `undo` An undo operation is being performed. Since undo behavior is handled by the Draft core, it is unlikely that you will need to use this explicitly. diff --git a/docs/APIReference-EditorState.md b/docs/APIReference-EditorState.md index e675696a3f..c1bff0a634 100644 --- a/docs/APIReference-EditorState.md +++ b/docs/APIReference-EditorState.md @@ -122,7 +122,8 @@ The list below includes the most commonly used instance methods for `EditorState > new options to an EditorState instance. > > **Example** -> ``` +> +> ```js > const editorState = EditorState.createEmpty(); > const editorStateWithoutUndo = EditorState.set(editorState, {allowUndo: false}); > ``` @@ -197,25 +198,28 @@ The list below includes the most commonly used instance methods for `EditorState ## Common Instance Methods -### getCurrentContent +### `getCurrentContent` -``` +```js getCurrentContent(): ContentState ``` + Returns the current contents of the editor. -### getSelection +### `getSelection` -``` +```js getSelection(): SelectionState ``` + Returns the current cursor/selection state of the editor. -### getCurrentInlineStyle +### `getCurrentInlineStyle` -``` +```js getCurrentInlineStyle(): DraftInlineStyle ``` + Returns an `OrderedSet` that represents the "current" inline style for the editor. @@ -223,11 +227,12 @@ This is the inline style value that would be used if a character were inserted for the current `ContentState` and `SelectionState`, and takes into account any inline style overrides that should be applied. -### getBlockTree +### `getBlockTree` -``` +```js getBlockTree(blockKey: string): List; ``` + Returns an Immutable `List` of decorated and styled ranges. This is used for rendering purposes, and is generated based on the `currentContent` and `decorator`. @@ -237,42 +242,45 @@ block, decorator, and styled range components. ## Static Methods -### createEmpty +### `createEmpty` -``` +```js static createEmpty(decorator?: DraftDecoratorType): EditorState ``` + Returns a new `EditorState` object with an empty `ContentState` and default configuration. -### createWithContent +### `createWithContent` -``` +```js static createWithContent( contentState: ContentState, decorator?: DraftDecoratorType ): EditorState ``` + Returns a new `EditorState` object based on the `ContentState` and decorator provided. -### create +### `create` -``` +```js static create(config: EditorStateCreationConfig): EditorState ``` Returns a new `EditorState` object based on a configuration object. Use this if you need custom configuration not available via the methods above. -### push +### `push` -``` +```js static push( editorState: EditorState, contentState: ContentState, changeType: EditorChangeType ): EditorState ``` + Returns a new `EditorState` object with the specified `ContentState` applied as the new `currentContent`. Based on the `changeType`, this `ContentState` may be regarded as a boundary state for undo/redo behavior. @@ -281,86 +289,93 @@ All content changes must be applied to the EditorState with this method. _To be renamed._ -### undo +### `undo` -``` +```js static undo(editorState: EditorState): EditorState ``` + Returns a new `EditorState` object with the top of the undo stack applied as the new `currentContent`. The existing `currentContent` is pushed onto the `redo` stack. -### redo +### `redo` -``` +```js static redo(editorState: EditorState): EditorState ``` -Returns a new `EditorState` object with the top of the redo stack applied -as the new `currentContent`. + +Returns a new `EditorState` object with the top of the redo stack applied as the new `currentContent`. The existing `currentContent` is pushed onto the `undo` stack. -### acceptSelection +### `acceptSelection` -``` +```js static acceptSelection( editorState: EditorState, selectionState: SelectionState ): EditorState ``` + Returns a new `EditorState` object with the specified `SelectionState` applied, but without requiring the selection to be rendered. For example, this is useful when the DOM selection has changed outside of our control, and no re-renders are necessary. -### forceSelection +### `forceSelection` -``` +```js static forceSelection( editorState: EditorState, selectionState: SelectionState ): EditorState ``` + Returns a new `EditorState` object with the specified `SelectionState` applied, forcing the selection to be rendered. This is useful when the selection should be manually rendered in the correct location to maintain control of the rendered output. -### moveSelectionToEnd +### `moveSelectionToEnd` -``` +```js static moveSelectionToEnd(editorState: EditorState): EditorState ``` + Returns a new `EditorState` object with the selection at the end. Moves selection to the end of the editor without forcing focus. -### moveFocusToEnd +### `moveFocusToEnd` -``` +```js static moveFocusToEnd(editorState: EditorState): EditorState ``` + Returns a new `EditorState` object with selection at the end and forces focus. This is useful in scenarios where we want to programmatically focus the input and it makes sense to allow the user to continue working seamlessly. -### setInlineStyleOverride +### `setInlineStyleOverride` -``` +```js static setInlineStyleOverride(editorState: EditorState, inlineStyleOverride: DraftInlineStyle): EditorState ``` + Returns a new `EditorState` object with the specified `DraftInlineStyle` applied as the set of inline styles to be applied to the next inserted characters. -### set +### `set` -``` +```js static set(editorState: EditorState, options: EditorStateRecordType): EditorState ``` + Returns a new `EditorState` object with new options passed in. The method is inherited from the Immutable `record` API. @@ -378,74 +393,81 @@ state tracked in this object. > You should not use the Immutable API when using EditorState objects. > Instead, use the instance getters and static methods above. -### allowUndo +### `allowUndo` -``` +```js allowUndo: boolean; getAllowUndo() ``` + Whether to allow undo/redo behavior in this editor. Default is `true`. Since the undo/redo stack is the major source of memory retention, if you have an editor UI that does not require undo/redo behavior, you might consider setting this to `false`. -### currentContent +### `currentContent` -``` +```js currentContent: ContentState; getCurrentContent() ``` + The currently rendered `ContentState`. See [getCurrentContent()](#getcurrentcontent). -### decorator +### `decorator` -``` +```js decorator: ?DraftDecoratorType; getDecorator() ``` + The current decorator object, if any. Note that the `ContentState` is independent of your decorator. If a decorator is provided, it will be used to decorate ranges of text for rendering. -### directionMap +### `directionMap` -``` +```js directionMap: BlockMap; getDirectionMap() ``` + A map of each block and its text direction, as determined by UnicodeBidiService. You should not manage this manually. -### forceSelection +### `forceSelection` -``` +```js forceSelection: boolean; mustForceSelection() ``` + Whether to force the current `SelectionState` to be rendered. You should not set this property manually -- see -[forceSelection()](#forceselection). +[`forceSelection()`](#forceselection). -### inCompositionMode +### `inCompositionMode` -``` +```js inCompositionMode: boolean; isInCompositionMode() ``` + Whether the user is in IME composition mode. This is useful for rendering the appropriate UI for IME users, even when no content changes have been committed to the editor. You should not set this property manually. -### inlineStyleOverride +### `inlineStyleOverride` -``` +```js inlineStyleOverride: DraftInlineStyle; getInlineStyleOverride() ``` + An inline style value to be applied to the next inserted characters. This is used when keyboard commands or style buttons are used to apply an inline style for a collapsed selection range. @@ -453,21 +475,23 @@ for a collapsed selection range. `DraftInlineStyle` is a type alias for an immutable `OrderedSet` of strings, each of which corresponds to an inline style. -### lastChangeType +### `lastChangeType` -``` +```js lastChangeType: EditorChangeType; getLastChangeType() ``` + The type of content change that took place in order to bring us to our current `ContentState`. This is used when determining boundary states for undo/redo. -### nativelyRenderedContent +### `nativelyRenderedContent` -``` +```js nativelyRenderedContent: ?ContentState; getNativelyRenderedContent() ``` + During edit behavior, the editor may allow certain actions to render natively. For instance, during normal typing behavior in the contentEditable-based component, we can typically allow key events to fall through to print characters in the DOM. @@ -477,12 +501,13 @@ When allowing native rendering behavior, it is appropriate to use the `nativelyRenderedContent` property to indicate that no re-render is necessary for this `EditorState`. -### redoStack +### `redoStack` -``` +```js redoStack: Stack; getRedoStack() ``` + An immutable stack of `ContentState` objects that can be resurrected for redo operations. When performing an undo operation, the current `ContentState` is pushed onto the `redoStack`. @@ -492,22 +517,24 @@ undo/redo behavior, use the `allowUndo` property. See also [undoStack](#undostack). -### selection +### `selection` -``` +```js selection: SelectionState; getSelection() ``` + The currently rendered `SelectionState`. See [acceptSelection()](#acceptselection) and [forceSelection()](#forceselection). You should not manage this property manually. -### treeMap +### `treeMap` -``` +```js treeMap: OrderedMap; ``` + The fully decorated and styled tree of ranges to be rendered in the editor component. The `treeMap` object is generated based on a `ContentState` and an optional decorator (`DraftDecoratorType`). @@ -518,12 +545,13 @@ method. You should not manage this property manually. -### undoStack +### `undoStack` -``` +```js undoStack: Stack; getUndoStack() ``` + An immutable stack of `ContentState` objects that can be restored for undo operations. @@ -535,4 +563,4 @@ onto the `undoStack`. If not, the outgoing `ContentState` is discarded. You should not manage this property manually. If you would like to disable undo/redo behavior, use the `allowUndo` property. -See also [redoStack](#redostack). +See also [`redoStack`](#redostack). diff --git a/docs/APIReference-Entity.md b/docs/APIReference-Entity.md index 85e90d84ff..5b4505eebc 100644 --- a/docs/APIReference-Entity.md +++ b/docs/APIReference-Entity.md @@ -8,12 +8,12 @@ updating entity objects, which are used for annotating text ranges with metadata This module also houses the single store used to maintain entity data. This article is dedicated to covering the details of the API. See the -[advanced topics article on entities](/docs/advanced-topics-entities.html) +[advanced topics article on entities](/docs/advanced-topics-entities) for more detail on how entities may be used. Please note that the API for entity storage and management has changed recently; for details on updating your application -[see our v0.10 API Migration Guide](/docs/v0-10-api-migration.html#content). +[see our v0.10 API Migration Guide](/docs/v0-10-api-migration#content). Entity objects returned by `Entity` methods are represented as [DraftEntityInstance](https://github.com/facebook/draft-js/blob/master/src/model/entity/DraftEntityInstance.js) immutable records. These have a small set of getter functions and should @@ -53,15 +53,16 @@ be used only for retrieval. ## Methods -### create _(Deprecated in favour of [contentState.createEntity](/docs/api-reference-content-state.html#createentity))_ +### `create` _(Deprecated in favour of [`contentState.createEntity`](/docs/api-reference-content-state#createentity))_ -``` +```js create( type: DraftEntityType, mutability: DraftEntityMutability, data?: Object ): string ``` + The `create` method should be used to generate a new entity object with the supplied properties. @@ -70,11 +71,12 @@ are referenced by their string key in `ContentState`. The string value should be used within `CharacterMetadata` objects to track the entity for annotated characters. -### add _(Deprecated in favour of [contentState.addEntity](/docs/api-reference-content-state.html#addentity))_ +### `add` _(Deprecated in favour of [`contentState.addEntity`](/docs/api-reference-content-state#addentity))_ -``` +```js add(instance: DraftEntityInstance): string ``` + In most cases, you will use `Entity.create()`. This is a convenience method that you probably will not need in typical Draft usage. @@ -83,35 +85,38 @@ created, and now need to be added to the `Entity` store. This may occur in cases where a vanilla JavaScript representation of a `ContentState` is being revived for editing. -### get _(Deprecated in favour of [contentState.getEntity](/docs/api-reference-content-state.html#getentity))_ +### `get` _(Deprecated in favour of [`contentState.getEntity`](/docs/api-reference-content-state#getentity))_ -``` +```js get(key: string): DraftEntityInstance ``` + Returns the `DraftEntityInstance` for the specified key. Throws if no instance exists for that key. -### mergeData _(Deprecated in favour of [contentState.mergeEntityData](/docs/api-reference-content-state.html#mergeentitydata))_ +### `mergeData` _(Deprecated in favour of [`contentState.mergeEntityData`](/docs/api-reference-content-state#mergeentitydata))_ -``` +```js mergeData( key: string, toMerge: {[key: string]: any} ): DraftEntityInstance ``` + Since `DraftEntityInstance` objects are immutable, you cannot update an entity's metadata through typical mutative means. The `mergeData` method allows you to apply updates to the specified entity. -### replaceData _(Deprecated in favour of [contentState.replaceEntityData](/docs/api-reference-content-state.html#replaceentitydata))_ +### `replaceData` _(Deprecated in favour of [`contentState.replaceEntityData`](/docs/api-reference-content-state#replaceentitydata))_ -``` +```js replaceData( key: string, newData: {[key: string]: any} ): DraftEntityInstance ``` + The `replaceData` method is similar to the `mergeData` method, except it will totally discard the existing `data` value for the instance and replace it with the specified `newData`. diff --git a/docs/APIReference-KeyBindingUtil.md b/docs/APIReference-KeyBindingUtil.md index 98da3ad7ec..3b0b982dbc 100644 --- a/docs/APIReference-KeyBindingUtil.md +++ b/docs/APIReference-KeyBindingUtil.md @@ -8,9 +8,9 @@ defining key bindings. ## Static Methods -### isCtrlKeyCommand +### `isCtrlKeyCommand()` -``` +```js isCtrlKeyCommand: function( e: SyntheticKeyboardEvent ): boolean @@ -20,26 +20,26 @@ Check whether the `ctrlKey` modifier is *not* being used in conjunction with the `altKey` modifier. If they are combined, the result is an `altGraph` key modifier, which is not handled by this set of key bindings. -### isOptionKeyCommand +### `isOptionKeyCommand()` -``` +```js isOptionKeyCommand: function( e: SyntheticKeyboardEvent ): boolean ``` -### usesMacOSHeuristics +### `usesMacOSHeuristics()` -``` +```js usesMacOSHeuristics: function(): boolean ``` Check whether heuristics that only apply to macOS are used internally, for example when determining the key combination used as command modifier. -### hasCommandModifier +### `hasCommandModifier()` -``` +```js hasCommandModifier: function( e: SyntheticKeyboardEvent ): boolean diff --git a/docs/APIReference-Modifier.md b/docs/APIReference-Modifier.md index 57338744a7..b58e7e2b3b 100644 --- a/docs/APIReference-Modifier.md +++ b/docs/APIReference-Modifier.md @@ -83,9 +83,9 @@ will be the same as the input object if no edit was actually performed. ## Static Methods -### replaceText +### `replaceText()` -``` +```js replaceText( contentState: ContentState, rangeToReplace: SelectionState, @@ -94,6 +94,7 @@ replaceText( entityKey?: ?string ): ContentState ``` + Replaces the specified range of this `ContentState` with the supplied string, with the inline style and entity key applied to the entire inserted string. @@ -101,9 +102,9 @@ Example: On Facebook, when replacing `@abraham lincoln` with a mention of Abraham Lincoln, the entire old range is the target to replace and the mention entity should be applied to the inserted string. -### insertText +### `insertText()` -``` +```js insertText( contentState: ContentState, targetRange: SelectionState, @@ -112,30 +113,33 @@ insertText( entityKey?: ?string ): ContentState ``` + Identical to `replaceText`, but enforces that the target range is collapsed so that no characters are replaced. This is only for convenience, since text edits are so often insertions rather than replacements. -### moveText +### `moveText()` -``` +```js moveText( contentState: ContentState, removalRange: SelectionState, targetRange: SelectionState ): ContentState ``` + Moves the "removal" range to the "target" range, replacing the target text. -### replaceWithFragment +### `replaceWithFragment()` -``` +```js replaceWithFragment( contentState: ContentState, targetRange: SelectionState, fragment: BlockMap ): ContentState ``` + A "fragment" is a section of a block map, effectively only an `OrderedMap` much the same as the full block map of a `ContentState` object. @@ -145,92 +149,99 @@ This method will replace the "target" range with the fragment. Example: When pasting content, we convert the paste into a fragment to be inserted into the editor, then use this method to add it. -### removeRange +### `removeRange()` -``` +```js removeRange( contentState: ContentState, rangeToRemove: SelectionState, removalDirection: DraftRemovalDirection ): ContentState ``` + Remove an entire range of text from the editor. The removal direction is important for proper entity deletion behavior. -### splitBlock +### `splitBlock()` -``` +```js splitBlock( contentState: ContentState, selectionState: SelectionState ): ContentState ``` + Split the selected block into two blocks. This should only be used if the selection is collapsed. -### applyInlineStyle +### `applyInlineStyle()` -``` +```js applyInlineStyle( contentState: ContentState, selectionState: SelectionState, inlineStyle: string ): ContentState ``` + Apply the specified inline style to the entire selected range. -### removeInlineStyle +### `removeInlineStyle()` -``` +```js removeInlineStyle( contentState: ContentState, selectionState: SelectionState, inlineStyle: string ): ContentState ``` + Remove the specified inline style from the entire selected range. -### setBlockType +### `setBlockType()` -``` +```js setBlockType( contentState: ContentState, selectionState: SelectionState, blockType: DraftBlockType ): ContentState ``` + Set the block type for all selected blocks. -### setBlockData +### `setBlockData()` -``` +```js setBlockData( contentState: ContentState, selectionState: SelectionState, blockData: Map ): ContentState ``` + Set the block data for all selected blocks. -### mergeBlockData +### `mergeBlockData()` -``` +```js mergeBlockData( contentState: ContentState, selectionState: SelectionState, blockData: Map ): ContentState ``` + Update block data for all selected blocks. -### applyEntity +### `applyEntity()` -``` +```js applyEntity( contentState: ContentState, selectionState: SelectionState, entityKey: ?string ): ContentState ``` -Apply an entity to the entire selected range, or remove all entities from the -range if `entityKey` is `null`. + +Apply an entity to the entire selected range, or remove all entities from the range if `entityKey` is `null`. diff --git a/docs/APIReference-RichUtils.md b/docs/APIReference-RichUtils.md index feefbdb795..4942c17788 100644 --- a/docs/APIReference-RichUtils.md +++ b/docs/APIReference-RichUtils.md @@ -11,58 +11,58 @@ parameters and return `EditorState` objects. ## Static Methods -### currentBlockContainsLink +### `currentBlockContainsLink()` -``` +```js currentBlockContainsLink( editorState: EditorState ): boolean ``` -### getCurrentBlockType +### `getCurrentBlockType()` -``` +```js getCurrentBlockType( editorState: EditorState ): string ``` -### handleKeyCommand +### `handleKeyCommand()` -``` +```js handleKeyCommand( editorState: EditorState, command: string ): ?EditorState ``` -### insertSoftNewline +### `insertSoftNewline()` -``` +```js insertSoftNewline( editorState: EditorState ): EditorState ``` -### onBackspace +### `onBackspace()` -``` +```js onBackspace( editorState: EditorState ): EditorState? ``` -### onDelete +### `onDelete()` -``` +```js onDelete( editorState: EditorState ): EditorState? ``` -### onTab +### `onTab()` -``` +```js onTab( event: SyntheticEvent, editorState: EditorState, @@ -70,26 +70,26 @@ onTab( ): EditorState ``` -### toggleBlockType +### `toggleBlockType()` -``` +```js toggleBlockType( editorState: EditorState, blockType: string ): EditorState ``` -### toggleCode +### `toggleCode()` -``` +```js toggleCode( editorState: EditorState ): EditorState ``` -### toggleInlineStyle +### `toggleInlineStyle()` -``` +```js toggleInlineStyle( editorState: EditorState, inlineStyle: string @@ -101,9 +101,9 @@ user's selection is collapsed, apply or remove the style for the internal state. If it is not collapsed, apply the change directly to the document state. -### toggleLink +### `toggleLink()` -``` +```js toggleLink( editorState: EditorState, targetSelection: SelectionState, @@ -111,9 +111,9 @@ toggleLink( ): EditorState ``` -### tryToRemoveBlockStyle +### `tryToRemoveBlockStyle()` -``` +```js tryToRemoveBlockStyle( editorState: EditorState ): ContentState? diff --git a/docs/APIReference-SelectionState.md b/docs/APIReference-SelectionState.md index 378f5f2434..3b0f5045c7 100644 --- a/docs/APIReference-SelectionState.md +++ b/docs/APIReference-SelectionState.md @@ -3,9 +3,7 @@ id: api-reference-selection-state title: SelectionState --- -`SelectionState` is an Immutable -[Record](http://facebook.github.io/immutable-js/docs/#/Record/Record) that -represents a selection range in the editor. +`SelectionState` is an Immutable [Record](http://facebook.github.io/immutable-js/docs/#/Record/Record) that represents a selection range in the editor. The most common use for the `SelectionState` object is via `EditorState.getSelection()`, which provides the `SelectionState` currently being rendered in the editor. @@ -42,7 +40,7 @@ and _end_ values. For instance, when extracting a slice of text from a block based on a `SelectionState`, it is irrelevant whether the selection is backward: -``` +```js var selectionState = editorState.getSelection(); var anchorKey = selectionState.getAnchorKey(); var currentContent = editorState.getCurrentContent(); @@ -141,14 +139,14 @@ _Start_ and _end_ values are derived. > Use [Immutable Map API](http://facebook.github.io/immutable-js/docs/#/Record/Record) to > set properties. -> +> > **Example** -> ``` +> +> ```js > const selectionState = SelectionState.createEmpty(); > const selectionStateWithNewFocusOffset = selection.set('focusOffset', 1); > ``` -