Datasheet

model/datasheet.Datasheet

表格操作

如果想操作表格，如获取表格数据、新增记录、删除记录等，推荐使用 useDatasheet 钩子函数

如果需要获取记录数据，可以使用 useRecord（查询单条记录数据）、useRecords（批量查询记录数据）

• addRecord: 新增记录

• addRecords: 批量新增记录

• setRecord: 修改记录的值

• setRecords: 批量修改记录的值

• deleteRecord: 删除记录

• deleteRecords: 批量删除记录

• addField: 新增字段

• deleteField: 删除字段

• checkPermissionsForAddRecord: 校验用户是否有权限新增记录

• checkPermissionsForAddRecords: 校验用户是否有权限批量新增记录

• checkPermissionsForSetRecord: 校验用户是否有有权限修改记录的值

• checkPermissionsForSetRecords: 校验用户是否有有权限批量修改记录的值

• checkPermissionsForDeleteRecord: 校验用户是否有权限删除记录

• checkPermissionsForDeleteRecords: 校验用户是否有权限批量删除记录

• checkPermissionsForAddField: 校验用户是否有权限新增字段

• checkPermissionsForDeleteField: 校验用户是否有权限删除字段

配件

id

• get id(): undefined | string

表格 id, 表格的唯一标识

返回值

undefined | string

示例

console.log(myDatasheet.id);
// => 'dstxxxxxxx'

---

name

• get name(): undefined | string

表格名称

返回值

undefined | string

示例

console.log(myDatasheet.name);
// => 'Name'

方法

addRecord

▸ addRecord(valuesMap?, insertPosition?): Promise<string>

新增记录

参数

Name	Type	Description
valuesMap	Object	key 为 fieldId, value 为单元格内容的 object
insertPosition?	IInsertPosition	要在视图中插入的位置

返回值

Promise<string>

返回新增的记录 ID

描述

新增一条记录，并可选的指定它在视图中的位置（默认在最后）, 返回新增的记录 ID 数组

当用户无权限进行操作或者单元格值格式校验不通过时，将会抛出错误

有关单元格值写入格式，请参阅 FieldType

示例

async function addNewRecord(valuesMap) {
  if (datasheet.checkPermissionsForAddRecord(valuesMap).acceptable) {
    const newRecordId = await datasheet.addRecord(valuesMap);
    alert(`新创建的记录 ID 为： ${newRecordId}`);

    // 接下来可以对新创建的 records 进行选择，或者操作了
    // ...
  }
}

// 参数的 key 为 fieldId， value 为单元格值
addNewRecord({
  fld1234567980: 'this is a text value',
  fld0987654321: 1024,
});

// 不同类型的字段单元格值有特定的数据结构，需要进行正确的传入
addNewRecord({
  fld1234567890: 'this is a text value', // SingleLineText 单行文本
  fld0987654321: 1024, // Number 数字
  fld1234567891: '选项 1', // SingleSelect 单选
  fld1234567892: ['选项 1', '选项 2'], // MultiSelect 多选
  fld1234567893:  1635513510962, // DateTime 日期 （时间戳）
  fld1234567894: ['rec1234567'], // TwoWayLink 双向关联 （recordId)
});

---

addRecords

▸ addRecords(records?, insertPosition?): Promise<string[]>

批量新增记录

参数

Name	Type	Default value	Description
records	{ valuesMap: { [key: string]: any; } }[]	[]	key 为 fieldId, value 为单元格内容的 object
insertPosition?	IInsertPosition	undefined	要在视图中插入的位置

返回值

Promise<string[]>

返回新增的记录 ID 数组

描述

新增多条记录，并可选的指定它在视图中的位置（默认在最后插入）

当用户无权限进行操作或者单元格值格式校验不通过时，将会抛出错误

有关单元格值写入格式，请参阅 FieldType

示例

