Control de permisos

Univer proporciona capacidades de control de permisos para restringir las operaciones del usuario en libros, hojas de trabajo y rangos. Cuando un usuario intenta una operación sin el permiso requerido, la ejecución se detiene y se notifica al usuario. Por ejemplo, puede proteger un rango para controlar si los colaboradores pueden editar, ver, copiar o filtrar dentro de ese rango.

Vaya a la sección correspondiente a su tarea. Las operaciones básicas, los ejemplos avanzados, la configuración y la solución de problemas se mantienen en esta página; los contratos API completos se mantienen en Reference.

• Tareas habituales
• Configuración de la interfaz de permisos
• Integración del servicio de autorización
• Reference

Conceptos principales

• Alcance: los permisos se aplican en tres niveles: libro de trabajo, hoja de trabajo y rango.
• Puntos de permiso: cada característica corresponde a un punto de permiso. La modificación de un punto controla si esa función está disponible.
• Reglas de protección: antes de configurar puntos de permiso para hojas de trabajo y rangos, debe crear una regla de protección.

Ejemplo básico

Antes de usar los ejemplos de allowedUsers, sustituya user1 y user2 por ID reales de colaboradores devueltos por su servicio de autorización.

Los métodos de configuración de permisos más comunes se muestran a continuación en tres niveles: libro de trabajo, hoja de trabajo y rango.

Ejemplo de código de permisos de libro de trabajo

Los permisos a nivel de libro de trabajo se pueden configurar directamente a través de API de Facade.

El siguiente ejemplo deshabilita la edición para todo el libro de trabajo. Para otras funciones, reemplace el punto de permiso en consecuencia (consulte Lista de puntos de permiso del libro de trabajo):

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)

Puntos clave:

• Los puntos de permiso del libro de trabajo se pueden configurar directamente sin crear reglas de protección.

Ejemplo de código de permisos de hoja de trabajo

Los permisos de la hoja de trabajo y el rango se pueden configurar a través de la API o comandos de Facade. El siguiente ejemplo demuestra cómo configurar permisos de edición de hojas de trabajo. Para otras funciones, reemplace el punto de permiso en consecuencia (consulte lista de puntos de permiso de la hoja de trabajo):

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)

Eliminar permisos de hoja de trabajo

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()

Ejemplo de código de permisos de rango personalizado

Los permisos de rango también se pueden configurar mediante API y modos de comando. Aquí usaremos los permisos de edición de rango como ejemplo. Otras funciones de rango requieren reemplazar los puntos de permiso; consulte lista de puntos de permiso - Rango para obtener más detalles.

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)

Eliminar permisos de protección de rango

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()}

Tareas habituales

Poner un libro en modo de solo lectura

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

Gestionar rangos protegidos

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')])}

Diagnosticar permisos de una celda

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

Lista de puntos de permiso

Puede ver el código fuente de todos los puntos de permiso aquí.

Cuando los permisos del libro se superponen con los permisos de la hoja de cálculo o del rango, todos los permisos relevantes deben establecerse en true para que la función sea utilizable.

Permisos del libro de trabajo

Permisos de la hoja de trabajo

Protección de rango

Configuración de la interfaz de permisos

Estrategia de sombra de rango protegido

Para distinguir las áreas protegidas que el usuario actual puede editar de aquellas que no puede editar, usa non-editable. Las áreas protegidas editables no muestran sombra; las que tienen desactivado el permiso de edición la conservan. Los rangos protegidos que no se pueden ver siguen enmascarados.

Esta opción controla la visualización de la protección de rangos y hojas. No crea reglas de protección, no cambia los permisos de edición o visualización ni añade sombras a áreas sin protección. Primero configura las reglas y los permisos del usuario actual como se indica arriba.

Define la estrategia durante la inicialización:

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

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

También puedes modificarlo dinámicamente a través de la API:

La API Facade que aparece a continuación actualiza los libros existentes en la instancia actual de Univer. En modo plugin, importa primero @univerjs/sheets-ui/facade; el preset Sheets Core ya incluye esta importación.

// 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()

Componente de usuario personalizado

El selector de usuario integrado de Univer tiene una flexibilidad limitada. Para escenarios más complejos, puede proporcionar un componente personalizado como se muestra a continuación.

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',        },      },    }),  ],})

Llame a setSelectUserList() desde el manejador de cambios del selector. Este ejemplo mínimo de React borra la selección: useDependency se ejecuta dentro del componente y el servicio se actualiza solo al pulsar el botón. Complete el selector según 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}>Borrar usuarios seleccionados</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}>Borrar usuarios seleccionados</button>}

Ocultar el cuadro de diálogo de permiso

univerAPI.setPermissionDialogVisible(false)

Integración del servicio de autorización

Uso extendido

Cuando necesite verificar los permisos en su propio complemento, puede manipular los puntos de permiso directamente.

El siguiente ejemplo utiliza WorkbookEditablePermission para demostrar cómo verificar los permisos en su propio complemento. Otros puntos de permiso funcionan de manera similar.

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)  }}

Lista de puntos de permiso

Cómo extender los puntos de permiso

Para personalizar los puntos de permiso, implemente IPermissionPoint y regístrelo con el servicio de permisos:

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$)  }}

Integración de un servicio de autorización de terceros (avanzado)

Implemente IAuthzIoService en su aplicación y conecte sus métodos de permisos, roles y colaboradores al backend. El ejemplo supone que ./authorization-service exporta esta implementación como YourAuthzService. Regístrela antes de crear libros y conserve las demás opciones y complementos.

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

El servicio debe persistir las reglas y los cambios de colaboradores, devolver los permisos del usuario actual y propagar los fallos de las solicitudes. Las listas vacías simuladas no implementan persistencia. En colaboración, el backend debe comprobar por separado lectura, JOIN y modificación; consulte Identidad y autorización. La protección de la interfaz y ocultar sombras no sustituyen la autorización del servidor.

Administración de colaboradores

• Obtener lista de colaboradores

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

• Agregar colaboradores

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,)

• Actualizar función de colaborador

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,)

• Eliminar colaboradores

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