Find & Replace

The Find & Replace feature allows users to quickly search for specific content in spreadsheets and replace it, supporting various matching options to help users efficiently process data.

Playground

Live preview

Preset Mode

Installation

npm install @univerjs/preset-sheets-find-replace

Usage

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsFindReplacePreset } from '@univerjs/preset-sheets-find-replace'
import UniverPresetSheetsFindReplaceEnUS from '@univerjs/preset-sheets-find-replace/locales/en-US'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-find-replace/lib/index.css'

const { univerAPI } = createUniver({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsFindReplaceEnUS, 
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsFindReplacePreset(), 
  ],
})

Plugin Mode

Installation

npm install @univerjs/find-replace @univerjs/sheets-find-replace

Usage

import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverFindReplacePlugin } from '@univerjs/find-replace'
import FindReplaceEnUS from '@univerjs/find-replace/locale/en-US'
import { UniverSheetsFindReplacePlugin } from '@univerjs/sheets-find-replace'
import SheetsFindReplaceEnUS from '@univerjs/sheets-find-replace/locale/en-US'

import '@univerjs/find-replace/lib/index.css'

import '@univerjs/sheets-find-replace/facade'

const univer = new Univer({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      FindReplaceEnUS, 
      SheetsFindReplaceEnUS, 
    ),
  },
})

univer.registerPlugin(UniverFindReplacePlugin) 
univer.registerPlugin(UniverSheetsFindReplacePlugin)

Facade API

Complete Facade API type definitions can be found in the FacadeAPI.

Importing

Plugin mode note

Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.

import '@univerjs/sheets-find-replace/facade'

Create Text Finder

univerAPI.createTextFinderAsync() creates a text finder and returns an FTextFinder instance.

Here are some member methods on FTextFinder:

Method	Description
findAll	Get all the matched cells of the current sheet, the current matched cell is the last matched cell
findNext	Get the next matched cell of the current sheet, if exists return the next matched cell and move the current matched cell to the next matched cell
findPrevious	Get the previous matched cell of the current sheet, if exists return the previous matched cell and move the current matched cell to the previous matched cell
getCurrentMatch	Get the current matched cell of the current sheet
matchCaseAsync	Set the match case option, if true, the find operation will match case, otherwise, the find operation will ignore case
matchEntireCellAsync	Set the match entire cell option, if true, the find operation will match entire cell value, otherwise, the find operation will match part of the cell value
matchFormulaTextAsync	Set the match formula text option, if true, the find operation will match formula text, otherwise, the find operation will match value
replaceAllWithAsync	Replace all the matched text with the given text
replaceWithAsync	Replace the current matched text with the given text
ensureCompleteAsync	Ensure the find operation is completed. Especially when the current sheet changed use this method to ensure the find operation is completed

// Assume the current sheet is empty sheet.
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set some values to the range A1:D10.
const fRange = fWorksheet.getRange('A1:D10')
fRange.setValues([
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
  [6, 7, 8, 9],
  [7, 8, 9, 10],
  [8, 9, 10, 11],
  [9, 10, 11, 12],
  [10, 11, 12, 13],
])

// Create a text-finder to find the text '5'.
const textFinder = await univerAPI.createTextFinderAsync('5')

// Find all cells that contain the text '5'.
const matchCells = textFinder.findAll()
matchCells.forEach((cell) => {
  cell.getA1Notation() // D2, C3, B4, A5
})

Table of Contents