const records = [
  // valuesMap 的 key 为 fieldId value 为单元格内容
  {
    valuesMap: {
      fld1234567890: 'this is a text value',
      fld0987654321: 1024,
    },
  },
  // valuesMap 指定为空对象时，将会创建一条空记录
  {
    valuesMap: {},
  },
  // 不同类型的字段单元格值有特定的数据结构，需要进行正确的传入
  {
    valuesMap: {
      fld1234567890: 'Cat video 2', // SingleLineText 单行文本
      fld0987654321: 1024, // Number 数字
      fld1234567891: '选项 1', // SingleSelect 单选
      fld1234567892: ['选项 1', '选项 2'], // MultiSelect 多选
      fld1234567893:  1635513510962, // DateTime 日期 （时间戳）
      fld1234567894: ['rec1234567'], // TwoWayLink 双向关联 （recordId)
    },
  },
];

async function addNewRecords() {
  if (datasheet.checkPermissionToAddRecords(records)) {
    const recordIds = await datasheet.addRecords(records);

    alert(`新创建的记录 IDs: ${recordIds}`);

    // 接下来可以对新创建的 records 进行选择，或者操作了
    // ...
  }
}

---

setRecord

▸ setRecord(recordId, valuesMap?): Promise<void>

修改记录的值

参数

Name	Type	Description
recordId	string	指定要修改的 record
valuesMap	Object	key 为 fieldId, value 为单元格内容的 object，只需要传入要修改 value，无需修改的key value 则不需要传入。要清空一个 field，需要传入 key: null

返回值

Promise<void>

描述

当无权限，或者 recordId 不存在，或者写入的值类型不匹配的时候，会抛出对应的错误

我们将一个 record 中的一个 field 称作单元格。有关单元格值写入格式，请参阅 FieldType

如果你需要同时修改多个记录，请使用 setRecords

示例

function setRecord(recordId, valuesMap) {
  if (datasheet.checkPermissionsForSetRecord(recordId, valuesMap).acceptable) {
    datasheet.setRecord(recordId, valuesMap);
  }
}

---

setRecords

▸ setRecords(records): Promise<void>

批量修改记录的值

参数

Name	Type	Description
records	{ id: string ; valuesMap: { [key: string]: any; } }[]	指定要修改的 records

返回值

Promise<void>

描述

当无权限，或者 recordId 不存在，或者写入的值类型不匹配的时候，会抛出对应的错误

valuesMap key 为 fieldId, value 为单元格内容的 object，只需要传入要修改 value，无需修改的key value 则不需要传入。要清空一个 field，需要传入 key: null

我们将一个 record 中的一个 field 称作单元格。有关单元格值写入格式，请参阅 FieldType

如果你只需要修改单个记录，请使用 setRecord

示例

function setRecord(id, valuesMap) {
  if (datasheet.checkPermissionsForSetRecords([{ id, valuesMap }]).acceptable) {
    datasheet.setRecords([{ id, valuesMap }]);
  }
}

---

deleteRecord

▸ deleteRecord(recordId): Promise<void>

删除记录

参数

Name	Type	Description
recordId	string	记录 Id

返回值

Promise<void>

描述

通过 recordId 删除一条记录

当用户无权限进行操作时，将会抛出错误

示例

async function deleteRecord(recordId) {
  if (datasheet.checkPermissionsForDeleteRecord(recordId).acceptable) {
    await datasheet.deleteRecord(recordId);
    alert('记录已被删除');

    // 记录此时已经被删除
  }
}

---

deleteRecords

▸ deleteRecords(recordIds): Promise<void>

批量删除记录

参数

Name	Type	Description
recordIds	string[]	记录 Id 数组

返回值

Promise<void>

描述

通过 recordIds 数组批量删除记录

当用户无权限进行操作时，将会抛出错误

示例

async function deleteRecords(recordIds) {
  if (datasheet.checkPermissionsForDeleteRecords(recordIds).acceptable) {
    await datasheet.deleteRecords(recordIds);
    alert('记录已被批量删除');

    // 记录此时已经被删除
  }
}

---

addField

▸ addField(name, type, property): Promise<string>

新增字段

参数

Name	Type	Description
name	string	字段名称
type	FieldType	字段类型
property	IAddOpenFieldProperty	字段属性

返回值

Promise<string>

描述

有关新增字段属性值写入格式，请参阅 FieldType

