使用API自定义kintone空间

betsy_yan发表于:2022年01月11日 18:30:29更新于:2022年03月09日 18:29:19

Index

前言

kintone 的空间画面顶部,可以根据使用目的自由设置。例如,例如在“通知”栏中显示空间说明,或粘贴应用显示记录列表等。
此外,自定义空间的 API 可以像门户自定义一样显示文本和放置按钮。
本文将介绍使用 kintone JavaScript API 的空间 API 进行简单的 kintone 定制。

空间 API 可以执行的操作

通过使用空间 API ,可以自定义设置按钮和动态链接等。

空间系列 API

截至 2021 年 10 月,与空间相关的 JavaScript API 有:

效果图

在空间的上方设置上班和下班打卡按钮。 按下每个按钮可将记录添加到考勤卡应用并更新。

0016202063909f229f96b37fc97ca14

使用JavaScript自定义空间

此 Tips 的自定义将应用于整个 kintone 。
因此,需要 kintone 系统管理员权限。

事前准备

1.在 kintone 首页创建一个空间。

  • 对于要创建的空间,请启用“使用空间门户和多主题”。

  • 记下刚创建好的空间 ID。 用于 JavaScript 自定义。
    关于空间 ID,可以在浏览器的 URL 中找到。
    例如以下 URL,空间 ID 为 8。
    https://{subdomain}.cubozu.cn/k/#/space/8

2.在1.中创建的空间里创建一个考勤卡应用。

  • 请在此处下载考勤卡应用模版。创建时请选择“选择已有模版创建”,然后导入此模版。

  • 记下刚创建的应用 ID。 用于 JavaScript 自定义。
    关于应用 ID,可以在浏览器的 URL 中找到。
    例如以下 URL ,应用 ID 为 245 。
    https://{subdomain}.cybozu.cn/k/245/

自定义范例:在空间上方设置上班/下班打卡按钮

现在,在空间上方设置一个上班/下班打卡按钮,并结合考勤卡应用进行自定义。

将自定义应用到 kintone

需在 kintone 系统管理页面进行空间自定义。
具体设置方法请参考 kintone 帮助“使用JavaScript或CSS自定义”。
设置如下。

0016201e95f67e3d53259729986f2ee

范例代码

注意事项
  • 范例程序不保证其能正常运行

  • 才望子不为范例程序提供技术支持

sample.js
这是一个脚本文件,用于设置上班/下班按钮,并在按下按钮时向考勤卡应用添加/更新记录。
※ 将第 12行的「{YOUR_CUSTOM_SPACE_ID}」改为之前在“事前准备1”中记下的空间 ID 。
※ 将第13行的「{TIMECARD_APP_ID}」改为之前在“事前准备2”中记下的考勤卡应用 ID。

/*
 * sample.js
 * Copyright (c) 2021 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/licenses/mit-license.php
 */

