Contrôle des autorisations

Univer propose un système de contrôle des autorisations qui permet de limiter les opérations des utilisateurs sur les classeurs, les feuilles de calcul et les plages. Lorsqu’un utilisateur tente une opération sans disposer de l’autorisation requise, son exécution est interrompue et l’utilisateur en est informé. Vous pouvez, par exemple, protéger une plage afin de déterminer si les collaborateurs peuvent la modifier, l’afficher, la copier ou la filtrer.

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.

• Tâches courantes
• Configuration de l’interface des permissions
• Intégration du service d’autorisation
• Reference

Concepts fondamentaux

• Portée : les autorisations s’appliquent à trois niveaux : classeur, feuille de calcul et plage.
• Points d’autorisation : chaque fonctionnalité correspond à un point d’autorisation. La modification d’un point détermine si la fonctionnalité est disponible.
• Règles de protection : avant de définir les points d’autorisation d’une feuille de calcul ou d’une plage, vous devez créer une règle de protection.

Exemple de base

Avant d’utiliser les exemples allowedUsers, remplacez user1 et user2 par les identifiants réels de collaborateurs retournés par votre service d’autorisation.

Les méthodes les plus courantes de configuration des autorisations sont présentées ci-dessous pour les trois niveaux : classeur, feuille de calcul et plage.

Exemple de code pour les autorisations d’un classeur

Les autorisations au niveau du classeur peuvent être définies directement avec l’Facade API.

L’exemple suivant désactive la modification de l’ensemble du classeur. Pour les autres fonctionnalités, remplacez le point d’autorisation en conséquence (consultez la liste des points d’autorisation du classeur) :

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const workbookPermission = fWorkbook.getWorkbookPermission()// Set the workbook to be non-editableawait workbookPermission.setPoint(univerAPI.Enum.WorkbookPermissionPoint.Edit, false)

À retenir :

• Les points d’autorisation d’un classeur peuvent être définis directement, sans créer de règle de protection.

Exemple de code pour les autorisations d’une feuille de calcul

Les autorisations des feuilles de calcul et des plages peuvent être définies avec l’API Facade ou avec des commandes. L’exemple suivant montre comment configurer l’autorisation de modification d’une feuille de calcul. Pour les autres fonctionnalités, remplacez le point d’autorisation en conséquence (consultez la liste des points d’autorisation des feuilles de calcul) :

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const worksheetPermission = fWorksheet.getWorksheetPermission()// Create worksheet protection, allow specified users to editconst permissionId = await worksheetPermission.protect({  allowedUsers: ['user1', 'user2'],  name: 'My Worksheet Protection',})// To set permission points, you must first protect the worksheetawait worksheetPermission.setPoint(univerAPI.Enum.WorksheetPermissionPoint.Edit, false)

Supprimer les autorisations d’une feuille de calcul

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const worksheetPermission = fWorksheet.getWorksheetPermission()// Remove worksheet protectionawait worksheetPermission.unprotect()

Exemple de code pour les autorisations d’une plage personnalisée

Les autorisations d’une plage peuvent également être définies par l’API ou par des commandes. Nous prendrons ici l’autorisation de modification d’une plage comme exemple. Pour les autres fonctionnalités, remplacez les points d’autorisation ; consultez la liste des points d’autorisation des plages pour en savoir plus.

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')const rangePermission = fRange.getRangePermission()// Set range protection permission, allow specified users to edit but not allow others to viewconst rule = await rangePermission.protect({  name: 'My protected range',  allowViewByOthers: false,  allowedUsers: ['user1', 'user2'],})console.log(rule)// To set permission points, you must first create a range protection rule.await rule.setPoint(univerAPI.Enum.RangePermissionPoint.Edit, false)await rule.setPoint(univerAPI.Enum.RangePermissionPoint.View, true)

Supprimer les autorisations de protection d’une plage

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')const rangePermission = fRange.getRangePermission()// delete all rules within the rangeawait rangePermission.unprotect()// Or delete specific rules within the rangeconst rules = await rangePermission.listRules()if (rules.length > 0) {  await rules[0].remove()}

Tâches courantes

Passer un classeur en lecture seule

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const permission = fWorkbook.getWorkbookPermission()await permission.setMode('viewer')console.log(permission.getSnapshot())

Gérer les plages protégées

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const permission = fWorksheet.getWorksheetPermission()const createdRules = await permission.protectRanges([  {    ranges: [fWorksheet.getRange('A1:B2')],    options: { name: 'Public area', allowViewByOthers: true },  },  {    ranges: [fWorksheet.getRange('C3:D4')],    options: { name: 'Private area', allowViewByOthers: false, allowedUsers: ['user1'] },  },])console.log(createdRules)const rules = await permission.listRangeProtectionRules()const firstRule = rules[0]if (firstRule) {  await firstRule.updateRanges([fWorksheet.getRange('A1:B3')])}

