平台实体数据源

在自定义组件中，可通过 Neo OpenAPI SDK（neo-open-api）访问平台实体数据源，用于查询或写入平台业务数据。

业务对象 API（xObject）

1. 查询业务对象数据列表

使用通用查询接口获取业务对象数据，支持分页与排序。

import { xObject } from 'neo-open-api';

// 基本查询（无 where）
const result = await xObject.query({
  xObjectApiKey: 'xxObject', // 业务对象 API Key
  fields: ['name', 'phone', 'email'], // 查询字段
  page: 1, // 页码（可选）
  pageSize: 10, // 每页数量（可选）
  orderBy: 'id asc' // 排序（可选，仅支持 id）
});

// where 为字符串：与通用查询 SQL 语法一致，拼接到 `select ... from ...` 之后
const byString = await xObject.query({
  xObjectApiKey: 'xxObject',
  fields: ['name', 'city'],
  where: "city = '北京' and name like '张%'",
  page: 1,
  pageSize: 20
});

// where 为字符串数组：多项以 ` and ` 连接，便于拆分、复用条件片段
const byArray = await xObject.query({
  xObjectApiKey: 'xxObject',
  fields: ['name', 'status'],
  where: ["status = '生效'", "name like '李%'"],
  page: 1,
  pageSize: 20
});
// 与 where: "status = '生效' and name like '李%'" 等价

参数说明

参数	说明
xObjectApiKey	业务对象的 API Key
fields	待查询字段数组；会自动补充 id
where（可选）	过滤条件。字符串：完整 WHERE 子句内容（不含关键字 where），语法与平台通用查询一致（见下文「查询条件与 SQL」）。字符串数组：每段为一条条件表达式，默认按顺序用 and 拼接；空串、null、undefined 会被忽略。若需 or 或复杂嵌套，请使用字符串形式，例如 (a = 1 or b = 2) and c = 3。
page	页码，默认 1
pageSize	每页条数，默认 10
orderBy	排序表达式，仅支持对 id 排序，例如 id asc 或 id desc

查询条件与 SQL 说明（与 /rest/data/v2/query 通用查询一致）

xObject.query 会将 fields、xObjectApiKey、where、orderBy 与分页参数拼装为 SQL，通过请求参数 q 提交。下列限制适用于该查询能力。

不支持的字段类型（查询条件中）

多选、文本域、地理位置、图片、引用。

SELECT

• 由 fields 生成；不支持 *，须显式列出字段；未传入时也会自动加入 id。

FROM

• 由 xObjectApiKey 生成；可查询所有自定义对象，以及本文档涉及的标准对象。

WHERE

• 由 where 生成；各对象字段定义可通过该对象的 description 接口获取。
• 不支持对「多值字段」做取值条件，此类字段仅可使用 is null 或 is not null。
• 支持的操作符：=、!=、like、not like、not in、is not null、is null、>、<、<>、>=、<=、in、between ... and ...。
• =、like、in 补充说明
  • =（字符串）为精确匹配。例如 city = '北京' 仅匹配字段值等于「北京」的记录。
  • like 须用 % 做模糊匹配，例如 city like '北京%' 表示以「北京」开头。当前仅支持将 % 写在已知内容之后（如 '北京%'），不支持 city like '%北京' 等形式。
  • SQL 中含 % 等需编码的字符时，应对 SQL 做 URL 编码。SDK 使用 GET，将 SQL 作为查询参数 q 传递（axios 会序列化 params；若自行拼 URL，请确保编码正确）。
  • 支持 in，不支持子查询形式的 in (...)。
• 逻辑运算符：and、or。

ORDER BY

• 由 orderBy 生成；支持 asc / desc；当前仅支持对 id 排序。其他字段排序可在取回列表后在客户端处理。

LIMIT

• 由 page、pageSize 生成。

返回结构

{
  status: boolean;   // true 表示成功
  code: number;      // 返回码
  msg: string;       // 多为错误信息
  totalSize: number; // 总条数
  data: any[];       // 数据行
}

