XLSX

保护

锁定工作表和工作簿、定义保护范围，以及带密码的文件共享

工作表保护

使用密码保护工作表并限制用户操作。提供明文 password 时，会自动计算传统的 XOR 哈希和现代 SHA-512 哈希。

{
  "worksheets": [
    {
      "name": "Protected",
      "rows": [
        { "cells": [{ "value": "Quarter" }, { "value": "2023" }, { "value": "2024" }] },
        { "cells": [{ "value": "Q1" }, { "value": 100 }, { "value": 120 }] },
        { "cells": [{ "value": "Q2" }, { "value": 150 }, { "value": 170 }] }
      ],
      "protection": {
        "sheet": true,
        "password": "secret",
        "formatCells": false,
        "insertRows": false,
        "sort": false
      }
    }
  ]
}

{
  name: "Protected",
  rows: [
    { cells: [{ value: "Quarter" }, { value: "2023" }, { value: "2024" }] },
    { cells: [{ value: "Q1" }, { value: 100 }, { value: 120 }] },
    { cells: [{ value: "Q2" }, { value: 150 }, { value: 170 }] },
  ],
  protection: {
    sheet: true,
    password: "secret",
    formatCells: false,
    insertRows: false,
    sort: false,
  },
}

工作表保护选项

选项	类型	说明
`sheet`	`boolean`	启用工作表保护
`password`	`string`	明文密码（自动计算哈希）
`objects`	`boolean`	保护对象
`scenarios`	`boolean`	保护方案
`formatCells`	`boolean`	允许格式化单元格
`formatColumns`	`boolean`	允许格式化列
`formatRows`	`boolean`	允许格式化行
`insertColumns`	`boolean`	允许插入列
`insertRows`	`boolean`	允许插入行
`insertHyperlinks`	`boolean`	允许插入超链接
`deleteColumns`	`boolean`	允许删除列
`deleteRows`	`boolean`	允许删除行
`selectLockedCells`	`boolean`	允许选取锁定单元格
`sort`	`boolean`	允许排序
`autoFilter`	`boolean`	允许自动筛选
`pivotTables`	`boolean`	允许数据透视表
`selectUnlockedCells`	`boolean`	允许选取未锁定单元格

现代加密

提供 password 时，会自动生成传统 XOR 哈希（用于兼容性）和现代 SHA-512 哈希（使用随机盐值和 100,000 次迭代）。也可以直接提供预计算的值：

{
  "protection": {
    "sheet": true,
    "algorithmName": "SHA-512",
    "hashValue": "base64hash...",
    "saltValue": "base64salt...",
    "spinCount": 100000
  }
}

选项	类型	说明
`algorithmName`	`string`	哈希算法（如 `"SHA-512"`）
`hashValue`	`string`	Base64 编码的密码哈希
`saltValue`	`string`	Base64 编码的盐值
`spinCount`	`number`	哈希迭代次数

保护范围

在受保护的工作表中定义指定用户可编辑的命名区域：

{
  "worksheets": [
    {
      "name": "Protected",
      "rows": [
        { "cells": [{ "value": "Quarter" }, { "value": "2023" }, { "value": "2024" }] },
        { "cells": [{ "value": "Q1" }, { "value": 100 }, { "value": 120 }] },
        { "cells": [{ "value": "Q2" }, { "value": 150 }, { "value": 170 }] }
      ],
      "protection": {
        "sheet": true,
        "password": "secret"
      },
      "protectedRanges": [{ "name": "EditableRange", "sqref": "B2:C5", "password": "range1" }]
    }
  ]
}

{
  name: "Protected",
  rows: [
    { cells: [{ value: "Quarter" }, { value: "2023" }, { value: "2024" }] },
    { cells: [{ value: "Q1" }, { value: 100 }, { value: 120 }] },
    { cells: [{ value: "Q2" }, { value: 150 }, { value: 170 }] },
  ],
  protection: {
    sheet: true,
    password: "secret",
  },
  protectedRanges: [
    { name: "EditableRange", sqref: "B2:C5", password: "range1" },
  ],
}

保护范围选项

选项	类型	说明
`name`	`string`	范围名称（必填）
`sqref`	`string`	单元格范围引用，如 `"B2:C5"`（必填）
`password`	`string`	明文密码（自动计算哈希）
`algorithmName`	`string`	现代加密的哈希算法
`hashValue`	`string`	Base64 编码的密码哈希
`saltValue`	`string`	Base64 编码的盐值
`spinCount`	`number`	哈希迭代次数
`securityDescriptor`	`string`	SID 安全描述符字符串

工作簿保护

在工作簿级别锁定工作簿结构和窗口。支持为结构和修订分别设置密码：

{
  "workbookProtection": {
    "lockStructure": true,
    "lockWindows": true,
    "workbookPassword": "admin"
  },
  "worksheets": [
    {
      "name": "Data",
      "rows": [{ "cells": [{ "value": "Protected workbook" }] }]
    }
  ]
}

import { generateWorkbook } from "@office-open/xlsx";

const buffer = await generateWorkbook({
  workbookProtection: {
    lockStructure: true,
    lockWindows: true,
    workbookPassword: "admin",
  },
  worksheets: [{ name: "Data", rows: [{ cells: [{ value: "Protected workbook" }] }] }],
});

工作簿保护选项

选项	类型	说明
`lockStructure`	`boolean`	锁定工作簿结构（添加/删除/重命名工作表）
`lockWindows`	`boolean`	锁定工作簿窗口
`lockRevision`	`boolean`	锁定修订
`workbookPassword`	`string`	明文结构密码（自动计算哈希）
`revisionsPassword`	`string`	明文修订密码（自动计算哈希）

两个密码还支持现代加密选项：workbookAlgorithmName、workbookHashValue、workbookSaltValue、workbookSpinCount 以及 revisionsAlgorithmName、revisionsHashValue、revisionsSaltValue、revisionsSpinCount。

文件共享

推荐以只读模式打开，并记录文件被谁打开：

{
  "fileSharing": {
    "readOnlyRecommended": true,
    "userName": "John"
  },
  "worksheets": [
    {
      "name": "Data",
      "rows": [{ "cells": [{ "value": "Shared file" }] }]
    }
  ]
}

import { generateWorkbook } from "@office-open/xlsx";

const buffer = await generateWorkbook({
  fileSharing: {
    readOnlyRecommended: true,
    userName: "John",
  },
  worksheets: [{ name: "Data", rows: [{ cells: [{ value: "Shared file" }] }] }],
});

文件共享选项

选项	类型	说明
`readOnlyRecommended`	`boolean`	推荐只读模式
`userName`	`string`	锁定文件的用户名
`reservationPassword`	`string`	明文预留密码（自动计算哈希）
`algorithmName`	`string`	现代加密的哈希算法
`hashValue`	`string`	Base64 编码的密码哈希
`saltValue`	`string`	Base64 编码的盐值
`spinCount`	`number`	哈希迭代次数

编辑此页面或提交问题报告

批注

为单元格添加批注和备注

共享工作簿修订

通过修订日志（revisionHeaders、revisions、users）追踪共享工作簿的更改