Notion 插件开发入门

Notion 插件开发入门

最近想要用 Notion 记笔记，奈何 Notion 的标签分类功能确实不太好用…… 看了看其它文章中配置多级标签的繁杂流程之后，我觉得还是写一个插件比较靠谱……

本文主要介绍 Notion 简单的插件开发，编程语言使用 JavaScript，所以熟悉 JS 的同学应该很快就能上手。官网链接：https://developers.notion.com/docs/getting-started，英语好的同学自取。

1. Notion 数据库

Notion 的灵魂在于数据库，它是 Notion 中最强大也最复杂的功能。下面简单梳理一下 Notion 数据库会用到的知识，其它内容估计自己试试也能摸索出来。数据库官方文档：https://www.notion.so/zh-cn/help/category/databases。

1.1 数据库是什么

简单来说，数据库是一个包含了多个 Notion 页面的集合。数据库可以以多种视图动态展现数据库下的页面：

我们一般常用表格（Table）、看板（Board）、列表（List）三种视图，这里方便起见先用列表演示。列表中展示了数据库下所有的页面，初始化几个页面：

把它们在表格视图下展示就是这个样子。同样地，你也可以在表格中的“名称”一栏新建数据库页面。

1.2 页面属性

数据库中的页面与普通页面不一样，它具有属性（Property）。例如上图的标签、日期就都是属性。常用的属性类型有文本、单选、多选、状态等。

给页面添加属性可以在“表格”视图添加，也可以在页面内部添加：

（可能有些反直觉，但标签确实是用“多选”类型实现的）

那如何新建属性呢？点击表格视图下标题栏的“+”号，选择一个类型：

再根据提示操作即可。

简单布置一下，高级文章管理面板的感觉是不是出来了？

2. 创建你的第一个插件

终于进入正题了。这里将创建第一个 Notion 插件。全程只使用了一个 Notion API：数据库读取。

2.1 先决条件

一定的准备条件（虽然大部分同学可能已经拥有）

• Node.js 及 NPM
• 一个 Notion 账号及默认工作空间
• 一个趁手的 IDE，这里以 VS Code 演示

2.2 在 Notion 中创建插件

（Notion 中，我们又将插件（Plug-in）称为集成（Integration））

打开集成页面，创建新集成；

填写基本信息（集成分为自用的内部集成和公共集成，免费版用户只能创建内部集成）：

保存之后你会得到一个集成密钥。复制备用。

2.3 准备 Node.js 环境

用 VS Code 打开一个文件夹，输入以下内容初始化并安装依赖：

npm init
npm install @notionhq/client

然后新建文件 index.js；

新建一个数据库。你可以自己添加内容，也可以复制官方模拟数据。然后在页面中复制 Database ID（如下图）：

在数据库页面授权你的插件访问，不然请求会被拒绝：

然后就是 index.js 了~

打开 index.js，引入 Client：

const {
    Client } = require("@notionhq/client");

定义几个常量：

const NOTION_KEY = "xxx"; // 此处填写你的集成密钥
const NOTION_DATABASE_ID = "xxx"; // 此处填写 Database ID

创建主函数（异步），并在结尾调用。创建新的 Client：

async function main() {
   
  const notion = new Client({
    auth: NOTION_KEY });
}

main();

读取数据库：

const response = await notion.databases.retrieve({
    database_id: NOTION_DATABASE_ID }); ;console.log(response);

全貌：

const {
    Client } = require("@notionhq/client");

const NOTION_KEY = "xxx"; // 此处填写你的集成密钥
const NOTION_DATABASE_ID = "xxx"; // 此处填写 Database ID

async function main() {
   
  const notion = new Client({
    auth: NOTION_KEY });
  const response = await notion.databases.retrieve({
    database_id: NOTION_DATABASE_ID });	
  console.log(response);
}

main();

运行：

node index.js

成功！

3. Notion 页面 API

插件与 Notion 的交互主要依靠 API（即前面提到的 Client）。这里简单介绍一下 Notion 的页面 API。

官方文档：https://developers.notion.com/reference/post-page

3.1 读取页面信息

做实验肯定需要原材料。所以打开数据库中的一个页面，随便写点什么：

刚刚的数据库有 Database ID，那么页面肯定有 Page ID。复制备用：

读取页面信息的 API 是 notion.pages.retrieve({page_id: string})，用上面的 Page ID 尝试一下：

const {
    Client } = require("@notionhq/client");

const NOTION_KEY = "xxx";
const NOTION_PAGE_ID = "xxx"; // 刚刚复制的 Page ID

async function main() {
   
  const notion = new Client({
    auth: NOTION_KEY });
  const response = await notion.pages.retrieve({
    page_id: NOTION_PAGE_ID });
  console.log(response);
}

main();

看看返回了什么：

{
   
  object: 'page',
  id: 'your_page_id',
  created_time: '2024-08-14T00:13:00.000Z',
  last_edited_time: '2024-08-14T03:00:00.000Z',
  cr