prosemirror-search v1.0.0
prosemirror-search
[ WEBSITE | ISSUES | FORUM | GITTER ]
This module defines an API for searching through ProseMirror documents, search/replace commands, and a plugin that highlights the matches of a given search query.
When using this module, you should either load
style/search.css
into your page, or define your own styles for the
ProseMirror-search-match
(search match) and
ProseMirror-active-search-match
(the active match) classes.
The project page has more information, a number of examples and the documentation.
This code is released under an MIT license. There's a forum for general discussion and support requests, and the Github bug tracker is the place to report issues.
We aim to be an inclusive, welcoming community. To make that explicit, we have a code of conduct that applies to communication around the project.
API
search
(options?: {initialQuery?: SearchQuery, initialRange?: {from: number, to: number}} = {}) → Plugin
\ Returns a plugin that stores a current search query and searched range, and highlights matches of the query.
class SearchQuery
new
SearchQuery
(config: Object)
\ Create a query object.config
: Object
search
: string
\ The search string.caseSensitive
?: boolean
\ Controls whether the search should be case-sensitive.literal
?: boolean
\ By default, string search will replace\n
,\r
, and\t
in the query with newline, return, and tab characters. When this is set to true, that behavior is disabled.regexp
?: boolean
\ When true, interpret the search string as a regular expression.replace
?: string
\ The replace text.wholeWord
?: boolean
\ Enable whole-word matching.
search
: string
\ The search string (or regular expression).caseSensitive
: boolean
\ Indicates whether the search is case-sensitive.literal
: boolean
\ By default, string search will replace\n
,\r
, and\t
in the query with newline, return, and tab characters. When this is set to true, that behavior is disabled.regexp
: boolean
\ When true, the search string is interpreted as a regular expression.replace
: string
\ The replace text, or the empty string if no replace text has been given.valid
: boolean
\ Whether this query is non-empty and, in case of a regular expression search, syntactically valid.wholeWord
: boolean
\ When true, matches that contain words are ignored when there are further word characters around them.eq
(other: SearchQuery) → boolean
\ Compare this query to another query.findNext
(state: EditorState, from?: number = 0, to?: number = state.doc.content.size) → SearchResult
\ Find the next occurrence of this query in the given range.findPrev
(state: EditorState, from?: number = state.doc.content.size, to?: number = 0) → SearchResult
\ Find the previous occurrence of this query in the given range. Note that, ifto
is given, it should be less thanfrom
.getReplacements
(state: EditorState, result: SearchResult) → {from: number, to: number, insert: Slice}[]
\ Get the ranges that should be replaced for this result. This can return multiple ranges whenthis.replace
contains$1
/$&
-style placeholders, in which case the preserved content is skipped by the replacements.Ranges are sorted by position, and
from
/to
positions all refer to positions instate.doc
. When applying these, you'll want to either apply them from back to front, or map these positions through your transaction's current mapping.
interface SearchResult
A matched instance of a search query. match
will be non-null
only for regular expression queries.
from
: number
to
: number
match
: RegExpMatchArray
These functions can be used to manipulate the active search state:
getSearchState
(state: EditorState) → {query: SearchQuery, range: {from: number, to: number}}
\ Get the current active search query and searched range. Will returnundefined
is the search plugin isn't active.
setSearchState
(tr: Transaction, query: SearchQuery, range?: {from: number, to: number} = null) → Transaction
\ Add metadata to a transaction that updates the active search query and searched range, when dispatched.
getMatchHighlights
(state: EditorState) → DecorationSet
\ Access the decoration set holding the currently highlighted search matches in the document.
Commands
findNext
: Command
\ Find the next instance of the search query after the current selection and move the selection to it.
findPrev
: Command
\ Find the previous instance of the search query and move the selection to it.
findNextNoWrap
: Command
\ Find the next instance of the search query and move the selection to it. Don't wrap around at the end of document or search range.
findPrevNoWrap
: Command
\ Find the previous instance of the search query and move the selection to it. Don't wrap at the start of the document or search range.
replaceNext
: Command
\ Replace the currently selected instance of the search query, and move to the next one. Or select the next match, if none is already selected.
replaceNextNoWrap
: Command
\ Replace the next instance of the search query. Don't wrap around at the end of the document.
replaceCurrent
: Command
\ Replace the currently selected instance of the search query, if any, and keep it selected.
replaceAll
: Command
\ Replace all instances of the search query.