当用户无权限进行操作时，将会抛出错误

示例

function addField(name, type, property) {
  if (datasheet.checkPermissionsForAddField(name, type, property).acceptable) {
    datasheet.addField(recordIds);
  }
}

---

deleteField

▸ deleteField(fieldId, conversion?): Promise<void>

删除字段

参数

Name	Type	Description
fieldId	string	字段ID
conversion?	Conversion	删除字段为关联字段的时候，标记关联表的关联字段是删除还是转换成文本，默认为 转成文本字段

返回值

Promise<void>

描述

当用户无权限进行操作时，将会抛出错误

示例

function deleteField(fieldId) {
  if (datasheet.checkPermissionsForDeleteField(fieldId).acceptable) {
    datasheet.deleteField(fieldId);
  }
}

---

checkPermissionsForAddRecord

▸ checkPermissionsForAddRecord(valuesMap?): IPermissionResult

校验用户是否有权限新增记录

参数

Name	Type	Description
valuesMap?	Object	key 为 fieldId, value 为单元格内容的 object

返回值

IPermissionResult

描述

接受一个可选的 valuesMap 输入，valuesMap 是 key 为 fieldId, value 为单元格内容的 object

valuesMap 的格式和写入单元格时的格式相同。有关单元格值写入格式，请参阅 FieldType

如果有权限操作则返回 {acceptable: true}

如果无权限操作则返回 {acceptable: false, message: string} ，message 为显示给用户的失败原因解释

示例

// 校验用户是否有权限新增一条记录，当新增的同时也有写入值的话，也可以一并进行校验
const setRecordCheckResult = datasheet.checkPermissionsForAddRecord({
  'fld1234567890': 'Advertising campaign',
  'fld0987654321': 1024,
});
if (!setRecordCheckResult.acceptable) {
  alert(setRecordCheckResult.message);
}

// 校验用户是否有新增记录的权限，但并不校验具体的值（示例：可以用来在 UI 控制创建按钮可用状态）
const addUnknownRecordCheckResult =
  datasheet.checkPermissionsForAddRecord();

---

checkPermissionsForAddRecords

▸ checkPermissionsForAddRecords(records?): IPermissionResult

校验用户是否有权限批量新增记录

参数

Name	Type	Description
records?	{ valuesMap: { [key: string]: any; } }[]	接收一个可选的 records 数组

返回值

IPermissionResult

描述

records 是 key 为 fieldId, value 为单元格内容的 object

records 的格式和写入单元格时的格式相同。有关单元格值写入格式，请参阅 FieldType

如果有权限操作则返回 {acceptable: true}

如果无权限操作则返回 {acceptable: false, message: string} ，message 为显示给用户的失败原因解释

示例

// 校验用户是否有权限新增记录，当新增的同时也有写入值的话，也可以一并进行校验
const addRecordsCheckResult = datasheet.checkPermissionsForAddRecords([
  {
    valuesMap: {
      fld1234567890: 'this is a text value',
      fld0987654321: 1024,
    },
  },
  {
    valuesMap: {
      fld1234567890: 'this is another text value',
      fld0987654321: 256,
    },
  },
  {},
]);
if (!addRecordsCheckResult.acceptable) {
  alert(addRecordsCheckResult.message);
}
// 校验用户是否有新增记录的权限，但并不校验具体的值（示例：可以用来在 UI 控制新增按钮可用状态）
// 与 checkPermissionsForSetRecord 一致
const addUnknownRecordCheckResult =
  datasheet.checkPermissionsForAddRecords();

---

checkPermissionsForSetRecord

▸ checkPermissionsForSetRecord(recordId?, valuesMap?): IPermissionResult

校验用户是否有有权限修改记录的值

参数

Name	Type	Description
recordId?	string	要修改的 recordId
valuesMap?	Object	是 key 为 fieldId, value 为单元格内容的 object

返回值

IPermissionResult

IPermissionResult

描述

recordId 是要修改的 recordId, valuesMap 是 key 为 fieldId, value 为单元格内容的 object