Diagnostiquer les permissions d’une cellule

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const permission = fWorkbook.getActiveSheet().getWorksheetPermission()console.log(permission.debugCellPermission(0, 0))

Liste des points d’autorisation

Vous pouvez consulter ici le code source de tous les points d’autorisation.

Lorsque les autorisations du classeur se superposent à celles d’une feuille de calcul ou d’une plage, toutes les autorisations concernées doivent être définies sur true pour que la fonctionnalité soit utilisable.

Autorisations du classeur

Autorisations de la feuille de calcul

Protection des plages

Configuration de l’interface des permissions

Stratégie d’ombrage des plages protégées

Pour distinguer les zones protégées que l’utilisateur actuel peut modifier de celles qu’il ne peut pas modifier, utilisez non-editable. L’ombrage disparaît des zones protégées modifiables et reste visible lorsque le droit de modification est désactivé. Les plages protégées non consultables restent masquées.

Ce réglage contrôle l’affichage de la protection des plages et des feuilles. Il ne crée pas de règles de protection, ne modifie pas les droits de modification ou de consultation et n’ajoute pas d’ombrage aux zones non protégées. Configurez d’abord les règles et les droits de l’utilisateur actuel comme indiqué ci-dessus.

Définissez la stratégie à l’initialisation :

univer.registerPlugin(UniverSheetsUIPlugin, {  protectedRangeShadow: 'non-editable',})

createUniver({  presets: [    UniverSheetsCorePreset({      sheets: {        protectedRangeShadow: 'non-editable',      },    }),  ],})

Vous pouvez également le modifier dynamiquement avec l’API :

L’API Facade ci-dessous met à jour les classeurs existants dans l’instance Univer actuelle. En mode plugin, importez d’abord @univerjs/sheets-ui/facade ; le preset Sheets Core inclut déjà cet import.

// Set to only show shadows for non-editable rangesuniverAPI.setProtectedRangeShadowStrategy('non-editable')// Get the current protected range shadow display strategyconsole.log(univerAPI.getProtectedRangeShadowStrategy())// Subscribe to changes in the protected range shadow strategyconst subscription = univerAPI.getProtectedRangeShadowStrategy$().subscribe((strategy) => {  console.log('Global strategy changed to:', strategy)  // Update UI or perform other actions})// Later, unsubscribe to clean upsubscription.unsubscribe()

Composant utilisateur personnalisé

Le sélecteur d’utilisateurs intégré à Univer offre une souplesse limitée. Pour les cas plus complexes, vous pouvez fournir un composant personnalisé comme ci-dessous.

univer.registerPlugin(UniverSheetsUIPlugin, {  protectedRangeUserSelector: {    /**     * Custom component; must implement the `IPermissionDetailUserPartProps` interface.     */    component: CustomPermissionDetailUserPart,    /**     * The framework of the component. Must be passed correctly.     */    framework: 'react',  },})

const { univer } = createUniver({  presets: [    UniverSheetsCorePreset({      sheets: {        protectedRangeUserSelector: {        /**         * Custom component; must implement the `IPermissionDetailUserPartProps` interface.         */          component: CustomPermissionDetailUserPart,          /**           * The framework of the component. Must be passed correctly.           */          framework: 'react',        },      },    }),  ],})

Appelez setSelectUserList() dans le gestionnaire de changement du sélecteur. Cet exemple React minimal efface la sélection : useDependency s’exécute dans le composant et le service ne change qu’au clic. Complétez le sélecteur selon IPermissionDetailUserPartProps.

import type { IPermissionDetailUserPartProps } from '@univerjs/sheets-ui'import type { FC } from 'react'import { SheetPermissionUserManagerService } from '@univerjs/sheets-ui'import { useDependency } from '@univerjs/ui'export const CustomPermissionDetailUserPart: FC<IPermissionDetailUserPartProps> = () => {  const service = useDependency(SheetPermissionUserManagerService)  const clearSelection = () => service.setSelectUserList([])  return <button type="button" onClick={clearSelection}>Effacer les utilisateurs sélectionnés</button>}

import type { IPermissionDetailUserPartProps } from '@univerjs/preset-sheets-core'import type { FC } from 'react'import { SheetPermissionUserManagerService, useDependency } from '@univerjs/preset-sheets-core'export const CustomPermissionDetailUserPart: FC<IPermissionDetailUserPartProps> = () => {  const service = useDependency(SheetPermissionUserManagerService)  const clearSelection = () => service.setSelectUserList([])  return <button type="button" onClick={clearSelection}>Effacer les utilisateurs sélectionnés</button>}

Masquer la boîte de dialogue des autorisations

univerAPI.setPermissionDialogVisible(false)

Intégration du service d’autorisation

Utilisation avancée

