Flutter控制台客户端插件cockpit_client的使用

介绍

cockpit_client 是一个用于与 Cockpit CMS 进行交互的 HTTP 客户端。

如何安装

Flutter

$ flutter pub add cockpit_client

Pubspec.yaml

在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  cockpit_client: ^1.0.6-b

然后运行以下命令来获取依赖：

flutter pub get

导入

在你的 Dart 代码中导入该库：

import 'package:cockpit_client/cockpit_client.dart';

如何初始化

最小化初始化

import 'package:cockpit_client/cockpit_client.dart';

// 最小化初始化
Cockpit.init(
    server: Uri.parse("http://[SERVER HOST]"),
    token: "[API TOKEN]",
);

自定义路径

如果 Cockpit 不在根目录下，可以自定义路径：

import 'package:cockpit_client/cockpit_client.dart';

// 自定义路径
Cockpit.init(
    server: Uri.https("[SERVER HOST]", "/cockpit/folder"), // 或者使用 Uri.http 或 Uri.parse
    token: "[API TOKEN]",
);

全局过滤器

为所有请求设置默认过滤器：

import 'package:cockpit_client/cockpit_client.dart';

// 永远不获取已删除的字段
Cockpit.init(
    server: Uri.https("[SERVER HOST]", "/cockpit/folder"),
    token: "[API TOKEN]",
    defaultFilter : {
      r"$or" :[
        { "delete" : {$eq : false} },
        { "delete" : {$eq : null} },
        {
          "delete" : {
            r"$exist" : false
          }
        }
      ]
    }
);

声明端点（可选）

你可以声明一些特定的端点：

import 'package:cockpit_client/cockpit_client.dart';

// API 声明
Cockpit.init(
    server: Uri.https("[SERVER HOST]", "/cockpit/folder"),
    token: "[API TOKEN]",
    api : { 
      // Collection
      "myCollection" :  {
        "collection": "users", // 真实的集合名称
        "sort": {"login": 1}, // 默认排序
        "fields": [ // 获取这些字段
          "nom",
          "prenom",
          "parent",
          "login",
          "enabled",
          "_create_by"
        ]
      },
      // Form
      "myForm" :  {
        "form": "sendmail" // 真实的表单名称
      },
      // Singleton
      "mySingleton" : {
        "singleton": "configurations" // 真实的单例名称
      },
      // 集合带有虚拟属性（映射）
      "slides" : {
        "collection": "collection_name", // 在 Cockpit 中的集合名称
        "limit": 5, // 从服务器获取数据时的限制
        "sort": { // 排序结果
          "_o": 1
        },
        "fields": [ // 从服务器获取的字段，其他字段将被忽略
          "title",
          "image",
          "description",
          "backgroundColor",
          "fontColor"
        ],
        "map": { // 更改属性值或在结果对象中设置新属性
          // 可以从模板构建字符串
          "image": "{{SERVER}}{{image.path}}",
          // 或将属性值映射到另一个
          "body" : "{{description}}"
        },
      },
    }
);

如何使用

读取数据

import 'package:cockpit_client/cockpit_client.dart';

// 获取所有元素
List<Map<String, dynamic>> results = await Cockpit("api_access").find(
  cache: Duration(hours : 1), // [可选] 缓存结果
);

// 获取第一个元素
Map<String, dynamic> result = await Cockpit("user").findOne(
  filter: {
    "login" : "root",
    "pwd" : "secret",
    r"$or": [
      {"disable": false},
      {
        "disable": {
          r"$exists": false,
        },
      },
    ],
  },
);

// 获取特定元素
Map<String, dynamic> result = await Cockpit("user").get("[My Super ID]");
// 获取某些特定字段
Map<String, dynamic> result = await Cockpit("user").get("[My Super ID]", fields : ["nom", "prenom"]);

// 获取一页的数据
List<Map<String, dynamic>> results = await Cockpit("api_access").find(
  limit : 10,
  page : 2
); // 页码从0开始，page=0表示第一页，page=1表示第二页

// 使用过滤器获取数据
List<Map<String, dynamic>> results = await Cockpit("api_access").find(
  filter: {
    published : true,
  },
);

读取未声明的端点

可以通过前缀来指定类型（表单、单例、集合或自定义URL）。

保存数据

import 'package:cockpit_client/cockpit_client.dart';

// 向 Cockpit 发送数据（表单和集合）
Map<String, dynamic> data = await Cockpit("api_access").save(
  data : {
    published : false,
    title : "Cool",
    description : "I'm just a test :-p",
  },
);

向自定义URL发送数据

import 'package:cockpit_client/cockpit_client.dart';

// 向自定义 Cockpit URL 发送数据
Map<String, dynamic> data = await Cockpit("!/addons/save/gps").get(
  data : {
    lat : -19.016682,
    long : 26.806641,
    alt : 15,
  },
);

Cockpit URL

用户认证

Cockpit.authUser('username', 'xxpasswordxx');

创建/更新用户

Cockpit.saveUser({...}); // 用户数据（user, name, email, active, group）

获取用户列表

Cockpit.listUsers([Map<String, dynamic> filter]); // （可选）可以传递过滤条件

获取资产

Cockpit.assets([Map<String, dynamic> filter]); // （可选）可以传递过滤条件

获取缩略图URL

Cockpit.image(imagePath, 
  width : width,
  height : height,
  quality : quality,
  domain : domain,
  o : o,
  base64 : base64,
);

获取所有单例

Cockpit.listSingletons();

获取所有集合

Cockpit.listCollections();

获取集合模式

Cockpit("collectionname").schema();

更新集合模式

Cockpit("collectionname").updateSchema(fields); // fields 是 List<Map<String, dynamic>>

示例代码

以下是一个完整的示例代码：

import 'package:cockpit_client/cockpit_client.dart';

void main() async {
  // 初始化 Cockpit 客户端
  Cockpit.init(
    server: Uri.parse("http://192.168.2.1"),
    token: "58e20fae9f86dc1a493d11bc5d6a18",
    defaultFilter: {
      // 全局过滤器
      r"$or": [
        {"delete": false},
        {
          "delete": {r"$exists": false}
        }
      ]
    },
    api: {
      // 集合
      "users": {
        "collection": "users",
        "sort": {"login": 1},
        "fields": ["nom", "prenom", "parent", "login", "enabled", "_create_by"]
      },
      "myForm": {"form": "sendmail"},
      "mySingleton": {"singleton": "configurations"},
      "slides": {
        "collection":
            "collection_or_form_name", // 在 Cockpit 中的集合或表单名称
        "limit": 5, // 从服务器获取数据时的限制
        "sort": {
          // 排序结果
          "_o": 1
        },
        "fields": [
          // 从服务器获取的字段，其他字段将被忽略
          "title",
          "image",
          "description",
          "backgroundColor",
          "fontColor"
        ],
        "map": {
          // 更改属性值或在结果对象中设置新属性
          // 可以从模板构建字符串
          "image": "{{SERVER}}{{image.path}}",
          "body": "{{description}}"
        },
      },
    }
  );

  // 打印查询结果
  print(await Cockpit("users").find(
    cache: Duration(hours: 1), // [可选] 缓存结果
  ));
}