FWorksheetLegacy

packages	`@univerjs/sheets-drawing-ui`

APIs

`addFloatDomToColumnHeader`

Add dom at column header, And FloatDOM is registerComponent(BuiltInUIPart.CONTENT)

Signature

addFloatDomToColumnHeader(column: number, layer: IFICanvasFloatDom, domLayout: IDOMAnchor, id?: string): Nullable<{
        id: string;
        dispose: () => void;
    }>

Parameters

column (number) — - The column index to add the float dom.
layer (IFICanvasFloatDom) — - The float dom layer configuration.
domPos — - The anchor configuration of the float dom.
id (string) — - The float dom id, if not given will be auto generated

Returns

(Nullable<{ id: string; dispose: () => void; }>) — float dom id and dispose function

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();

// Register a float button component
const FloatButton = () => {
  const divStyle = {
    width: '100px',
    height: '30px',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    cursor: 'pointer',
  };

  const clickHandler = () => {
    console.warn('click');
  };

  return (
    <div style={divStyle} onClick={clickHandler}>
      FloatButton
    </div>
  );
};
univerAPI.registerComponent('FloatButton', FloatButton);

// Add the float button to the column D header, position is right align, width is 100px, height is 30px, margin is 0
const disposable = fWorksheet.addFloatDomToColumnHeader(
  3,
  {
    componentKey: 'FloatButton',
    allowTransform: false,
  },
  {
    width: 100,
    height: 30,
    marginX: 0,
    marginY: 0,
    horizonOffsetAlign: 'right',
  },
  'myFloatButton'
);
console.log(disposable?.id); // The id of the floating DOM

// Remove the float button after 2 seconds
setTimeout(() => {
  disposable?.dispose();
}, 2000);

`addFloatDomToPosition`

Add a float dom to position.

Signature

addFloatDomToPosition(layer: IFICanvasFloatDom, id?: string): Nullable<{
        id: string;
        dispose: () => void;
    }>

Parameters

layer (IFICanvasFloatDom) — - The float dom layer configuration.
id (string) — - The float dom id, if not given will be auto generated.

Returns

(Nullable<{ id: string; dispose: () => void; }>) — float dom id and dispose function

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()

// You should register components at an appropriate time (e.g., when Univer is loaded)
// This is a React component. For Vue3 components, the third parameter should be `{ framework: 'vue3' }`
univerAPI.registerComponent(
  'myFloatDom',
  ({ data }) => (
    <div style={{ width: '100%', height: '100%', background: '#fff', border: '1px solid #ccc', boxSizing: 'border-box' }}>
      popup content:
      {' '}
      {data?.label}
    </div>
  ),
)

// Add a floating DOM
// If disposable is null, floating DOM addition failed
const disposable = fWorksheet.addFloatDomToPosition({
  componentKey: 'myFloatDom',
  initPosition: {
    startX: 100,
    endX: 300,
    startY: 100,
    endY: 200,
  },

  // Component data
  data: {
    label: 'hahah',
  },
})
console.log(disposable?.id) // The id of the floating DOM

// Remove the floating DOM after 2 seconds
setTimeout(() => {
  disposable?.dispose()
}, 2000)

`addFloatDomToRange`

Add dom over range to FloatDOM, And FloatDOM is registerComponent(BuiltInUIPart.CONTENT)

Signature

addFloatDomToRange(fRange: FRange, layer: IFICanvasFloatDom, domLayout: IDOMAnchor, id?: string): Nullable<{
        id: string;
        dispose: () => void;
    }>

Parameters

range — - The range to add the float dom.
layer (IFICanvasFloatDom) — - The float dom layer configuration.
domLayout (IDOMAnchor) — - The anchor configuration of the float dom.
id (string) — - The float dom id, if not given will be auto generated

Returns

(Nullable<{ id: string; dispose: () => void; }>) — float dom id and dispose function

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()

// Register a range loading component
function RangeLoading() {
  const divStyle = {
    width: '100%',
    height: '100%',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    transformOrigin: 'top left',
  }

  return (
    <div style={divStyle}>
      Loading...
    </div>
  )
}
univerAPI.registerComponent('RangeLoading', RangeLoading)

