开关文档保护

场景说明

文档保护功能可以限制文档的编辑权限,支持多种保护模式,包括表单录入、修订保护、区域编辑和批注模式。

JSSDK 1.12.1 起,文档保护拆分为两套互相独立的体系,均支持密码(密码相关行为由环境变量 LS_WEBRESOURCE_DOCUMENTS_TEXT_PROTECTPASSWORD 控制,true 为强密码模式,false 为兼容模式):

• 内容保护:对应本地 Word/WPS 的「限制编辑」,通过 protect / unprotect 开关,开启时密码可空(空=无密码),关闭时凭密码校验
• 只读保护:开启后所有人只读,通过 setWritePassword 专用开关管理

适用场景:

• 合同文档保护
• 表单模板限制编辑
• 启用文档修订模式
• 协作文档权限控制

相关 API 文档

• Document.protect - 开启文档保护
• Document.unprotect - 关闭文档保护
• Document.setWritePassword - 只读保护专用开关
• Document.unlockEditing - 临时解锁只读保护
• Document.unlockProtection - 临时解锁内容保护
• Document.ProtectionType - 保护类型
• Writer.ProtectionType - 保护类型枚举

示例代码

开启区域编辑保护（完整参数示例）

async function enableEditAreaProtection() {
  // 开启区域编辑保护，全文默认只读
  // 参数：protectionType - 保护类型（必填）, permission - 默认权限（可选，默认为只读）
  const success = await Application.ActiveDocument.protect(
    Writer.ProtectionType.EditArea,
    Writer.DocPermission.ReadOnly  // 明确指定全文默认只读
  );
  
  if (success) {
    console.log('区域编辑保护已开启,全文只读');
    // 此时只有设置了可编辑区域的部分可以编辑
  }
}

开启区域编辑保护(全文可编辑)

async function enableEditAreaProtectionEditable() {
  // 开启区域编辑保护,全文默认可编辑
  const success = await Application.ActiveDocument.protect(
    Writer.ProtectionType.EditArea,
    Writer.DocPermission.Editable
  );
  
  if (success) {
    console.log('区域编辑保护已开启,全文可编辑');
    // 可以通过设置可编辑区域来限制特定用户的编辑权限
  }
}

开启修订保护

async function enableRevisionProtection() {
  // 开启修订保护,所有编辑都会记录修订
  const success = await Application.ActiveDocument.protect(
    Writer.ProtectionType.Revision
  );
  
  if (success) {
    console.log('修订保护已开启,所有修改都会被追踪');
  }
}

同时开启区域编辑和修订保护

async function enableMultipleProtections() {
  // 使用 | 操作符同时开启多种保护
  // 注意:修订保护可以和其他保护类型同时设置
  const success = await Application.ActiveDocument.protect(
    Writer.ProtectionType.EditArea | Writer.ProtectionType.Revision,
    Writer.DocPermission.ReadOnly
  );
  
  if (success) {
    console.log('已开启区域编辑保护和修订保护');
  }
}

开启带密码的内容保护(JSSDK: 1.12.1 支持)

async function enableProtectionWithPassword() {
  // LS_WEBRESOURCE_DOCUMENTS_TEXT_PROTECTPASSWORD为false
  // 开启区域编辑保护并设置保护密码,停止保护时需输入该密码
  // 密码可不传(不传 = 无密码保护)
  const success = await Application.ActiveDocument.protect(
    Writer.ProtectionType.EditArea,
    Writer.DocPermission.ReadOnly,
    '123456'
  );

  if (success) {
    console.log('区域编辑保护已开启,密码已设置');
  }
}

async function enableProtectionWithNounce() {
  // LS_WEBRESOURCE_DOCUMENTS_TEXT_PROTECTPASSWORD为true
  // 开启区域编辑保护,匹配nounce,停止保护时也使用该nounce校验
  const success = await Application.ActiveDocument.protect(
    Writer.ProtectionType.EditArea,
    Writer.DocPermission.ReadOnly,
    undefined,
    { nounce: '123' }
  );

  if (success) {
    console.log('区域编辑保护已开启');
  }
}

开启/关闭只读保护(JSSDK: 1.12.1 支持)

async function enableReadonlyProtection() {
  // 开启只读保护并设置编辑授权密码,开启后所有人只读
  const success = await Application.ActiveDocument.setWritePassword('123456');

  if (success) {
    console.log('只读保护已开启');
  }
}