Pour vérifier les autorisations dans votre propre plugin, vous pouvez manipuler directement les points d’autorisation.

L’exemple suivant utilise WorkbookEditablePermission pour montrer comment vérifier les autorisations dans votre propre plugin. Les autres points d’autorisation fonctionnent de la même façon.

import { IPermissionService } from '@univerjs/core'import { WorkbookEditablePermission } from '@univerjs/sheets'class YourService {  constructor(@IPermissionService private _permissionService: IPermissionService) {  }  setWorkbookNotEditable() {    this._permissionService.updatePermissionPoint(new WorkbookEditablePermission('unitId').id, false)  }  setWorkbookEditable() {    this._permissionService.updatePermissionPoint(new WorkbookEditablePermission('unitId').id, true)  }}

Liste des points d’autorisation

Étendre les points d’autorisation

Pour personnaliser les points d’autorisation, implémentez IPermissionPoint, puis enregistrez-le auprès du service d’autorisation :

import type { IPermissionPoint } from '@univerjs/core'import { IPermissionService, PermissionStatus } from '@univerjs/core'import { UnitAction, UnitObject } from '@univerjs/protocol'export class CustomPermissionPoint implements IPermissionPoint {  type = UnitObject.Unkonwn // your type  subType = UnitAction.View // your subType  status = PermissionStatus.INIT  value = true // Default value  id: string  constructor(unitId: string, subUnitId: string, customId: string) {    // The id must be unique within `IPermissionService`.    this.id = `${unitId}.${subUnitId}.${customId}`  }}class YourService {  constructor(@IPermissionService private _permissionService: IPermissionService) {    this._init()  }  _init() {    this._permissionService.addPermissionPoint(new CustomPermissionPoint('unitId', 'subUnitId', 'my-id'))  }}// How to use it elsewhereclass ConsumeService {  constructor(@IPermissionService private _permissionService: IPermissionService) {  }  doSomething() {    const point = this._permissionService.getPermissionPoint(new CustomPermissionPoint('unitId', 'subUnitId', 'my-id').id)    console.log(point?.value)  }  bindEvent() {    // This returns an RxJS observable that lets you listen for permission changes    const point$ = this._permissionService.getPermissionPoint$(new CustomPermissionPoint('unitId', 'subUnitId', 'my-id').id)    console.log(point$)  }}

Intégrer un service d’autorisation tiers (avancé)

Implémentez IAuthzIoService dans votre application et reliez ses méthodes de permissions, rôles et collaborateurs au backend. Cet exemple suppose que ./authorization-service exporte cette implémentation sous le nom YourAuthzService. Enregistrez-la avant de créer les classeurs, en conservant les autres options et plugins.

import { IAuthzIoService, Univer } from '@univerjs/core'import { YourAuthzService } from './authorization-service'const univer = new Univer({  override: [[IAuthzIoService, { useClass: YourAuthzService }]],})

Le service doit persister les règles et les changements de collaborateurs, retourner les droits de l’utilisateur actuel et propager les échecs de requête. Des listes vides simulées ne constituent pas une persistance. En collaboration, le backend doit vérifier séparément les droits de lecture, JOIN et modification ; voir Identité et autorisation. La protection de l’interface et le masquage des ombres ne remplacent pas l’autorisation serveur.

Gestion des collaborateurs

• Obtenir la liste des collaborateurs

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const workbookPermission = fWorkbook.getWorkbookPermission()const collaborators = await workbookPermission.listCollaborators()console.log(collaborators)

• Ajouter des collaborateurs

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const workbookPermission = fWorkbook.getWorkbookPermission()// Add multiple collaborators at onceawait workbookPermission.setCollaborators([  {    user: { userID: 'user1', name: 'John Doe', avatar: 'https://...' },    role: univerAPI.Enum.UnitRole.Editor,  },  {    user: { userID: 'user2', name: 'Jane Smith', avatar: '' },    role: univerAPI.Enum.UnitRole.Reader,  },])// Add a single collaboratorawait workbookPermission.addCollaborator(  { userID: 'user1', name: 'John Doe', avatar: 'https://...' },  univerAPI.Enum.UnitRole.Editor,)

• Modifier le rôle d’un collaborateur

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const workbookPermission = fWorkbook.getWorkbookPermission()await workbookPermission.updateCollaborator(  { userID: 'user1', name: 'John Doe Updated', avatar: 'https://...' },  univerAPI.Enum.UnitRole.Reader,)

• Supprimer des collaborateurs

const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const workbookPermission = fWorkbook.getWorkbookPermission()// Remove multiple collaboratorsawait workbookPermission.removeCollaborators(['user1', 'user2'])// Remove a single collaboratorawait workbookPermission.removeCollaborator('user1')

Reference

• FWorkbookPermission
• FWorksheetPermission
• FRangePermission
• FRangeProtectionRule