200 lines
4.0 KiB
Markdown
200 lines
4.0 KiB
Markdown
# NocoDB API SDK
|
||
|
||
一个轻量级的 NocoDB API SDK，支持表记录操作和 Base 管理功能。
|
||
|
||
## 功能特性
|
||
|
||
- 📋 **记录操作**: 完整的 CRUD 操作支持
|
||
- 🗄️ **Base 管理**: 创建、列出、更新、删除 Bases
|
||
- 🔗 **关联数据**: 支持链接字段操作
|
||
- 📊 **统计信息**: 获取 Base 和记录统计
|
||
- 🎯 **类型安全**: 完整的 TypeScript 类型定义
|
||
|
||
## 快速开始
|
||
|
||
### 基本用法
|
||
|
||
```ts
|
||
import { NocoApi } from '@kevisual/noco';
|
||
|
||
const nocoApi = new NocoApi({
|
||
baseURL: 'https://your-nocodb-instance.com',
|
||
token: 'your-api-token',
|
||
table: 'your-table-name' // 可选，用于记录操作
|
||
});
|
||
|
||
// 记录操作
|
||
const listResult = await nocoApi.record.list();
|
||
await nocoApi.record.update({ Id: 1, Title: '更新的标题' });
|
||
```
|
||
|
||
### Base 管理
|
||
|
||
```ts
|
||
// 列出所有 Bases
|
||
const bases = await nocoApi.meta.bases.list();
|
||
console.log('所有 Bases:', bases.list);
|
||
|
||
// 创建新的 Base
|
||
const newBase = await nocoApi.meta.bases.create({
|
||
title: '我的新项目',
|
||
description: '项目描述',
|
||
color: '#ff6b35'
|
||
});
|
||
|
||
// 获取 Base 信息
|
||
const baseInfo = await nocoApi.meta.bases.get('base-id');
|
||
|
||
// 更新 Base
|
||
await nocoApi.meta.bases.update('base-id', {
|
||
title: '更新的项目名',
|
||
description: '更新的描述'
|
||
});
|
||
|
||
// 删除 Base
|
||
await nocoApi.meta.bases.delete('base-id');
|
||
```
|
||
|
||
### 高级功能
|
||
|
||
```ts
|
||
// 复制 Base
|
||
const duplicatedBase = await nocoApi.meta.bases.duplicate('base-id', {
|
||
title: '复制的项目',
|
||
description: '这是一个复制的项目'
|
||
});
|
||
|
||
// 获取 Base 统计信息
|
||
const stats = await nocoApi.meta.bases.getStats('base-id');
|
||
|
||
// 导入/导出 Base
|
||
await nocoApi.meta.bases.importBase(importData);
|
||
const exportData = await nocoApi.meta.bases.export('base-id');
|
||
```
|
||
|
||
## API 参考
|
||
|
||
### NocoApi 构造函数选项
|
||
|
||
```ts
|
||
type NocoApiOptions = {
|
||
table?: string; // 表名（用于记录操作）
|
||
token?: string; // API 令牌
|
||
baseURL?: string; // NocoDB 实例 URL
|
||
};
|
||
```
|
||
|
||
### Base 操作类型
|
||
|
||
```ts
|
||
type BaseInfo = {
|
||
id?: string;
|
||
title: string;
|
||
description?: string;
|
||
config?: Record<string, any>;
|
||
color?: string;
|
||
meta?: Record<string, any>;
|
||
order?: number;
|
||
prefix?: string;
|
||
status?: string;
|
||
type?: string;
|
||
created_at?: string;
|
||
updated_at?: string;
|
||
};
|
||
|
||
type CreateBaseData = {
|
||
title: string;
|
||
description?: string;
|
||
color?: string;
|
||
meta?: Record<string, any>;
|
||
config?: Record<string, any>;
|
||
};
|
||
```
|
||
|
||
### 记录操作
|
||
|
||
```ts
|
||
// 查询参数
|
||
type QueryParams = {
|
||
fields?: string | string[]; // 选择字段
|
||
sort?: string | string[]; // 排序
|
||
where?: string; // 查询条件
|
||
offset?: number; // 偏移量
|
||
limit?: number; // 限制数量
|
||
viewId?: string; // 视图 ID
|
||
};
|
||
|
||
// 列出记录
|
||
await nocoApi.record.list<T>(params);
|
||
|
||
// 创建记录
|
||
await nocoApi.record.create(data);
|
||
|
||
// 读取记录
|
||
await nocoApi.record.read(id);
|
||
|
||
// 更新记录
|
||
await nocoApi.record.update(data);
|
||
|
||
// 删除记录
|
||
await nocoApi.record.delete({ Id: id });
|
||
|
||
// 获取记录数量
|
||
await nocoApi.record.count();
|
||
```
|
||
|
||
### 链接字段操作
|
||
|
||
```ts
|
||
// 列出链接记录
|
||
await nocoApi.record.listLinks(linkFieldId, recordId);
|
||
|
||
// 更新链接
|
||
await nocoApi.record.updateLinks(linkFieldId, recordId, data);
|
||
|
||
// 删除链接
|
||
await nocoApi.record.deleteLinks(linkFieldId, recordId);
|
||
```
|
||
|
||
## 独立使用 Meta API
|
||
|
||
```ts
|
||
import { MetaBases } from '@kevisual/noco';
|
||
|
||
const metaBases = new MetaBases({
|
||
token: 'your-api-token',
|
||
baseURL: 'https://your-nocodb-instance.com'
|
||
});
|
||
|
||
const bases = await metaBases.list();
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
```ts
|
||
try {
|
||
const result = await nocoApi.meta.bases.create({
|
||
title: '新项目'
|
||
});
|
||
|
||
if (result.code === 200) {
|
||
console.log('创建成功:', result.data);
|
||
} else {
|
||
console.error('创建失败:', result.message);
|
||
}
|
||
} catch (error) {
|
||
console.error('请求错误:', error);
|
||
}
|
||
```
|
||
|
||
## 参考资料
|
||
|
||
### Meta API
|
||
https://nocodb.com/apis/v2/meta
|
||
|
||
### Data API
|
||
https://nocodb.com/apis/v2/data
|
||
|
||
## 许可证
|
||
|
||
MIT |