Google Apps Script 用CardService.newDatePicker跟踪选中日期的方法

问题场景 #

开发Google Calendar平台卡片式插件时，通过CardService.newDatePicker组件实现日期选择功能，日期选择器初始化代码如下：

const DatePickerFrom = CardService.newDatePicker()
    .setTitle("From Day")
    .setFieldName("range_start")
    .setValueInMsSinceEpoch(todayDate.getTime())
    .setOnChangeAction(
      CardService
        .newAction()
        .setFunctionName("handleRangeStartChange")
    );

需求为持久化保存用户选中的日期值，供后续业务逻辑调用，初始实现方案使用ScriptProperties存储配置，相关代码如下：

const scriptProperties = PropertiesService.getScriptProperties();

scriptProperties.setProperties({
  "rangeStart": new Date(),
  "rangeEnd": new Date(),
  "dayStartHour": 9,
  "dayStartMinutes": 0,
  "dayEndHour": 17,
  "dayEndMinutes": 0,
  "busyBlocks": []
});

function handleRangeStartChange(e) {
  const rangeStart = formatDate(new Date(e.formInput.range_start.msSinceEpoch));
  scriptProperties.setProperty("rangeStart", rangeStart);
}

后续读取scriptProperties存储值时发现，用户选择后更新的日期值并未成功写入，日志打印结果始终为setProperties设置的默认值，日志读取代码如下：

function logParams() {
  const params = scriptProperties.getProperties();
  Logger.log(params)
}

需要明确该类插件正确跟踪、存储用户选中配置值的实现方式。

问题根因 #

代码存在两个核心问题，直接导致配置更新失效：

• 全局作用域的默认值写入逻辑会强制覆盖配置：Apps Script的执行模型是每次触发任意函数执行（包括日期组件的onChange回调、手动触发的日志打印函数），都会先完整运行所有全局作用域的代码。你把批量写入默认值的setProperties逻辑写在全局，等于每次执行操作前都会把存储值重置为初始默认值，回调里写入的新值会在下次脚本执行时被直接覆盖。
• 存储类型选型错误：ScriptProperties是脚本级全局共享存储，所有使用该插件的用户都会读写同一份数据，天然不适合存储用户个人配置。另外Properties服务仅支持字符串类型存储，直接传入Date对象、数组类型值时会被强制转换为格式异常的字符串，后续读取无法正常解析使用。

正确实现方案 #

按以下三点调整即可实现稳定的用户配置持久化：

• 替换存储为用户级隔离存储：使用PropertiesService.getUserProperties()存储用户个人配置，该存储按Google账号隔离，同一用户的配置支持跨设备同步，不同用户之间数据完全独立，不会出现互相覆盖的问题。
• 移除全局作用域的写操作，仅在配置缺失时初始化默认值：把默认值写入逻辑从全局作用域移到专门的初始化函数中，仅当检测到用户配置不存在时才写入默认值，从根源避免每次脚本执行重置配置的问题。
• 对非字符串值做序列化处理：存储数字、日期、数组、对象类型的配置值时，统一转换为字符串格式写入，读取时再反序列化为原始类型，避免格式异常。

修正后的参考代码：

// 全局仅声明存储实例，不执行任何写入操作
const userProperties = PropertiesService.getUserProperties();

/**
 * 初始化用户默认配置，仅在首次使用/配置缺失时执行
 */
function initDefaultUserConfig() {
  const existingConfig = userProperties.getProperties();
  // 检测配置是否已初始化，避免覆盖用户已保存的设置
  if (!Object.prototype.hasOwnProperty.call(existingConfig, 'rangeStart')) {
    const defaultConfig = {
      "rangeStart": String(new Date().getTime()), // 日期存时间戳，转字符串写入
      "rangeEnd": String(new Date().getTime()),
      "dayStartHour": "9",
      "dayStartMinutes": "0",
      "dayEndHour": "17",
      "dayEndMinutes": "0",
      "busyBlocks": JSON.stringify([]) // 数组/对象转JSON字符串写入
    };
    userProperties.setProperties(defaultConfig);
  }
}

/**
 * 日期选择变更回调
 */
function handleRangeStartChange(e) {
  initDefaultUserConfig();
  // 获取用户选中日期的毫秒时间戳
  const selectedTimestamp = e.formInput.range_start.msSinceEpoch;
  // 写入新的日期值
  userProperties.setProperty("rangeStart", String(selectedTimestamp));
  
  // 注意：卡片交互回调必须返回合法的ActionResponse，否则可能出现执行中断
  return CardService.newActionResponseBuilder()
    .setNavigation(CardService.newNavigation().updateCard(buildMainCard()))
    .build();
}

/**
 * 打印已存储的配置
 */
function logParams() {
  initDefaultUserConfig();
  const params = userProperties.getProperties();
  // 读取后反序列化为对应类型
  params.rangeStart = new Date(Number(params.rangeStart));
  params.rangeEnd = new Date(Number(params.rangeEnd));
  params.busyBlocks = JSON.parse(params.busyBlocks);
  Logger.log(params);
}

/**
 * 构建插件主卡片（替换为你自己的卡片构建逻辑）
 */
function buildMainCard() {
  // 此处放置你的卡片构建代码
  return CardService.newCardBuilder().build();
}

额外注意事项 #

• 所有卡片交互回调函数执行完成后，必须返回符合规范的ActionResponse对象，否则可能出现回调执行中途中断、写操作不落地的问题。
• 全局作用域仅适合声明常量、实例化无副作用的通用对象，不要在全局写任何存储写入、外部API调用这类带副作用的逻辑，避免出现预期外的执行结果。

内容的提问来源于stack exchange，提问作者GN.