该方法会根据传入值的详细程度来进行权限以及值合法性校验。传入 valuesMap 会进行单元格写入合法性、列权限校验，传入 recordId 会进行记录存在性，和修改权限校验

valuesMap 的格式和写入单元格时的格式相同。有关单元格值写入格式，请参阅 FieldType

如果有权限操作则返回 {acceptable: true}

如果无权限操作则返回 {acceptable: false, message: string} ，message 为显示给用户的失败原因解释

示例

// 校验用户是否有权限修改一个具体的 record 中的两个具体的字段
const setRecordCheckResult =
  datasheet.checkPermissionsForSetRecord('rec1234567', {
    'fld1234567890': 'this is a text value',
    'fld0987654321': 1024,
  });
if (!setRecordCheckResult.acceptable) {
  alert(setRecordCheckResult.message);
}

// 校验用户是否有权限修改一个记录，但不校验具体值是否能修改
const setUnknownFieldsCheckResult =
  datasheet.checkPermissionsForSetRecord('rec1234567');

// 校验用户是否有权限修改对应字段，不关心具体的记录
const setUnknownRecordCheckResult =
  datasheet.checkPermissionsForSetRecord(undefined, {
    'fld1234567890': 'this is a text value',
        // 你也可以选择不传入具体值，使用 undefined 代替，这将不进行值类型校验
    'fld0987654321': undefined,
  });
// 不传入任何值，也可以校验用户是否有权限修改记录，但不校验任何具体的记录和字段（也就是说即使返 acceptable 为 true，也可能有部分字段或者记录无权限修改，你可以用这个方式来显示是否小程序处于只读状态）
const setUnknownRecordAndFieldsCheckResult =
  datasheet.checkPermissionsForSetRecord();

---

checkPermissionsForSetRecords

▸ checkPermissionsForSetRecords(records): IPermissionResult

校验用户是否有有权限批量修改记录的值

参数

Name	Type	Description
records	{ id?: string ; valuesMap?: { [key: string]: any; } }[]	要修改的 records

返回值

IPermissionResult

IPermissionResult

描述

接收一个可选的 records 数组

recordId 是要修改的 recordId, valuesMap 是 key 为 fieldId, value 为单元格内容的 object

该方法会根据传入值的详细程度来进行权限、值合法性校验。传入 valuesMap 会进行单元格写入合法性、列权限校验，传入 recordId 会进行记录存在性，和修改权限校验

valuesMap 的格式和写入单元格时的格式相同。有关单元格值写入格式，请参阅 FieldType

如果有权限操作则返回 {acceptable: true}

如果无权限操作则返回 {acceptable: false, message: string}，message 为显示给用户的失败原因解释

示例

const recordsToSet = [
  {
    // 指定要修改的记录的 ID
    id: record1.id,
    valuesMap: {
      // 将要写入的数据
      fld1234567890: 'this is a text value',
      fld0987654321: 1024,
    },
  },
  {
    id: record2.id,
    valuesMap: {
      // 只传了一个 fieldId 则只修改这条记录的这个单元格，其他的单元格不进行修改
      fld1234567890: 'another text value',
    },
  },
  {
    // 不传 valuesMap 表示只校验一下有没有权限可以修改这条记录，还不知道要进行哪些值的修改
    id: record3.id,
  },
  {
    // 校验一下是否有权限修改某些字段的值，但是还不确定要修改哪个记录
    valuesMap: {
      fld1234567890: 'another text value',
      // 如果需要校验某个字段是否有权限修改，但还不知道修改的值是什么，可以传入 undefined
      fld0987654321: undefined,
    },
  },
];

const checkResult = datasheet.checkPermissionsForSetRecords(recordsToSet);
if (!checkResult.acceptable) {
  console.log(checkResult.message);
}

// 不传入任何值，也可以校验用户是否有权限修改记录，但不校验任何具体的记录和字段（也就是说即使返 acceptable 为 true，也可能有部分字段或者记录无权限修改，你可以用这个方式来显示是否小程序处于只读状态）
// 与 datasheet.checkPermissionsForSetRecord() 相等
const setUnknownRecordAndFieldsCheckResult =
  datasheet.checkPermissionsForSetRecords();