async function disableReadonlyProtection() {
  // 空字符串 = 关闭只读保护(内容保护不受影响)
  const success = await Application.ActiveDocument.setWritePassword('');

  if (success) {
    console.log('只读保护已关闭');
  }
}

临时解锁(JSSDK: 1.12.1 支持)

async function unlock() {
  // 临时解锁只读保护,仅本端本会话有效,刷新后恢复锁定,不关闭保护
  const unlocked = await Application.ActiveDocument.unlockEditing('123456');

  // 临时解锁内容保护(解除编辑类型限制),同样为本端会话级
  // const unlocked = await Application.ActiveDocument.unlockProtection('123456');

  if (unlocked) {
    console.log('解锁成功,现在可以编辑文档');
  }
}

关闭文档保护

async function disableProtection() {
  // 关闭内容保护(只读保护不受影响)
  // 内容保护设置了密码时需传入密码,否则返回 false
  const success = await Application.ActiveDocument.unprotect();
  
  if (success) {
    console.log('文档保护已关闭');
  }
}

检查文档保护状态

async function checkProtectionStatus() {
  // 获取文档保护类型
  const protectionType = await Application.ActiveDocument.ProtectionType;
  
  console.log('当前保护类型:', protectionType);
  
  // 判断具体的保护类型
  const types = Writer.ProtectionType;
  
  if (protectionType === types.NoProtection) {
    console.log('文档未设置保护');
  } else if (protectionType === types.EditArea) {
    console.log('已开启区域编辑保护');
  }
  
  if (protectionType === types.Revision) {
    console.log('已开启修订保护');
  }
  
  if (protectionType === types.FormEntry) {
    console.log('已开启表单录入保护');
  }
  
  if (protectionType === types.Comments) {
    console.log('已开启批注模式');
  }
}

检查区域编辑的默认权限

async function checkDocPermission() {
  // 获取区域编辑保护时的默认权限
  const permission = await Application.ActiveDocument.PermissionType;
  
  if (permission === Writer.DocPermission.ReadOnly) {
    console.log('全文默认只读');
  } else if (permission === Writer.DocPermission.Editable) {
    console.log('全文默认可编辑');
  } else if (permission === Writer.DocPermission.None) {
    console.log('文档未开启区域编辑保护');
  }
}

检查内容保护是否开启

async function checkDataProtection() {
  // 检查内容保护(数据保护)是否开启
  const isProtected = await Application.ActiveDocument.isDataProtectionOn();
  
  if (isProtected) {
    console.log('内容保护已开启');
  } else {
    console.log('内容保护未开启');
  }
}

完整的保护切换流程

async function toggleDocumentProtection() {
  // 检查当前保护状态
  const currentType = await Application.ActiveDocument.ProtectionType;
  
  if (currentType === Writer.ProtectionType.NoProtection) {
    // 如果未保护,则开启保护
    await Application.ActiveDocument.protect(
      Writer.ProtectionType.EditArea,
      Writer.DocPermission.ReadOnly
    );
    console.log('文档保护已开启');
  } else {
    // 如果已保护,则关闭保护
    await Application.ActiveDocument.unprotect();
    console.log('文档保护已关闭');
  }
}

注意事项

• 只有修订保护类型可以和其他保护类型同时设置，其他保护类型只能单独设置
• 使用 | 运算符组合保护类型
• 区域编辑保护需要配合需配合编辑区域使用
• DocPermission 只在区域编辑保护时有效
• 保护状态可以通过 ProtectionType 属性查询
• isDataProtectionOn() 检查内容保护是否开启
• protect / unprotect 仅用于内容保护；只读保护的开启/关闭/换密码统一走 setWritePassword
• 两套体系（只读保护、内容保护）互相独立，可同时开启、分别关闭，各自独立设密码
• unlockEditing / unlockProtection 为临时解锁：仅本端本会话有效，刷新后恢复锁定，不会关闭保护；环境变量LS_WEBRESOURCE_DOCUMENTS_TEXT_PROTECTPASSWORD为false时不可用（返回 false）
• 集成方配置了 nounce 的文档，上述保护相关 API 的 options 未带 nounce 或不匹配时均返回 false 且不执行，此时保护密码不作为替代凭据（仅环境变量LS_WEBRESOURCE_DOCUMENTS_TEXT_PROTECTPASSWORD为true时生效）
• 所有保护相关 API 成功返回 true / 失败返回 false