// Add the range loading component covering the range A1:C3
const fRange = fWorksheet.getRange('A1:C3')
const disposable = fWorksheet.addFloatDomToRange(fRange, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading')
console.log(disposable?.id) // The id of the floating DOM

// Remove the floating DOM after 2 seconds
setTimeout(() => {
  disposable?.dispose()
}, 2000)

// another example-------------------
// Register a float button component
function FloatButton() {
  const divStyle = {
    width: '100px',
    height: '30px',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    cursor: 'pointer',
  }

  const clickHandler = () => {
    console.warn('click')
  }

  return (
    <div style={divStyle} onClick={clickHandler}>
      FloatButton
    </div>
  )
}
univerAPI.registerComponent('FloatButton', FloatButton)

// Add the float button to the range A5:C7, position is start from A5 cell, and width is 100px, height is 30px, margin is 100% of range width and height
const fRange2 = fWorksheet.getRange('A5:C7')
const disposable2 = fWorksheet.addFloatDomToRange(
  fRange2,
  {
    componentKey: 'FloatButton',
  },
  {
    width: 100,
    height: 30,
    marginX: '100%', // margin percent to range width, or pixel
    marginY: '100%',
  },
  'myFloatButton',
)
console.log(disposable2?.id) // The id of the floating DOM

`batchUpdateFloatDoms`

Batch update float doms

Signature

batchUpdateFloatDoms(updates: Array<{ id: string; config: Partial<Omit<IFCanvasFloatDomResult, 'id'>> }>): this

Parameters

updates (Array<{ id: string; config: Partial<Omit<IFCanvasFloatDomResult, 'id'>> }>) — - array of update configs

Returns

(this) — The worksheet instance for chaining

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()

// Update multiple float doms at once
const allFloatDoms = fWorksheet.getAllFloatDoms()
fWorksheet.batchUpdateFloatDoms(allFloatDoms.map((floatDom, index) => {
  if (floatDom.id === 'MyFloatDomId') {
    return {
      id: floatDom.id,
      config: {
        position: {
          left: 100,
          top: 100,
        },
        data: {
          label: 'Updated',
        },
      },
    }
  }

  return {
    id: floatDom.id,
    config: {
      position: {
        left: 300,
        top: 100,
      },
    },
  }
}))

`deleteImages`

Delete images from the sheet

Signature

deleteImages(sheetImages: FOverGridImage[]): FWorksheet

Parameters

sheetImages (FOverGridImage[]) — - The images to delete

Returns

(FWorksheet) — The FWorksheet instance for chaining

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const image = fWorksheet.getImages()[0]

// Delete the first image of the sheet
fWorksheet.deleteImages([image])

`getActiveImages`

Get the current selected images.

Signature

getActiveImages(): FOverGridImage[]

Returns

(FOverGridImage[]) — The FOverGridImage instances

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const images = fWorksheet.getActiveImages()
images.forEach((image) => {
  console.log(image, image.getId())
})

`getAllFloatDoms`

Get all float doms in current worksheet

Signature

getAllFloatDoms(): IFCanvasFloatDomResult[]

Returns

(IFCanvasFloatDomResult[]) — array of float dom info

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const allFloatDoms = fWorksheet.getAllFloatDoms()
allFloatDoms.forEach((floatDom) => {
  console.log('Float dom ID:', floatDom.id)
  console.log('Position:', floatDom.position)
})

`getFloatDomById`

Get float dom by id

Signature

getFloatDomById(id: string): Nullable<IFCanvasFloatDomResult>

Parameters

id (string) — - float dom id

Returns

(Nullable<IFCanvasFloatDomResult>) — float dom info or null if not found

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const floatDom = fWorksheet.getFloatDomById('myFloatDomId')
if (floatDom) {
  console.log('Float dom position:', floatDom.position)
  console.log('Component key:', floatDom.componentKey)
  console.log('Custom data:', floatDom.data)
}

`getImageById`

Get image by drawing id

Signature

getImageById(id: string): FOverGridImage | null

Parameters

id (string) — - The drawing id of the image

Returns

(FOverGridImage | null) — The FOverGridImage instance

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const image = fWorksheet.getImageById('xxxx')
console.log(image)

`getImages`

Get all images of the sheet.

Signature

getImages(): FOverGridImage[]

Returns

(FOverGridImage[]) — The FOverGridImage instances

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const images = fWorksheet.getImages()
images.forEach((image) => {
  console.log(image, image.getId())
})

`insertImage`

Insert an image to the sheet

Signature

insertImage(url: IFBlobSource | string, column?: number, row?: number, offsetX?: number, offsetY?: number): Promise<boolean>

Parameters

url (IFBlobSource | string) — - The image url
url (IFBlobSource | string) — - The image url
column (number) — - The column index to insert the image
row (number) — - The row index to insert the image
url (IFBlobSource | string) — - The image url
column (number) — - The column index to insert the image
row (number) — - The row index to insert the image
offsetX (number) — - The column offset, pixel unit
offsetY (number) — - The row offset, pixel unit

Returns

(Promise<boolean>) — true if the image is inserted successfully

Examples

// Insert an image to the sheet, default position is A1
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')
console.log(result)

// Insert an image to the sheet, position is F6
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', 5, 5)
console.log(result)

// Insert an image to the sheet, position is F6, offset is 10px
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', 5, 5, 10, 10)
console.log(result)

`insertImages`

Insert images to the sheet

Signature

insertImages(sheetImages: ISheetImage[]): FWorksheet

Parameters

sheetImages (ISheetImage[]) — - The images to insert

Returns

(FWorksheet) — The FWorksheet instance for chaining

Examples

// create a new image builder and set image source.
// then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image = await fWorksheet.newOverGridImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
  .setColumn(5)
  .setRow(5)
  .setWidth(500)
  .setHeight(300)
  .buildAsync()
fWorksheet.insertImages([image])

// update the image width to 100px and height to 50px
setTimeout(async () => {
  const imageBuilder = fWorksheet.getImageById(image.drawingId).toBuilder()
  const newImage = await imageBuilder.setWidth(100).setHeight(50).buildAsync()
  fWorksheet.updateImages([newImage])
}, 4000)

`newOverGridImage`

Create a new over grid image builder.

Signature

newOverGridImage(): FOverGridImageBuilder

Returns

(FOverGridImageBuilder) — The FOverGridImageBuilder instance

Examples

// create a new image builder and set image source.
// then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image = await fWorksheet.newOverGridImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
  .setColumn(5)
  .setRow(5)
  .setWidth(500)
  .setHeight(300)
  .buildAsync()
fWorksheet.insertImages([image])

`onImageChanged`

Hook when a image is changed.

Deprecated use univerAPI.addEvent(univerAPI.Event.OverGridImageChanged, (params) => \{\}) as instead

Signature

onImageChanged(callback: (images: FOverGridImage[]) => void): IDisposable

Parameters

param — )} callback - The callback function when a image is changed.