2. 获取业务类型列表

获取指定业务对象下的业务类型列表。

import { xObject } from 'neo-open-api';

const result = await xObject.getEntityTypeList('xObjectApiKey', {
  // 其他请求选项
});

参数说明

• xObjectApiKey：业务对象的 API Key
• options：可选请求配置

返回结构：与上文「查询」的 status / code / msg / totalSize / data 形式一致（data 为列表数据）。

3. 获取实体列表

获取系统中的对象列表（标准对象、自定义对象或二者）。

import { xObject } from 'neo-open-api';

// 标准对象 + 自定义对象（有权限的）
const { data: allEntities } = await xObject.getEntityList({
  active: true
});

// 仅标准对象
const { data: standardObjects } = await xObject.getEntityList({
  custom: false,
  active: true
});

// 仅自定义对象
const { data: customObjects } = await xObject.getEntityList({
  custom: true,
  active: true
});

参数说明

• custom：是否限定为自定义对象。false 仅标准对象，true 仅自定义对象；不传则返回全部实体。
• active：是否仅返回当前用户有权限的对象，默认 true。

返回结构：同「查询」列表类接口（含 totalSize、data 等）。

4. 创建业务数据

import { xObject } from 'neo-open-api';

const result = await xObject.create('xObjectApiKey', {
  data: {
    name: '张三',
    phone: '13800138000',
    email: 'zhangsan@example.com'
  }
});

参数说明

• xObjectApiKey：业务对象的 API Key
• options.data：待创建字段键值

返回结构

{
  status: boolean;
  code: number;
  msg: string;
  totalSize: number;
  data: Object; // 新建记录
}

5. 更新业务数据

import { xObject } from 'neo-open-api';

const result = await xObject.update('xObjectApiKey', 'xObjectId', {
  data: {
    name: '李四',
    phone: '13900139000'
  }
});

参数说明

• xObjectApiKey：业务对象的 API Key
• xObjectId：记录主键
• options.data：待更新字段

返回结构

{
  status: boolean;
  code: number;
  msg: string;
  data: Object;
}

6. 获取业务数据详情

import { xObject } from 'neo-open-api';

// 方式一：对象参数
const result = await xObject.get({
  xObjectApiKey: 'xxKey',
  xObjectId: 'xxId',
  option: {
    // 其他请求选项
  }
});

// 方式二：位置参数
const result2 = await xObject.get('xObjectApiKey', 'xObjectId', {
  // 其他请求选项
});

参数说明

• xObjectApiKey：业务对象的 API Key
• xObjectId：记录 ID
• options：可选请求配置

返回结构

{
  status: boolean;
  code: number;
  msg: string;
  data: Object;
}

7. 删除业务数据

import { xObject } from 'neo-open-api';

const result = await xObject.delete('xObjectApiKey', 'xObjectId');

参数说明

• xObjectApiKey：业务对象的 API Key
• xObjectId：待删除记录 ID

返回结构

{
  status: boolean;
  code: number;
  msg: string;
}

8. 获取业务对象描述（字段元数据）

import { xObject } from 'neo-open-api';

const result = await xObject.getDesc('xObjectApiKey');

参数说明

• xObjectApiKey：业务对象的 API Key

综合示例（以联系人对象为例）

import { xObject } from 'neo-open-api';

const { data: contacts } = await xObject.query({
  xObjectApiKey: 'Contact',
  fields: ['name', 'phone', 'email'],
  page: 1,
  pageSize: 20,
  orderBy: 'id desc'
});

const { data: newContact } = await xObject.create('Contact', {
  data: {
    name: '王五',
    phone: '13700137000',
    email: 'wangwu@example.com'
  }
});

const { data: updatedContact } = await xObject.update('Contact', newContact.id, {
  data: {
    name: '王五（更新）'
  }
});

const { data: contactDetail } = await xObject.get('Contact', newContact.id);

await xObject.delete('Contact', newContact.id);