Plage, sélection et cellule
Accédez à la section correspondant à votre tâche. Opérations de base, exemples avancés, configuration et dépannage restent sur cette page ; les contrats API complets sont maintenus dans Reference.
- Plage
- Sélection
- Opérations avancées sur les plages
- Navigation au bord de la feuille
- Événements et édition des cellules
- Dépannage de l’édition des cellules
Plage
Une plage désigne une zone rectangulaire d’une feuille de calcul. Elle est définie par les numéros de la ligne et de la colonne de départ, sa hauteur et sa largeur, ou par les numéros de la ligne et de la colonne de fin.
La plupart des opérations d’un tableur peuvent être réalisées avec l’API Range, notamment définir ou obtenir des valeurs et des styles.
Pour consulter la définition complète de l’API Facade liée aux plages, reportez-vous à la documentation de FRange.
Créer une plage
Pour obtenir une plage, vous devez connaître les numéros de la ligne et de la colonne de départ, ainsi que sa hauteur et sa largeur.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Create a range of A1 cell:const fRange = fWorksheet.getRange(0, 0)console.log(fRange, fRange.getA1Notation())// Creates a range of A1:B2:const fRange2 = fWorksheet.getRange(0, 0, 2, 2)console.log(fRange2, fRange2.getA1Notation())const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Get the A1:B2 range on named Sheet1const fRange1 = fWorksheet.getRange('Sheet1!A1:B2')console.log(fRange1, fRange1.getA1Notation())// Get a single cell A1const fRange2 = fWorksheet.getRange('A1')console.log(fRange2, fRange2.getA1Notation())// Get the A1:B2 rangeconst fRange3 = fWorksheet.getRange('A1:B2')console.log(fRange3, fRange3.getA1Notation())// Get the range of column Aconst fRange4 = fWorksheet.getRange('A:A')console.log(fRange4, fRange4.getA1Notation())// Get the range of row 1const fRange5 = fWorksheet.getRange('1:1')console.log(fRange5, fRange5.getA1Notation())Obtenir les données d’une plage
Obtenir la valeur de la première cellule de la plage
const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValue()) // The value of the top-left cell in the rangeconsole.log(fRange.getRawValue()) // The raw value of the top-left cell in the rangeconsole.log(fRange.getDisplayValue()) // The displayed value of the top-left cell in the rangeconsole.log(fRange.getCellData()) // The cell data of the top-left cell in the rangeconst value = fRange.getValue(true)console.log(value)if (value !== null && typeof value === 'object') { console.log(value.toPlainText())}Utilisez getValue(true) pour conserver le texte enrichi. Une cellule vide renvoie null / undefined ; les autres valeurs sont des chaînes, des nombres ou des booléens. Appelez toPlainText() uniquement sur un objet de texte enrichi.
Obtenir les valeurs de toutes les cellules de la plage
const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValues()) // The values of all cells in the rangeconsole.log(fRange.getRawValues()) // The raw values of all cells in the rangeconsole.log(fRange.getDisplayValues()) // The displayed values of all cells in the rangeconsole.log(fRange.getCellDataGrid()) // The cell data of all cells in the rangeconsole.log(fRange.getValues(true))Obtenir toutes les formules de la plage
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getFormula()) // The formula of the top-left cell in the rangeconsole.log(fRange.getFormulas()) // The formulas of all cells in the rangeDéfinir les valeurs d’une plage
Définir une valeur unique
Si vous transmettez une valeur ou un objet de cellule, toutes les cellules de la plage sont remplacées. Si la valeur commence par =, elle est interprétée comme une formule.
Par exemple, pour attribuer la valeur Hello, Univer à la plage A1:B2 :
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setValue('Hello, Univer')Définissez C1 sur =A1+B1 pour séparer le résultat des cellules sources :
const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('C1')fRange.setValue('=A1+B1')Attribuer un objet de cellule à la plage A1:B2 :
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setValue({ v: 'Hello, Univer', custom: { key: 'value', },})Pour ne définir que la valeur de la cellule supérieure gauche de la plage, utilisez la méthode FRange.setValueForCell :
fRange.setValueForCell('Hello, Univer')Définir plusieurs valeurs avec un tableau
Les dimensions du tableau doivent correspondre à celles de la plage.
Vous pouvez transmettre des valeurs ou des objets de cellule.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setValues([ ['A1', 'B1'], ['A2', 'B2'],])fRange.setValues([ [{ v: 'A1' }, { v: 'B1' }], [{ v: 'A2' }, { v: 'B2' }],])Définir plusieurs valeurs avec un objet
Si vous transmettez un objet, son index principal représente le numéro de ligne et son index secondaire le numéro de colonne. Les dimensions de la plage et de l’objet ne doivent pas nécessairement correspondre.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setValues({ 0: { 0: 'A1', 1: 'B1', }, 1: { 0: 'A2', 1: 'B2', },})Effacer les données d’une plage
- La méthode
FRange.clearefface le contenu et la mise en forme de la plage. - La méthode
FRange.clearContentefface le contenu de la plage. - La méthode
FRange.clearFormatefface la mise en forme de la plage.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorkSheet = fWorkbook.getActiveSheet()const fRange = fWorkSheet.getRange('A1:D10')// Clears content and formatting information of the range.fRange.clear()Obtenir le style d’une plage
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellStyleData()) // The style data of the top-left cell in the rangeconsole.log(fRange.getCellStyle()) // The style of the top-left cell in the rangeconsole.log(fRange.getCellStyles()) // The styles of all cells in the rangeDéfinir le style d’une plage
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange .setValues([ [1, 2], [3, 4], ]) .setFontWeight('bold') .setFontLine('underline') .setFontFamily('Arial') .setFontSize(24) .setFontColor('red')Effacer le style d’une plage
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setFontWeight(null).setFontLine(null).setFontFamily(null).setFontSize(null).setFontColor(null)Sélection
Univer Sheets prend en charge les sélections multiples. Une sélection est donc un tableau de plages, dont vous pouvez manipuler les données avec l’API Range.
Des API permettent également d’obtenir ou de définir la sélection actuelle et d’écouter ses modifications.
Pour consulter la définition complète de l’API Facade liée aux sélections, reportez-vous à la documentation de FSelection.
Obtenir la sélection active
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Activate the new selection of A1:B2const fRange = fWorksheet.getRange('A1:B2')fRange.activate()// Get the current active selectionconst fSelection = fWorksheet.getSelection()console.log(fSelection)const activeRange = fSelection.getActiveRange()console.log(activeRange.getA1Notation()) // A1:B2Définir la sélection
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Set the selection to A1:B2 by FRangeconst fRange = fWorksheet.getRange('A1:B2')fRange.activate()// Set the selection to C1:D2 by FWorksheetfWorksheet.setActiveSelection(fWorksheet.getRange('C1:D2'))Obtenir la cellule active
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Activate the new selection of A10:B11const fRange = fWorksheet.getRange('A10:B11')fRange.activate()// Get the current active celllet fSelection = fWorksheet.getSelection()const { actualRow, actualColumn } = fSelection.getCurrentCell()console.log(fWorksheet.getRange(actualRow, actualColumn).getA1Notation()) // A10// Update the new active cell to B11fSelection = fSelection.updatePrimaryCell(fWorksheet.getRange('B11'))const { actualRow: newRow, actualColumn: newColumn } = fSelection.getCurrentCell()console.log(fWorksheet.getRange(newRow, newColumn).getA1Notation()) // B11Désactiver, activer, masquer ou afficher la sélection
Lorsqu’elle est désactivée, la sélection ne réagit plus. transparentSelection la rend invisible : contrairement à disableSelection, elle continue de fonctionner, mais vous ne la voyez plus.
const fWorkbook = univerAPI.getActiveWorkbook()// Disable selectionfWorkbook.disableSelection()// Enable selectionfWorkbook.enableSelection()// Hide selectionfWorkbook.transparentSelection()// Show selectionfWorkbook.showSelection()Écouter les modifications de la sélection
univerAPI.addEvent(univerAPI.Event.SelectionChanged, (params) => { const { worksheet, workbook, selections } = params console.log(params)})Cellule
Les données des cellules sont stockées dans la feuille de calcul sous forme de Map bidimensionnelle. Le premier index représente le numéro de ligne et le second, le numéro de colonne.
Voici un objet de cellule type :
const data = { v: 'Hello, Univer', s: 'styleId', t: CellValueType.STRING,}Pour une description détaillée des champs, consultez Configurer les données d’une cellule.
Bon à savoir
- Les opérations sur une cellule peuvent être considérées comme des opérations sur une plage d’une ligne et d’une colonne, de hauteur 1 et de largeur 1. Pour les opérations sur les plages, consultez Plage.
- Le plugin Univer API stocke également les attributs étendus des cellules dans la propriété
resourcesduWorkbook. Consultez Modèle personnalisé de plugin.
Opérations avancées sur les plages
Insérer des cellules
La méthode FRange.insertCells insère des cellules vides dans la plage. Les données existantes de la feuille sont décalées, selon la dimension indiquée, en s’éloignant de la plage insérée.
// Assume the active sheet empty sheet.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const values = [ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8],]// Set the range A1:D5 with some values, the range A1:D5 will be:// 1 | 2 | 3 | 4// 2 | 3 | 4 | 5// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8const fRange = fWorksheet.getRange('A1:D5')fRange.setValues(values)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]// Insert the empty cells into the range A1:B2 along the columns dimension, the range A1:D5 will be:// | | 1 | 2// | | 2 | 3// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8const fRange2 = fWorksheet.getRange('A1:B2')fRange2.insertCells(univerAPI.Enum.Dimension.COLUMNS)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[null, null, 1, 2], [null, null, 2, 3], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]// Set the range A1:D5 values again, the range A1:D5 will be:// 1 | 2 | 3 | 4// 2 | 3 | 4 | 5// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8fRange.setValues(values)// Insert the empty cells into the range A1:B2 along the rows dimension, the range A1:D5 will be:// | | 3 | 4// | | 4 | 5// 1 | 2 | 5 | 6// 2 | 3 | 6 | 7// 3 | 4 | 7 | 8const fRange3 = fWorksheet.getRange('A1:B2')fRange3.insertCells(univerAPI.Enum.Dimension.ROWS)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[null, null, 3, 4], [null, null, 4, 5], [1, 2, 5, 6], [2, 3, 6, 7], [3, 4, 7, 8]]Supprimer des cellules
La méthode FRange.deleteCells supprime cette plage de cellules. Les données existantes de la feuille sont décalées, selon la dimension indiquée, vers la plage supprimée.
// Assume the active sheet empty sheet.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const values = [ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8],]// Set the range A1:D5 with some values, the range A1:D5 will be:// 1 | 2 | 3 | 4// 2 | 3 | 4 | 5// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8const fRange = fWorksheet.getRange('A1:D5')fRange.setValues(values)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]// Delete the range A1:B2 along the columns dimension, the range A1:D5 will be:// 3 | 4 | |// 4 | 5 | |// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8const fRange2 = fWorksheet.getRange('A1:B2')fRange2.deleteCells(univerAPI.Enum.Dimension.COLUMNS)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[3, 4, null, null], [4, 5, null, null], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]// Set the range A1:D5 values again, the range A1:D5 will be:// 1 | 2 | 3 | 4// 2 | 3 | 4 | 5// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8fRange.setValues(values)// Delete the range A1:B2 along the rows dimension, the range A1:D5 will be:// 3 | 4 | 3 | 4// 4 | 5 | 4 | 5// 5 | 6 | 5 | 6// | | 6 | 7// | | 7 | 8const fRange3 = fWorksheet.getRange('A1:B2')fRange3.deleteCells(univerAPI.Enum.Dimension.ROWS)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[3, 4, 3, 4], [4, 5, 4, 5], [5, 6, 5, 6], [null, null, 6, 7], [null, null, 7, 8]]Fusionner des cellules
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Merge B1:B2const fRange = fWorksheet.getRange('B1:B2')fRange.merge()console.log(fRange.isMerged()) // true// A1:B2 is mergedconst fRange2 = fWorksheet.getRange('A1:B2')console.log(fRange2.isMerged()) // falseconsole.log(fRange2.isPartOfMerge()) // true// Break apart the merged rangefRange2.breakApart()// merge horizontally: fRange2.mergeAcross();// merge vertically: fRange2.mergeVertically();// Get all merged ranges in the worksheet: fWorksheet.getMergedRanges();Mettre une plage en surbrillance
La méthode FRange.highlight met la plage en surbrillance avec le style et la cellule principale indiqués.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Highlight the range C3:E5 with default styleconst fRange = fWorksheet.getRange('C3:E5')fRange.highlight()// Highlight the range C7:E9 with custom style and primary cell D8const fRange2 = fWorksheet.getRange('C7:E9')const primaryCell = fWorksheet.getRange('D8').getRange()const disposable = fRange2.highlight( { stroke: 'red', fill: 'yellow', }, { ...primaryCell, actualRow: primaryCell.startRow, actualColumn: primaryCell.startColumn, },)// Remove the range C7:E9 highlight after 5 secondssetTimeout(() => { disposable.dispose()}, 5000)Répartir le texte en colonnes
La méthode FRange.splitTextToColumns répartit le texte de la plage en colonnes selon le séparateur indiqué.
Exemple avec le séparateur par défaut :
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// A1:A3 has following values:// A |// 1,2,3 |// 4,,5,6 |const fRange = fWorksheet.getRange('A1:A3')fRange.setValues([['A'], ['1,2,3'], ['4,,5,6']])// After calling splitTextToColumns(true), the range will be:// A | |// 1 | 2 | 3// 4 | 5 | 6fRange.splitTextToColumns(true)// After calling splitTextToColumns(false), the range will be:// A | | |// 1 | 2 | 3 |// 4 | | 5 | 6fRange.splitTextToColumns(false)Exemple avec un séparateur défini :
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// A1:A3 has following values:// A |// 1;;2;3 |// 1;,2;3 |const fRange = fWorksheet.getRange('A1:A3')fRange.setValues([['A'], ['1;;2;3'], ['1;,2;3']])// After calling splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Semicolon|univerAPI.Enum.SplitDelimiterType.Comma), the range will be:// A | | |// 1 | | 2 | 3// 1 | | 2 | 3fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Semicolon | univerAPI.Enum.SplitDelimiterType.Comma)// After calling splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Semicolon|univerAPI.Enum.SplitDelimiterType.Comma), the range will be:// A | |// 1 | 2 | 3// 1 | 2 | 3fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Semicolon | univerAPI.Enum.SplitDelimiterType.Comma)Exemple avec un séparateur personnalisé :
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// A1:A3 has following values:// A |// 1#2#3 |// 4##5#6 |const fRange = fWorksheet.getRange('A1:A3')fRange.setValues([['A'], ['1#2#3'], ['4##5#6']])// After calling splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#'), the range will be:// A | | |// 1 | 2 | 3 |// 4 | | 5 | 6fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#')// After calling splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#'), the range will be:// A | |// 1 | 2 | 3// 4 | 5 | 6fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#')Obtenir les coordonnées de la plage
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellRect()) // width、heigh、left、right、top、bottom、x、yObtenir simultanément les informations de fusion et les coordonnées de la plage
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCell())Navigation au bord de la feuille
allowArrowKeyWrapOnSheetBoundary contrôle le passage à une autre ligne ou colonne lorsque les flèches atteignent le bord de la feuille. La valeur par défaut est true ; false arrête le déplacement au bord. Le parcours cyclique avec Entrée/Tab dans une sélection reste inchangé. Avec un preset, placez cette option dans sheets ; avec les plugins, passez-la directement à UniverSheetsUIPlugin.
univer.registerPlugin(UniverSheetsUIPlugin, { allowArrowKeyWrapOnSheetBoundary: false,})createUniver({ presets: [ UniverSheetsCorePreset({ sheets: { allowArrowKeyWrapOnSheetBoundary: false, }, }), ],})Événements et édition des cellules
Ces exemples couvrent le pointeur, le rendu, l’édition et le presse-papiers. Consultez Events Reference pour la liste complète et les types des paramètres. En mode plugin, importez @univerjs/sheets-ui/facade avant de vous abonner ; le preset Sheets Core l’inclut déjà. Libérez les abonnements à la suppression du composant ou de la page.
Exemple d’utilisation
Tous les événements peuvent être écoutés avec la méthode addEvent. Le format de base est le suivant :
import '@univerjs/sheets-ui/facade'const subscription = univerAPI.addEvent(univerAPI.Event.CellClicked, ({ row, column }) => { console.log(row, column)})// Call subscription.dispose() when the owning component or page is removed.Événement CellPointerMove
L’événement CellPointerMove est déclenché lorsque la souris se déplace sur une cellule. Il fournit des informations sur la cellule située sous le pointeur.
univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => { // Get event parameters const { worksheet, workbook, row, column } = params console.log('Current cell position:', worksheet.getRange(row, column).getA1Notation())})Événement CellPointerDown
L’événement CellPointerDown est déclenché lorsque le bouton de la souris est enfoncé sur une cellule.
univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => { const { worksheet, workbook, row, column } = params console.log('Mouse down cell:', worksheet.getRange(row, column).getA1Notation())})Événement CellPointerUp
L’événement CellPointerUp est déclenché lorsque le bouton de la souris est relâché sur une cellule.
univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => { const { worksheet, workbook, row, column } = params console.log('Mouse up cell:', worksheet.getRange(row, column).getA1Notation())})Événement CellHover
L’événement CellHover est déclenché lorsque la souris survole une cellule.
univerAPI.addEvent(univerAPI.Event.CellHover, (params) => { const { worksheet, workbook, row, column } = params console.log('Hovered cell:', worksheet.getRange(row, column).getA1Notation())})Événement DragOver
L’événement DragOver est déclenché lorsqu’un élément est glissé au-dessus d’une cellule.
univerAPI.addEvent(univerAPI.Event.DragOver, (params) => { const { worksheet, workbook, row, column } = params console.log('Drag over cell:', worksheet.getRange(row, column).getA1Notation())})Événement Drop
L’événement Drop est déclenché lorsqu’un élément est déposé sur une cellule.
univerAPI.addEvent(univerAPI.Event.Drop, (params) => { const { worksheet, workbook, row, column } = params console.log('Drop target cell:', worksheet.getRange(row, column).getA1Notation())})Événement de clic sur une cellule
L’événement CellClicked est déclenché lors d’un clic sur une cellule.
univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => { const { worksheet, workbook, row, column } = params console.log('Clicked cell:', worksheet.getRange(row, column).getA1Notation())})Événement de rendu d’une cellule
registerCellCustomRender enregistre des moteurs de rendu personnalisés pour les cellules.
Exemple 1 : rendu à position fixe — l’ajout de lignes ne modifie pas la position du rendu
// Fixed position renderinguniverAPI.registerCellCustomRender([ { drawWith: (ctx, info, skeleton, spreadsheets) => { const { row, col } = info // Render a checkmark at position (1,1) if (row === 1 && col === 1) { const { primaryWithCoord } = info const { startX, startY } = primaryWithCoord ctx.fillText('✅', startX, startY + 10) } }, },])// Refresh canvas to apply renderinguniverAPI.getActiveWorkbook().getActiveSheet().refreshCanvas()Exemple 2 : rendu basé sur un marqueur — la position du rendu suit les modifications des lignes et des colonnes
// Set markeruniverAPI .getActiveWorkbook() .getActiveSheet() .getRange('B2') .setValue({ custom: { key: 'needCheck' } })// Render based on markeruniverAPI.registerCellCustomRender([ { drawWith: (ctx, info, skeleton, spreadsheets) => { const { row, col, data } = info // Render checkmark at marked position if (data?.custom?.key === 'needCheck') { const { primaryWithCoord } = info const { startX, startY } = primaryWithCoord ctx.fillText('✅', startX, startY + 10) } }, },])// Refresh canvas to apply renderinguniverAPI.getActiveWorkbook().getActiveSheet().refreshCanvas()Événements de modification des cellules
Commencer la modification
const fWorkbook = univerAPI.getActiveWorkbook()fWorkbook.startEditing()Terminer la modification
// Pass true to commit changes, false to cancel editing// This is an async function, requires awaitconst fWorkbook = univerAPI.getActiveWorkbook()await fWorkbook.endEditingAsync(true)Événements de début de modification
L’événement BeforeSheetEditStart est déclenché avant le début de la modification d’une cellule.
univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => { const { worksheet, workbook, row, column, eventType, keycode } = params console.log('Before cell edit:', params) // If you want to prevent entering the editing state params.cancel = true})L’événement SheetEditStarted est déclenché au début de la modification d’une cellule.
const disposable = univerAPI.addEvent(univerAPI.Event.SheetEditStarted, (params) => { const { worksheet, workbook, row, column, eventType, keycode } = params console.log(params)})// Remove the event listener, use `disposable.dispose()`Événements de fin de modification
L’événement BeforeSheetEditEnd est déclenché avant la fin de la modification d’une cellule.
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetEditEnd, (params) => { const { worksheet, workbook, row, column, value, eventType, keycode, isConfirm } = params console.log(params) // Cancel the cell edit end operation params.cancel = true})// Remove the event listener, use `disposable.dispose()`L’événement SheetEditEnded est déclenché après la fin de la modification d’une cellule.
univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => { const { worksheet, workbook, row, column, eventType, keycode, isConfirm } = params console.log('After cell edit:', params)})Événements du presse-papiers
BeforeClipboardChange
L’événement BeforeClipboardChange est déclenché avant la modification du contenu du presse-papiers. Vous pouvez l’utiliser pour surveiller ou modifier ce contenu avant son changement.
univerAPI.addEvent(univerAPI.Event.BeforeClipboardChange, (params) => { const { text, html } = params console.log('Clipboard content:', text, html) // If you want to cancel the clipboard change // params.cancel = true;})BeforeClipboardPaste
L’événement BeforeClipboardPaste est déclenché avant le collage d’un contenu. Vous pouvez l’utiliser pour surveiller ou modifier ce contenu avant son collage.
univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (params) => { const { text, html } = params console.log('Content to paste:', text, html) // If you want to cancel the paste operation // params.cancel = true;})ClipboardChanged
L’événement ClipboardChanged est déclenché après la modification du contenu du presse-papiers.
univerAPI.addEvent(univerAPI.Event.ClipboardChanged, (params) => { const { text, html } = params console.log('New clipboard content:', text, html)})ClipboardPasted
L’événement ClipboardPasted est déclenché après le collage d’un contenu.
univerAPI.addEvent(univerAPI.Event.ClipboardPasted, (params) => { const { text, html } = params console.log('Pasted content:', text, html)})Dépannage de l’édition des cellules
Comment obtenir en temps réel les données de l’éditeur de cellule ?
Abonnez-vous à SheetEditChanging pour lire le texte enrichi pendant l’édition. La valeur reste dans l’éditeur jusqu’à sa validation dans la feuille à la fin de l’édition.
import '@univerjs/sheets-ui/facade'const subscription = univerAPI.addEvent(univerAPI.Event.SheetEditChanging, ({ value }) => { console.log(value.toPlainText())})// Call subscription.dispose() when the owning component or page is removed.Lorsque l’éditeur de cellule a le focus et qu’un bouton externe déclenche un événement, l’instantané obtenu ne contient pas les données de la cellule active.
Les données de la cellule sont synchronisées avec l’instantané lorsque l’éditeur perd le focus, c’est-à-dire à la fin de la modification. Avant de récupérer les données de l’instantané, vérifiez donc que la cellule a perdu le focus. Vous pouvez mettre fin à la modification comme suit :
import '@univerjs/sheets-ui/facade'async function saveWorkbook() { const fWorkbook = univerAPI.getActiveWorkbook() if (!fWorkbook) return await fWorkbook.endEditingAsync(true) const snapshot = fWorkbook.save() console.log(snapshot)}$btn.addEventListener('click', () => { saveWorkbook().catch(console.error)})Référence : https://github.com/dream-num/univer/issues/1314
Après la création d’un classeur avec l’API Facade, certaines API peuvent ne pas fonctionner immédiatement. Elles nécessitent parfois que le rendu de l’interface soit terminé. Il est donc recommandé d’effectuer les opérations concernées à l’étape Rendered ou Steady du cycle de vie.
De nombreuses API nécessitent que le rendu de l’interface soit terminé pour fonctionner correctement. Si vous les appelez juste après la création d’un classeur, elles risquent de ne pas fonctionner, car le rendu n’est pas encore achevé. Il est recommandé d’effectuer les opérations concernées à l’étape Rendered ou Steady du cycle de vie :
const disposable = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => { if (stage === univerAPI.Enum.LifecycleStages.Steady) { // code... }})// To remove the event listener, you can call `disposable.dispose()`Référence : Cycle de vie
Que pensez-vous de ce guide ?