`onImageDeleted`

Hook when a image is deleted.

Deprecated use univerAPI.addEvent(univerAPI.Event.OverGridImageRemoved, (params) => \{\}) as instead

Signature

onImageDeleted(callback: (images: FOverGridImage[]) => void): IDisposable

Parameters

param — )} callback - The callback function when a image is deleted.

`onImageInserted`

Hook when a image is inserted.

Deprecated use univerAPI.addEvent(univerAPI.Event.OverGridImageInserted, (params) => \{\}) as instead

Signature

onImageInserted(callback: (images: FOverGridImage[]) => void): IDisposable

Parameters

param — )} callback - The callback function when a image is inserted.

`removeFloatDom`

Remove float dom by id

Signature

removeFloatDom(id: string): this

Parameters

id (string) — - float dom id

Returns

(this) — The worksheet instance for chaining

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const firstFloatDom = fWorksheet.getAllFloatDoms()[0]

if (!firstFloatDom) return

// Remove the first float dom
fWorksheet.removeFloatDom(firstFloatDom.id)

`saveCellImagesAsync`

Save all cell images from specified ranges to the file system. This method will open a directory picker dialog and save all images to the selected directory.

Signature

saveCellImagesAsync(options?: ISaveCellImagesOptions, ranges?: FRange[]): Promise<boolean>

Parameters

options (ISaveCellImagesOptions) — - Options for saving images
ranges (FRange[]) — - The ranges to get cell images from. If not provided, all images in the worksheet will be saved.

Returns

(Promise<boolean>) — True if images are saved successfully, otherwise false

Examples

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Save cell images from multiple ranges
const range1 = fWorksheet.getRange('A1:B10')
const range2 = fWorksheet.getRange('D1:E10')

// Save with default options (using cell address as file name)
await fWorksheet.saveCellImagesAsync(undefined, [range1, range2])

// Save with custom options
await fWorksheet.saveCellImagesAsync({
  useCellAddress: true,
  useColumnIndex: 2, // Use values from column C for file names
}, [range1, range2])

`updateFloatDom`

Update float dom position and properties

Signature

updateFloatDom(id: string, config: Partial<Omit<IFCanvasFloatDomResult, 'id'>>): this

Parameters

id (string) — - float dom id
config (Partial<Omit<IFCanvasFloatDomResult, 'id'>>) — - new float dom config

Returns

(this) — The worksheet instance for chaining

Examples

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const firstFloatDom = fWorksheet.getAllFloatDoms()[0]

if (!firstFloatDom) return

// Update first float dom position and size
fWorksheet.updateFloatDom(firstFloatDom.id, {
  position: {
    left: 100,
    top: 100,
    width: 200,
    height: 150,
    angle: 45, // rotate 45 degrees
  },
})

// Update first float dom data
fWorksheet.updateFloatDom(firstFloatDom.id, {
  data: {
    label: 'Updated Label',
    color: '#ff0000',
  },
})

// Disable the first float dom from transform
fWorksheet.updateFloatDom(firstFloatDom.id, {
  allowTransform: false,
})

`updateImages`

Update images to the sheet

Signature

updateImages(sheetImages: ISheetImage[]): FWorksheet

Parameters

sheetImages (ISheetImage[]) — - The images to update

Returns

(FWorksheet) — The FWorksheet instance for chaining

Examples

// create a new image builder and set image source.
// then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image = await fWorksheet.newOverGridImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
  .setColumn(5)
  .setRow(5)
  .setWidth(500)
  .setHeight(300)
  .buildAsync()
fWorksheet.insertImages([image])

// update the image width to 100px and height to 50px after 4 seconds
setTimeout(async () => {
  const imageBuilder = fWorksheet.getImageById(image.drawingId).toBuilder()
  const newImage = await imageBuilder.setWidth(100).setHeight(50).buildAsync()
  fWorksheet.updateImages([newImage])
}, 4000)

Table of Contents