---

checkPermissionsForDeleteRecord

▸ checkPermissionsForDeleteRecord(recordId?): IPermissionResult

校验用户是否有权限删除记录

参数

Name	Type	Description
recordId?	string	要删除的记录 ID

返回值

IPermissionResult

描述

接受一个可选的 recordId 参数

如果有权限操作则返回 {acceptable: true}

如果无权限操作则返回 {acceptable: false, message: string} ，message 为显示给用户的失败原因解释

示例

// 校验用户是否有权限删除一个给定的记录
const deleteRecordCheckResult =
  datasheet.checkPermissionsForDeleteRecord(recordId);
if (!deleteRecordCheckResult.acceptable) {
  alert(deleteRecordCheckResult.message);
}

// 校验用户是否删除记录的权限，但并不校验具体的记录（示例：可以用来在 UI 控制删除选择器的可用状态）
const deleteUnknownRecordCheckResult =
  datasheet.checkPermissionsForDeleteRecord();

---

checkPermissionsForDeleteRecords

▸ checkPermissionsForDeleteRecords(recordIds?): IPermissionResult

校验用户是否有权限批量删除记录

参数

Name	Type	Description
recordIds?	string[]	要删除的记录 ID 数组

返回值

IPermissionResult

描述

接受一个可选的 recordIds 参数

如果有权限操作则返回 {acceptable: true}

如果无权限操作则返回 {acceptable: false, message: string} ，message 为显示给用户的失败原因解释

示例

// 校验用户是否有权限删除一个给定的记录
const deleteRecordsCheckResult =
  datasheet.checkPermissionsForDeleteRecords([recordId1. recordId2]);
if (!deleteRecordsCheckResult.acceptable) {
  alert(deleteRecordsCheckResult.message);
}

// 校验用户是否删除记录的权限，但并不校验具体的记录（示例：可以用来在 UI 控制删除选择器的可用状态）
// 与 checkPermissionsForDeleteRecord 一致
const deleteUnknownRecordsCheckResult =
  datasheet.checkPermissionsForDeleteRecords();

---

checkPermissionsForAddField

▸ checkPermissionsForAddField(name?, type?, property?): IPermissionResult

校验用户是否有权限新增字段

参数

Name	Type	Description
name?	string	字段名称
type?	FieldType	字段类型
property?	any	字段属性

返回值

IPermissionResult

描述

新增字段插入到最后，有关新增字段属性值写入格式，请参阅 FieldType

如果有权限操作则返回 {acceptable: true}

如果无权限操作则返回 {acceptable: false, message: string} ，message 为显示给用户的失败原因解释

示例

// 校验用户是否有权限新增一个字段
const addFieldCheckResult =
  datasheet.checkPermissionsForAddField(recordId);
if (!addFieldCheckResult.acceptable) {
  alert(addFieldCheckResult.message);
}

// 校验用户是否有增字段的权限，但并不校验具体的字段参数（示例：可以用来在 UI 控制删除选择器的可用状态）
const addUnknownFieldCheckResult =
  datasheet.checkPermissionsForAddField();

---

checkPermissionsForDeleteField

▸ checkPermissionsForDeleteField(fieldId?): { acceptable: false ; message: string } | { acceptable: boolean = true }

校验用户是否有权限删除

参数

Name	Type	Description
fieldId?	string	字段ID

返回值

{ acceptable: false ; message: string } | { acceptable: boolean = true }

描述

如果有权限操作则返回 {acceptable: true}

如果无权限操作则返回 {acceptable: false, message: string} ，message 为显示给用户的失败原因解释

示例

// 校验用户是否有权限删除一个字段
const deleteFieldCheckResult =
  datasheet.checkPermissionsForDeleteField(fieldId);
if (!deleteFieldCheckResult.acceptable) {
  alert(deleteFieldCheckResult.message);
}

// 校验用户是否有删除字段的权限，但并不校验具体的字段权限（示例：可以用来在 UI 控制删除选择器的可用状态）
const deleteUnknownFieldCheckResult =
  datasheet.checkPermissionsForDeleteField();