(function() {
  'use strict';
  kintone.events.on('space.portal.show', function(event) {
    var SPACE_ID = '1'; // 请更改为设置按钮的空间 ID
    var TIMECARD_APP_ID = '1'; // 请更改为考勤卡应用的应用 ID
    if (event.spaceId !== SPACE_ID) {
      return event;
    }

    var toastObj = Swal.mixin({
      toast: true,
      position: 'top',
      showConfirmButton: false,
      timer: 3000,
      timerProgressBar: true,
      didOpen: function(toast) {
        toast.addEventListener('mouseenter', Swal.stopTimer);
        toast.addEventListener('mouseleave', Swal.resumeTimer);
      }
    });

    // 获取空间上方的元素
    var el = kintone.space.portal.getContentSpaceElement();

    // 设置上班/下班按钮
    var startButton = new Kuc.Button({
      text: '上班',
      type: 'submit',
      id: 'startButton'
    });

    var endButton = new Kuc.Button({
      text: '下班',
      type: 'alert',
      id: 'endButton'
    });

    // 设置显示日期
    var today = luxon.DateTime.local();
    var todayStr = today.setLocale('zh').toFormat('yyyy 年 M 月 d 日(EEE)');
    var displayDateDiv = document.createElement('div');
    displayDateDiv.id = 'displayDate';
    displayDateDiv.innerText = todayStr;

    // 设置当前日期和上班/下班按钮
    el.appendChild(displayDateDiv);
    el.appendChild(startButton);
    el.appendChild(endButton);

    // 按下上班打卡按钮时的函数
    startButton.addEventListener('click', function() {
      // 获取当前时间
      var currentDate = luxon.DateTime.local();
      var currentTimeStr = currentDate.toFormat('HH:mm');

      // 检查登录用户是否已在当前日期添加过记录
      var query = '创建人 in (" USER", LOGINUSER()) and 创建时间 = TODAY() order by 创建时间 desc limit 1';
      var paramsForGet = {
        app: TIMECARD_APP_ID,
        query: query
      };
      return kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', paramsForGet).then(function(resp) {
        if (resp.records.length !== 0) {
          // 如已存在当前日期的记录,则更新记录的上班时间
          var recordId = resp.records[0].$id.value;
          var paramsForUpdate = {
            app: TIMECARD_APP_ID,
            id: recordId,
            record: {
              '上班时间': {
                value: currentTimeStr
              }
            }
          };
          return kintone.api(kintone.api.url('/k/v1/record.json', true), 'PUT', paramsForUpdate).then(function(resp2) {
            toastObj.fire({
              icon: 'success',
              title: '已更新上班时间!'
            });
          }).catch(function(error) {
            toastObj.fire({
              icon: 'error',
              title: '上班时间更新失败。'
            });
          });
        }
        // 如没有当前日期的记录,则添加记录
        var paramsForAdd = {
          app: TIMECARD_APP_ID,
          record: {
            '上班时间': {
              value: currentTimeStr
            },
            '下班时间': {
              value: ''
            }
          }
        };
        return kintone.api(kintone.api.url('/k/v1/record.json', true), 'POST', paramsForAdd, function(resp3) {
          toastObj.fire({
            icon: 'success',
            title: '已登记上班时间!'
          });
        }, function(error) {
          toastObj.fire({
            icon: 'error',
            title: '上班时间登记失败。'
          });
        });
      });
    });

    // 按下下班按钮时的函数
    endButton.addEventListener('click', function() {
      // 获取当前时间
      var currentDate = luxon.DateTime.local();
      var currentTimeStr = currentDate.toFormat('HH:mm');

      // 获取登录用户添加的记录
      var query = '创建人 in (" USER", LOGINUSER()) and 创建时间 = TODAY() order by 创建时间 desc limit 1';
      var paramsForGet = {
        app: TIMECARD_APP_ID,
        query: query
      };

      return kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', paramsForGet).then(function(resp) {
        if (resp.records.length === 0) {
          // 如没有当前日期的记录,则添加记录
          var paramsForAdd = {
            app: TIMECARD_APP_ID,
            record: {
              '上班时间': {
                value: ''
              },
              '下班时间': {
                value: currentTimeStr
              }
            }
          };

          return kintone.api(kintone.api.url('/k/v1/record.json', true), 'POST', paramsForAdd).then(function(resp2) {
            toastObj.fire({
              icon: 'info',
              title: '已登记下班时间!不要忘记从记录中输入您的工作时间。'
            });
          }).catch(function(error) {
            toastObj.fire({
              icon: 'error',
              title: '下班时间登记失败。'
            });
          });
        }
        var recordId = resp.records[0].$id.value;
        var paramsForUpdate = {
          app: TIMECARD_APP_ID,
          id: recordId,
          record: {
            '下班时间': {
              value: currentTimeStr
            }
          }
        };

        return kintone.api(kintone.api.url('/k/v1/record.json', true), 'PUT', paramsForUpdate).then(function(resp3) {
          toastObj.fire({
            icon: 'success',
            title: '已更新下班时间!'
          });
        }).catch(function(error) {
          toastObj.fire({
            icon: 'error',
            title: '下班时间更新失败。'
          });
        });
      });
    });

    return event;
  });
})();


sample.css
用于调整上班/下班打卡按钮显示位置的 CSS。

/*
 * sample.css
 * Copyright (c) 2021 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/licenses/mit-license.php
 */

#displayDate {
  padding: 10px 20px 0px 30px;
  font-size: 20pt;
  font-weight: 500;
}

#startButton {
  padding: 10px 20px 20px 30px;
}

#endButton {
  padding: 10px 20px 20px 10px;
}


JavaScript 自定义要点

  • 第11〜14行
    执行空间显示事件时,判断按钮是否是要显示的空间 ID 。
    由于空间自定义是应用于整个 kintone,因此使用 if 语句显示或隐藏按钮。

  • 第30〜56行
    获取空间上方的空白元素,并设置今天的日期和上班/下班打卡按钮。
    使用 kintone UI Component v1 把上班/下班打卡按钮设置成 kintone 风格。

  • 第61〜62行
    使用 Luxon 将按下上班打卡按钮的时间格式化为时间字段的格式。

  • 第135〜153行
    如果忘记按上班打卡按钮,则仅登记下班打卡时间。
    用户登记上班时间后会弹出消息。
    按下按钮后使用 SweetAlert2 显示弹出消息。

最后

本文介绍了使用空间 API 设置上下班按钮的自定义。
推荐用于希望按部门或组使用不同空间来管理出勤的场景。
cybozu developer network 还介绍了如何在门户中自定义上下班打卡按钮
那现在就开始利用空间 API 尝试您最喜爱的空间自定义吧。

此Tips在2021年10月版的 kintone 中确认过。


附件:考勤卡.zip • 3.61KB • 下载

    注意:贴代码时请注意格式并使用"代码语言",与本文无关的问题请至“讨论社区”提问。