Datasheet
model/datasheet.Datasheet
Datasheet operation
It is recommended to use if you want to operate datasheet, such as obtaining datasheet data, adding records, deleting records, etc., we recommend using the useDatasheet hook function.
If you need to obtain record data, you can use useRecord (query single record data) and useRecords (batch query record data).
addRecord: Creates a new record with the specified cell values
addRecords: Creates multiple new records with the specified cell values
setRecord: Updates cell values for a record
setRecords: Updates cell values for multiple records
deleteRecord: Delete the given record
deleteRecords: Delete the given records
addField: Creates a new field
deleteField: Delete the given field
checkPermissionsForAddRecord: Checks whether the current user has permission to create the specified record
checkPermissionsForAddRecords: Checks whether the current user has permission to create the specified records
checkPermissionsForSetRecord: Checks whether the current user has permission to perform the given record update
checkPermissionsForSetRecords: Checks whether the current user has permission to perform the given record updates
checkPermissionsForDeleteRecord: Checks whether the current user has permission to delete the specified record
checkPermissionsForDeleteRecords: Checks whether the current user has permission to delete the specified records
checkPermissionsForAddField: Checks whether the current user has permission to create the specified field
checkPermissionsForDeleteField: Checks whether the current user has permission to delete the specified field
Accessors
id
• get id(): undefined | string
The unique ID of this datasheet.
Returns
undefined | string
Example
console.log(myDatasheet.id);
// => 'dstxxxxxxx'
name
• get name(): undefined | string
The name of the Datasheet.
Returns
undefined | string
Example
console.log(myDatasheet.name);
// => 'Name'
Methods
addRecord
▸ addRecord(valuesMap?, insertPosition?): Promise<string>
Creates a new record with the specified cell values.
Parameters
| Name | Type | Description |
|---|---|---|
valuesMap | Object | object mapping fieldId to value for that field. |
insertPosition? | IInsertPosition | position to insert in view. |
Returns
Promise<string>
The returned promise will resolve to the recordId of the new record once it is persisted.
Description
Adds a new record and optionally specifies its position in the view (default at the end), returning an array of new record IDs.
An error will be thrown when the user does not have permission to perform the operation or when the cell value format check does not pass.
Refer to FieldType for cell value write formats.
Example
async function addNewRecord(valuesMap) {
if (datasheet.checkPermissionsForAddRecord(valuesMap).acceptable) {
const newRecordId = await datasheet.addRecord(valuesMap);
alert(`The newly created record ID is ${newRecordId}`);
// Next, you can select, or manipulate, the newly created records.
// ...
}
}
// The key of the parameter is the fieldId and the value is the cell value.
addNewRecord({
fld1234567980: 'this is a text value',
fld0987654321: 1024,
});
// Different types of field cell values have specific data structures that need to be passed in correctly
addNewRecord({
fld1234567890: 'this is a text value', // SingleLineText
fld0987654321: 1024, // Number
fld1234567891: 'option 1', // SingleSelect
fld1234567892: ['option 1', 'option 2'], // MultiSelect
fld1234567893: 1635513510962, // DateTime
fld1234567894: ['rec1234567'], // MagicLink (recordId)
});
addRecords
▸ addRecords(records?, insertPosition?): Promise<string[]>
Creates new records with the specified cell values.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
records | { valuesMap: { [key: string]: any; } }[] | [] | Array of objects with a fields key mapping fieldId to value for that field. |
insertPosition? | IInsertPosition | undefined | Position to insert in the view. |
Returns
Promise<string[]>
The returned promise will resolve to an array of recordIds of the new records once the new records are persisted.
Description
Add multiple records and optionally specify its position in the view (inserted at the end by default).
An error will be thrown when the user does not have permission to perform the operation or when the cell value format check does not pass.
Refer to FieldType for cell value write formats.
Example
const records = [
// Cell values should generally have format matching the output of
{
valuesMap: {
fld1234567890: 'this is a text value',
fld0987654321: 1024,
},
},
// Specifying no fields will create a new record with no cell values set
{
valuesMap: {},
},
// Different types of field cell values have specific data structures that need to be passed in correctly
{
valuesMap: {
fld1234567890: 'Cat video 2', // SingleLineText
fld0987654321: 1024, // Number
fld1234567891: 'option 1', // SingleSelect
fld1234567892: ['option 1', 'option 2'], // MultiSelect
fld1234567893: 1635513510962, // DateTime (Timestamp)
fld1234567894: ['rec1234567'], // MagicLink (recordId)
},
},
];
async function addNewRecords() {
if (datasheet.checkPermissionToAddRecords(records)) {
const recordIds = await datasheet.addRecords(records);
alert(`new records with IDs: ${recordIds}`);
// Next, you can select, or manipulate, the newly created records
// ...
}
}
setRecord
▸ setRecord(recordId, valuesMap?): Promise<void>
Updates cell values for a record.
Parameters
| Name | Type | Description |
|---|---|---|
recordId | string | the record to update. |
valuesMap | Object | key for fieldId, value for the contents of the cell object, only need to pass to modify the value, do not need to modify the key value do not need to pass. To empty a field, you need to pass key: null. |
Returns
Promise<void>
Description
Throws an error if the user does not have permission to update the given cell values in the record, or or recordId does not exist, or when the written value type does not match.
We refer to a field in a record as a cell. Refer to FieldType for cell value write formats.
If you need to modify multiple records at the same time, use the setRecords.
Example
function setRecord(recordId, valuesMap) {
if (datasheet.checkPermissionsForSetRecord(recordId, valuesMap).acceptable) {
datasheet.setRecord(recordId, valuesMap);
}
}
setRecords
▸ setRecords(records): Promise<void>
Updates cell values for records.
Parameters
| Name | Type | Description |
|---|---|---|
records | { id: string ; valuesMap: { [key: string]: any; } }[] | Specify the records be modified. |
Returns
Promise<void>
Description
Throws an error if the user does not have permission to update the given cell values in the record, or or recordId does not exist, or when the written value type does not match.
valuesMap key for fieldId, value for the contents of the cell object, only need to pass to modify the value, do not need to modify the key value do not need to pass. To empty a field, you need to pass key: null.
We refer to a field in a record as a cell. Refer to FieldType for cell value write formats.
If you only need to modify a single record, use the setRecord
Example
function setRecord(id, valuesMap) {
if (datasheet.checkPermissionsForSetRecords([{ id, valuesMap }]).acceptable) {
datasheet.setRecords([{ id, valuesMap }]);
}
}
deleteRecord
▸ deleteRecord(recordId): Promise<void>
Delete the given record.
Parameters
| Name | Type | Description |
|---|---|---|
recordId | string | the record to be deleted. |
Returns
Promise<void>
Description
Delete a record by recordId.
Throws an error if the user does not have permission to delete the given record.
Example
async function deleteRecord(recordId) {
if (datasheet.checkPermissionsForDeleteRecord(recordId).acceptable) {
await datasheet.deleteRecord(recordId);
alert('The record has been deleted');
// Record deletion has been saved to servers
}
}
deleteRecords
▸ deleteRecords(recordIds): Promise<void>
Delete the given records.
Parameters
| Name | Type | Description |
|---|---|---|
recordIds | string[] | array of recordIds. |
Returns
Promise<void>
Description
Delete the given record by recordIds.
Throws an error if the user does not have permission to delete the given record.
Example
async function deleteRecords(recordIds) {
if (datasheet.checkPermissionsForDeleteRecords(recordIds).acceptable) {
await datasheet.deleteRecords(recordIds);
alert('The records has been deleted');
// Records deletion has been saved to servers
}
}
addField
▸ addField(name, type, property): Promise<string>
Creates a new field.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | name for the field. must be case-insensitive unique |
type | FieldType | type for the field. |
property | any | property for the field. omit for fields without writable property. |
Returns
Promise<string>
Description
Refer to FieldType for supported field types, the write format for property, and other specifics for certain field types.
Throws an error if the user does not have permission to create a field, if invalid name, type or property are provided, or if creating fields of this type is not supported.
Example
function addField(name, type, property) {
if (datasheet.checkPermissionsForAddField(name, type, property).acceptable) {
datasheet.addField(recordIds);
}
}
deleteField
▸ deleteField(fieldId, conversion?): Promise<void>
Delete the given field.
Parameters
| Name | Type | Description |
|---|---|---|
fieldId | string | the field to be deleted. |
conversion? | Conversion | When deleting a field as an associated field, mark whether the associated field of the associated datasheet is deleted or converted to text, the default is Converted to a text field. |
Returns
Promise<void>
Description
Throws an error if the user does not have permission to delete a field.
Example
function deleteField(fieldId) {
if (datasheet.checkPermissionsForDeleteField(fieldId).acceptable) {
datasheet.deleteField(fieldId);
}
}
checkPermissionsForAddRecord
▸ checkPermissionsForAddRecord(valuesMap?): IPermissionResult
Checks whether the current user has permission to create the specified record.
Parameters
| Name | Type | Description |
|---|---|---|
valuesMap? | Object | object mapping fieldId to value for that field. |
Returns
Description
Accepts partial input, in the same format as addRecord. The more information provided, the more accurate the permissions check will be.
The format of valuesMap is the same as when writing to cells. For cell value writing format, refer to FieldType.
Returns {acceptable: true} if the current user can create the specified record.
Returns {acceptable: false, message: string} if no permission to operate, message may be used to display an error message to the user.
Example
// Check if user can create a specific record, when you already know what
// fields/cell values will be set for the record.
const setRecordCheckResult = datasheet.checkPermissionsForAddRecord({
'fld1234567890': 'Advertising campaign',
'fld0987654321': 1024,
});
if (!setRecordCheckResult.acceptable) {
alert(setRecordCheckResult.message);
}
// Check if user could potentially create a record.
// Use when you don't know the specific fields/cell values yet (for example,
// to show or hide UI controls that let you start creating a record.)
const addUnknownRecordCheckResult =
datasheet.checkPermissionsForAddRecord();
checkPermissionsForAddRecords
▸ checkPermissionsForAddRecords(records?): IPermissionResult
Checks whether the current user has permission to create the specified records.
Parameters
| Name | Type | Description |
|---|---|---|
records? | { valuesMap: { [key: string]: any; } }[] | Array of objects mapping fieldId to value for that field. |
Returns
Description
array of objects mapping fieldId to value for that field.
Accepts partial input, in the same format as addRecords. The more information provided, the more accurate the permissions check will be.
The format of records is the same as when writing to cells. For cell value writing format, refer to FieldType.
Returns {acceptable: true} if the current user can update the specified record.
Returns {acceptable: false, message: string} if no permission to operate, message may be used to display an error message to the user.
Example
// Check if user can update a specific records, when you already know what
// fields/cell values will be set for the record.
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);
}
// Check if user could potentially create a record.
// Use when you don't know the specific fields/cell values yet (for example,
// to show or hide UI controls that let you start creating a record.)
// same as checkPermissionsForSetRecord
const addUnknownRecordCheckResult =
datasheet.checkPermissionsForAddRecords();
checkPermissionsForSetRecord
▸ checkPermissionsForSetRecord(recordId?, valuesMap?): IPermissionResult
Checks whether the current user has permission to perform the given record update.
Parameters
| Name | Type | Description |
|---|---|---|
recordId? | string | the record to update |
valuesMap? | Object | specified as object mapping fieldId to value for that field |
Returns
Description
This method performs permission and value legality checks based on the level of detail of the value passed in. Passing in valuesMap will check the legality of cell writes and column permissions, and passing in recordId will check the existence of records and modification permissions.
The format of records is the same as when writing to cells. For cell value writing format, refer to FieldType.
Returns {acceptable: true} if the current user can update the specified record.
Returns {acceptable: false, message: string} if no permission to operate, message may be used to display an error message to the user.
Example
// Check if user can update specific fields for a specific record
const setRecordCheckResult =
datasheet.checkPermissionsForSetRecord('rec1234567', {
'fld1234567890': 'this is a text value',
'fld0987654321': 1024,
});
if (!setRecordCheckResult.acceptable) {
alert(setRecordCheckResult.message);
}
// Checks if a user has permission to modify a record, but does not check if the specific value can be modified
const setUnknownFieldsCheckResult =
datasheet.checkPermissionsForSetRecord('rec1234567');
// Check whether the user has permission to modify the corresponding field, do not care about the specific record
const setUnknownRecordCheckResult =
datasheet.checkPermissionsForSetRecord(undefined, {
'fld1234567890': 'this is a text value',
// You can also choose not to pass in a specific value and use undefined instead, which will not perform a value type check
'fld0987654321': undefined,
});
// Check if user could perform updates within the datasheet, without knowing the
// specific record or fields that will be updated yet (e.g., to render your
// extension in "read only" mode)
const setUnknownRecordAndFieldsCheckResult =
datasheet.checkPermissionsForSetRecord();
checkPermissionsForSetRecords
▸ checkPermissionsForSetRecords(records): IPermissionResult
Checks whether the current user has permission to perform the given record updates.
Parameters
| Name | Type | Description |
|---|---|---|
records | { id?: string ; valuesMap?: { [key: string]: any; } }[] | Array of objects containing recordId and fields/cellValues to update for that records. |
Returns
Description
This method performs permission and value legality checks based on the level of detail of the value passed in. Passing in valuesMap will check the legality of cell writes and column permissions, and passing in recordId will check the existence of records and modification permissions.
The format of records is the same as when writing to cells. For cell value writing format, refer to FieldType.
Returns {acceptable: true} if the current user can update the specified records.
Returns {acceptable: false, message: string} if no permission to operate, message may be used to display an error message to the user.
Example
const recordsToSet = [
{
// Validating a complete record update
id: record1.id,
valuesMap: {
// fields can be specified by ID
fld1234567890: 'this is a text value',
fld0987654321: 1024,
},
},
{
id: record2.id,
valuesMap: {
// If only a fieldId is passed, only the cell of this record will be modified, and the other cells will not be modified
fld1234567890: 'another text value',
},
},
{
// Validating an update to a specific record, not knowing what fields will be updated
id: record3.id,
},
{
// Validating an update to specific cell values, not knowing what record will be updated
valuesMap: {
fld1234567890: 'another text value',
// You can use undefined if you know you're going to update a field, but don't know the new cell value yet.
fld0987654321: undefined,
},
},
];
const checkResult = datasheet.checkPermissionsForSetRecords(recordsToSet);
if (!checkResult.acceptable) {
console.log(checkResult.message);
}
// Check if user could potentially update records.
// Equivalent to datasheet.checkPermissionsForSetRecord()
const setUnknownRecordAndFieldsCheckResult =
datasheet.checkPermissionsForSetRecords();
checkPermissionsForDeleteRecord
▸ checkPermissionsForDeleteRecord(recordId?): IPermissionResult
Checks whether the current user has permission to delete the specified record.
Parameters
| Name | Type | Description |
|---|---|---|
recordId? | string | the record to be deleted. |
Returns
Description
Accepts optional input.
Returns {acceptable: true} if the current user can delete the specified record.
Returns {acceptable: false, message: string} if no permission to operate, message may be used to display an error message to the user.
Example
// Check if user can delete a specific record
const deleteRecordCheckResult =
datasheet.checkPermissionsForDeleteRecord(recordId);
if (!deleteRecordCheckResult.acceptable) {
alert(deleteRecordCheckResult.message);
}
// Check if user could potentially delete a record.
// Use when you don't know the specific record you want to delete yet (for
// example, to show/hide UI controls that let you select a record to delete).
const deleteUnknownRecordCheckResult =
datasheet.checkPermissionsForDeleteRecord();
checkPermissionsForDeleteRecords
▸ checkPermissionsForDeleteRecords(recordIds?): IPermissionResult
Checks whether the current user has permission to delete the specified records.
Parameters
| Name | Type | Description |
|---|---|---|
recordIds? | string[] | the records to be deleted. |
Returns
Description
Accepts optional input.
Returns {acceptable: true} if the current user can delete the specified records.
Returns {acceptable: false, message: string} if no permission to operate, message may be used to display an error message to the user.
Example
// Check if user can delete specific records
const deleteRecordsCheckResult =
datasheet.checkPermissionsForDeleteRecords([recordId1. recordId2]);
if (!deleteRecordsCheckResult.acceptable) {
alert(deleteRecordsCheckResult.message);
}
// Check if user could potentially delete records.
// Use when you don't know the specific records you want to delete yet (for
// example, to show/hide UI controls that let you select records to delete).
// Equivalent to datasheet.checkPermissionsForDeleteRecord
const deleteUnknownRecordsCheckResult =
datasheet.checkPermissionsForDeleteRecords();
checkPermissionsForAddField
▸ checkPermissionsForAddField(name?, type?, property?): IPermissionResult
Checks whether the current user has permission to create a field.
Parameters
| Name | Type | Description |
|---|---|---|
name? | string | name for the field. must be case-insensitive unique. |
type? | FieldType | type for the field. |
property? | any | property for the field. omit for fields without writable property. |
Returns
Description
Accepts partial input, in the same format as addField.
Returns {acceptable: true} if the current user can create the specified field.
Returns {acceptable: false, message: string} if no permission to operate, message may be used to display an error message to the user.
Example
// Checks whether the current user has permission to create a field
const addFieldCheckResult =
datasheet.checkPermissionsForAddField(recordId);
if (!addFieldCheckResult.acceptable) {
alert(addFieldCheckResult.message);
}
// Check if user could potentially create a field.
// Use when you don't know the specific a field you want to create yet (for example,
// to show or hide UI controls that let you start creating a field.)
const addUnknownFieldCheckResult =
datasheet.checkPermissionsForAddField();
checkPermissionsForDeleteField
▸ checkPermissionsForDeleteField(fieldId?): { acceptable: false ; message: string } | { acceptable: boolean = true }
Checks whether the current user has permission to delete a field.
Parameters
| Name | Type | Description |
|---|---|---|
fieldId? | string | the field to be deleted |
Returns
{ acceptable: false ; message: string } | { acceptable: boolean = true }
Description
Returns {acceptable: true} if the current user can delete the specified field.
Returns {acceptable: false, message: string} if no permission to operate, message may be used to display an error message to the user.
Example
// Checks whether the current user has permission to delete a field.
const deleteFieldCheckResult =
datasheet.checkPermissionsForDeleteField(fieldId);
if (!deleteFieldCheckResult.acceptable) {
alert(deleteFieldCheckResult.message);
}
// Check if user could potentially delete a field.
// Use when you don't know the specific a field you want to delete yet (for
// example, to show/hide UI controls that let you select a field to delete).
const deleteUnknownFieldCheckResult =
datasheet.checkPermissionsForDeleteField();