飞书项目帮助中心

Appearance

Return to top
页面导航

插件开发指南

飞书项目已支持企业自定义插件，开发者可以基于飞书项目现有开放能力来开发插件，如实现 Figma、Gitlab 与飞书项目联动、定时推送延期需求等插件功能。

插件开发流程

在开发插件前，需要前置了解插件的开发流程，帮助你更好地进行插件的工作。

创建插件

内部梳理好插件的开发需求后，可以开始着手创建插件，开始插件前的开发配置工作。

插件入口

可以从以下两处访问飞书项目开发者后台来进行插件的开发工作。

  • 点击个人头像，从「开发者后台」进入插件开发者后台；

  • 管理员从点击导航栏下方的空间配置 → 插件管理，从添加插件的入口进入插件开发者后台。

  • 进入飞书项目·开发者后台，即可开始创建插件。

创建插件

点击「我的插件」模块内的创建插件，即可开始创建插件。

选项解析

  • 插件名称：插件名

  • 插件图标：插件 Logo

  • 仅使用API相关功能：使用本平台相关数据用于第三方平台的集成或开发，在空间内仅涉及到数据交互且无需相关配置，具体可参见：开放能力-OpenAPI接口文档

上传配置后展示如下：

创建后「我的插件」模块内会出现插件列表，展示已经上线与待上线的插件。

如果已经创建过插件，则可以点击导航栏的「我的插件」选项，在「我的插件」左上角进行第二个插件的创建。

插件帮助

对插件有任何疑问，可以点击插件中心下方的「开发者文档」模块。（目前未开放，预计 2 月）

插件配置

点击列表中的插件，即可进入开发者后台。主要有以下几个模块：基本信息、插件功能、权限管理与版本管理。

基本信息

在基本信息页，可以设置插件凭证，查看插件的 Plugin ID 与 Plugin Sercret；设置插件基础信息，配置英文介绍、添加协作人与删除插件。

插件凭证

插件凭证主要是用在开发阶段。

选项解析

  • Plugin ID：插件的唯一 ID；

  • Plugin Sercret：插件唯一的 ID 标识。

插件介绍

在插件介绍配置页设置图标、插件名称、插件的短描述与详情描述（支持富文本）与相关的插件使用帮助文档。帮助文档这里填入飞书文档时，会自动解析标题。

添加英文

如果插件有国际化的需要，可以点击「添加英文」按钮，进行英文基础信息的配置。

预览配置

基本信息配置完成后，点击右上角「预览」预览配置的基础信息。

协作者

如果插件是由团队成员协作开发开发，可选择添加协作者。

注意的是，插件只对应一个负责人，在添加完协作者后，选择升级负责人会将自己的身份转为协作人。

删除插件

如需删除插件，可以点击删除即可。删除的插件如果有被启用的，则需要联系对应的空间管理员先在自己空间删除此插件。

插件功能

插件功能模块中，主要是针对插件展示形态、入口位置进行配置。

添加插件构成

构成即插件所在的位置，如内嵌页面、视图、详情页标签页等等。点击「添加构成」按钮即可开始选择所需的构成。

插件构成与点位配置

点位配置即点位的展示信息配置，例如「内嵌页面 Page」有页面名称、Key、描述和页面图标。

注意：添加构成后需要填配置信息，不然插件无法生效。

插件构成名称
插件位置
点位配置
内嵌页面 Page
单独的导航入口与内嵌页面。
视图 View
可以配置嵌入到工作项视图或者图表视图页面。
详情页 Tab
工作项详情页中的 Tab 页面
控件 Control
可被配置于详情页、节点流转、状态流转表 单、表格页并可用于筛选和分组。
表单项容器 Section
即详情页布局配置的模块，属于控件，包含1-N个字段 / 控件。
按钮 Button
可被配置于详情页工具栏，视图页、视图 具栏、用于操作单个或多个工作项。
集成 Integration
用于承载第三方平台数据打通规则，不存在可视化界面。

删除构成

注意，删除后，已安装该插件的全部用户将无法再使用该插件提供的功能。

权限管理

插件拥有所需的权限后，才能调用接口获取相关信息。为保护用户的信息安全，开放平台或企业管理员审核插件时，需审核插件所需权限。请仅开启实现功能所需的权限否则插件可能无法通过审核。

接口使用须知

你可以通过以下方式，更好地调用插件、申请插件权限：

  • **在开发联调阶段：**你可以按需申请开通插件权限，同时勾选指定空间，使用虚拟token进行接口数据调用。该版本不需要发布插件，即可在本地环境调试真实空间接口数据，这个阶段仅支持获取单个空间数据，空间的筛选范围为插件管理员具备访问权限的空间，协作者不可切换空间

  • **开发完成后：**你需要发布插件并选择插件可见空间范围，上架对应插件。

  • **插件上架后：**空间管理员需安装对应插件，并完成空间数据授权后，你才可以正式获取对应空间的数据。

选择数据范围

仅针对调试阶段的虚拟 token 适用，开通对应接口权限后即生效。可通过虚拟的 plugin_token 在对应接口获取该空间数据。虚拟的 plugin_token 配置请参考：插件身份凭证（plugin_token）

获取权限

点击「获取权限」即可完成权限获取。

如果逐个获取单个权限麻烦，则可以选择批量获取。

筛选搜索

当选项过多时，可以选择状态来进行筛选，比如筛选未获取的权限，也可以通过搜索关键词来查看。

切换插件

当一个人管理多个插件时，可以将鼠标滑动至左上角插件进行切换。

插件开发

了解具体开发请参考以下文档。插件需要先创建代码仓库和插件绑定后，才能作为版本提交审核发布。

开发者请注意

  • 后端服务接口需注意接口安全，纯后端服务，并且有对公网暴露接口，需要保证接口安全，否则有泄漏项目数据风险；

  • 对于有页面集成的插件，后端服务需要接入插件的第三方免登，确保对页面提供的接口需要登陆认证，保证安全。

插件提交

版本管理

如需发布插件，可以在版本管理页面点击右上角的「创建版本」按钮。

在创建版本页面，可以选择版本号、可以安装的空间、产物版本与版本描述。产物版本这里需要代码进行提交后才能显示。

选项解析

  • 版本号：插件的版本号，参考版本：1.0.0；
  • 可用性：是对所有空间生效还是指定的几个空间生效；
  • 版本描述：版本更新、修复和优化了什么内容；
  • 版本产物：技术打包后可选择；
  • 权限变更：展示这次版本更新了多少权限。

插件使用

当插件提交审核通过后，管理员可以在空间配置 → 插件管理中添加对应插件即可。