1# @ohos.data.dataShareResultSet (数据共享结果集)(系统接口) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @woodenarow--> 5<!--Designer: @woodenarow; @xuelei3--> 6<!--Tester: @chenwan188; @logic42--> 7<!--Adviser: @ge-yafang--> 8 9**结果集(DataShareResultSet)** 可提供访问由查询数据库生成的结果集的相关方法，根据提供的行数，查询相应的值，也可查询指定数据类型的值。 10 11> **说明：** 12> 13> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 15> - 本模块接口为系统接口。 16> 17> - 本模块接口仅可在Stage模型下使用。 18> 19> - 数据共享结果集在全系统最多同时存在32个，使用完及时释放。 20 21## 导入模块 22 23```ts 24import { DataShareResultSet } from '@kit.ArkData'; 25``` 26 27## 使用说明 28 29需要通过调用[query](js-apis-data-dataShare-sys.md#query)接口获取DataShareResultSet对象。 30 31```ts 32import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 33import { DataShareResultSet, dataShare, dataSharePredicates } from '@kit.ArkData'; 34import { BusinessError } from '@kit.BasicServicesKit'; 35 36export default class EntryAbility extends UIAbility { 37 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 38 let dataShareHelper: dataShare.DataShareHelper | undefined = undefined; 39 let uri = ("datashare:///com.samples.datasharetest.DataShare"); 40 let context = this.context; 41 dataShare.createDataShareHelper(context, uri, (err:BusinessError, data:dataShare.DataShareHelper) => { 42 if (err != undefined) { 43 console.error("createDataShareHelper fail, error message : " + err); 44 } else { 45 console.info("createDataShareHelper end, data : " + data); 46 dataShareHelper = data; 47 } 48 let columns = ["*"]; 49 let da = new dataSharePredicates.DataSharePredicates(); 50 let resultSet: DataShareResultSet | undefined = undefined; 51 da.equalTo("name0", "ZhangSan"); 52 if (dataShareHelper != undefined) { 53 (dataShareHelper as dataShare.DataShareHelper).query(uri, da, columns).then((data: DataShareResultSet) => { 54 console.info("query end, data : " + data); 55 resultSet = data; 56 }).catch((err: BusinessError) => { 57 console.error("query fail, error message : " + err); 58 }); 59 } 60 }); 61 }; 62}; 63``` 64 65## DataShareResultSet 66提供通过查询数据库生成的结果集的相关访问方法。 67 68列或键名称作为字符串数组返回，其中字符串的顺序与结果集中的列或键的顺序相同。 69 70### 属性 71 72**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 73 74| 名称 | 类型 | 必填 | 说明 | 75| ----------- | ------------- | ---- | ------------------------ | 76| columnNames | Array<string> | 是 | 结果集中所有列的名称。 | 77| columnCount | number | 是 | 结果集中的列数。 | 78| rowCount | number | 是 | 结果集中的行数。 | 79| isClosed | boolean | 是 | 标识当前结果集是否关闭。如果结果集已关闭，则为true；否则为false。 | 80 81### goToFirstRow 82 83goToFirstRow(): boolean 84 85转到结果集的第一行。 86 87**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 88 89**返回值：** 90 91| 类型 | 说明 | 92| :------ | --------------------------------------------- | 93| boolean | 如果成功移动结果集，则为true；否则返回false。 | 94 95**示例：** 96 97```ts 98// resultSet需依照本页的使用说明进行创建。 99if (resultSet != undefined) { 100 let isGoToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 101 console.info('resultSet.goToFirstRow: ' + isGoToFirstRow); 102} 103``` 104 105### goToLastRow 106 107goToLastRow(): boolean 108 109转到结果集的最后一行。 110 111**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 112 113**返回值：** 114 115| 类型 | 说明 | 116| -------- | -------- | 117| boolean | 如果成功移动结果集，则为true；否则返回false。 | 118 119**示例：** 120 121```ts 122if (resultSet != undefined) { 123 let isGoToLastRow = (resultSet as DataShareResultSet).goToLastRow(); 124 console.info('resultSet.goToLastRow: ' + isGoToLastRow); 125} 126``` 127 128### goToNextRow 129 130goToNextRow(): boolean 131 132转到结果集的下一行。 133 134**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 135 136**返回值：** 137 138| 类型 | 说明 | 139| ------- | --------------------------------------------- | 140| boolean | 如果成功移动结果集，则为true；否则返回false。 | 141 142**示例：** 143 144```ts 145if (resultSet != undefined) { 146 let isGoToNextRow = (resultSet as DataShareResultSet).goToNextRow(); 147 console.info('resultSet.goToNextRow: ' + isGoToNextRow); 148} 149``` 150 151### goToPreviousRow 152 153goToPreviousRow(): boolean 154 155转到结果集的上一行。 156 157**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 158 159**返回值：** 160 161| 类型 | 说明 | 162| ------- | --------------------------------------------- | 163| boolean | 如果成功移动结果集，则为true；否则返回false。 | 164 165**示例：** 166 167```ts 168if (resultSet != undefined) { 169 let isGoToPreviousRow = (resultSet as DataShareResultSet).goToPreviousRow(); 170 console.info('resultSet.goToPreviousRow: ' + isGoToPreviousRow); 171} 172``` 173 174### goTo 175 176goTo(offset: number): boolean 177 178相对于当前位置向前或向后移动指定行数。 179 180**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 181 182**参数：** 183 184| **参数名** | **类型** | **必填** | 说明 | 185| ---------- | -------- | -------- | ------------------------------------------------------------ | 186| offset | number | 是 | 表示相对于当前位置的偏移量。offset为负值表示向前偏移，正值则表示向后偏移。 | 187 188**返回值：** 189 190| 类型 | 说明 | 191| ------- | --------------------------------------------- | 192| boolean | 如果成功移动结果集，则为true；否则返回false。 | 193 194**示例：** 195 196```ts 197let goToNum = 1; 198if (resultSet != undefined) { 199 let isGoTo = (resultSet as DataShareResultSet).goTo(goToNum); 200 console.info('resultSet.goTo: ' + isGoTo); 201} 202``` 203 204### goToRow 205 206goToRow(position: number): boolean 207 208转到结果集的指定行。 209 210**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 211 212**参数：** 213 214| **参数名** | **类型** | **必填** | 说明 | 215| ---------- | -------- | -------- | --------------------------------------- | 216| position | number | 是 | 表示要移动到的指定位置，从 0 开始。 | 217 218**返回值：** 219 220| 类型 | 说明 | 221| ------- | --------------------------------------------- | 222| boolean | 如果成功移动结果集，则为true；否则返回false。 | 223 224**示例：** 225 226```ts 227let goToRowNum = 2; 228if (resultSet != undefined) { 229 let isGoToRow = (resultSet as DataShareResultSet).goToRow(goToRowNum); 230 console.info('resultSet.goToRow: ' + isGoToRow); 231} 232``` 233 234### getBlob 235 236getBlob(columnIndex: number): Uint8Array 237 238以字节数组的形式获取当前行中指定列的值。 239 240如果当前行中指定的列或键的值为空，或者指定的列或键不是Blob类型，则使用方需要确定是否抛出此异常。 241 242**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 243 244**参数：** 245 246| **参数名** | **类型** | **必填** | 说明 | 247| ----------- | -------- | -------- | ----------------------- | 248| columnIndex | number | 是 | 指定的列索引，从0开始。 | 249 250**返回值：** 251 252| 类型 | 说明 | 253| ---------- | -------------------------------- | 254| Uint8Array | 以字节数组的形式返回指定列的值。 | 255 256**示例：** 257 258```ts 259let columnIndex = 1; 260if (resultSet != undefined) { 261 let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 262 if (!goToFirstRow) { 263 console.error("failed to go to first row"); 264 } else { 265 let getBlob = (resultSet as DataShareResultSet).getBlob(columnIndex); 266 console.info('resultSet.getBlob: ' + getBlob); 267 } 268} 269``` 270 271### getString 272 273getString(columnIndex: number): string 274 275以字符串形式获取当前行中指定列的值。 276 277如果当前行中指定的列或键的值为空，或者指定的列或键不是string类型，则使用方需要确定是否抛出此异常。 278 279**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 280 281**参数：** 282 283| **参数名** | **类型** | **必填** | 说明 | 284| ----------- | -------- | -------- | ----------------------- | 285| columnIndex | number | 是 | 指定的列索引，从0开始。 | 286 287**返回值：** 288 289| 类型 | 说明 | 290| ------ | ---------------------------- | 291| string | 以字符串形式返回指定列的值。 | 292 293**示例：** 294 295```ts 296let columnIndex = 1; 297if (resultSet != undefined) { 298 let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 299 let getString = (resultSet as DataShareResultSet).getString(columnIndex); 300 console.info('resultSet.getString: ' + getString); 301} 302``` 303 304### getLong 305 306getLong(columnIndex: number): number 307 308以长整数值形式获取当前行中指定列的值。 309 310如果当前行中指定的列或键的值为空，或者指定的列或键不是long类型，则使用方需要确定是否抛出此异常。 311 312**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 313 314**参数：** 315 316| **参数名** | **类型** | **必填** | 说明 | 317| ----------- | -------- | -------- | ----------------------- | 318| columnIndex | number | 是 | 指定的列索引，从0开始。 | 319 320**返回值：** 321 322| 类型 | 说明 | 323| ------ | -------------------------- | 324| number | 以长整数值形式返回指定列的值。 | 325 326**示例：** 327 328```ts 329let columnIndex = 1; 330if (resultSet != undefined) { 331 let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 332 let getLong = (resultSet as DataShareResultSet).getLong(columnIndex); 333 console.info('resultSet.getLong: ' + getLong); 334} 335``` 336 337### getDouble 338 339getDouble(columnIndex: number): number 340 341以值类型为双浮点数形式获取当前行中指定列的值。 342 343如果当前行中指定的列或键的值为空，或者指定的列或键不是double类型，则使用方需要确定是否抛出此异常。 344 345**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 346 347**参数：** 348 349| **参数名** | **类型** | **必填** | 说明 | 350| ----------- | -------- | -------- | ----------------------- | 351| columnIndex | number | 是 | 指定的列索引，从0开始。 | 352 353**返回值：** 354 355| 类型 | 说明 | 356| ------ | ---------------------------- | 357| number | 值类型为双浮点数形式返回指定列的值。 | 358 359**示例：** 360 361```ts 362let columnIndex = 1; 363if (resultSet != undefined) { 364 let goToFirstRow = (resultSet as DataShareResultSet).goToFirstRow(); 365 let getDouble = (resultSet as DataShareResultSet).getDouble(columnIndex); 366 console.info('resultSet.getDouble: ' + getDouble); 367} 368``` 369 370### close 371 372close(): void 373 374关闭结果集。 375 376对结果集调用此方法将释放其所有资源并使其无效。 377 378**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 379 380**示例：** 381 382```ts 383if (resultSet != undefined) { 384 (resultSet as DataShareResultSet).close(); 385} 386``` 387 388### getColumnIndex 389 390getColumnIndex(columnName: string): number 391 392根据指定的列名获取列索引。 393 394列名作为输入参数传递。 395 396**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 397 398**参数：** 399 400| **参数名** | **类型** | **必填** | 说明 | 401| ---------- | -------- | -------- | -------------------------- | 402| columnName | string | 是 | 表示结果集中指定列的名称。 | 403 404**返回值：** 405 406| 类型 | 说明 | 407| ------ | ------------------ | 408| number | 返回指定列的索引。 | 409 410**示例：** 411 412```ts 413let ColumnName = "name"; 414if (resultSet != undefined) { 415 let getColumnIndex = (resultSet as DataShareResultSet).getColumnIndex(ColumnName); 416 console.info('resultSet.getColumnIndex: ' + getColumnIndex); 417} 418``` 419 420### getColumnName 421 422getColumnName(columnIndex: number): string 423 424根据指定的列索引获取列名。 425 426列索引作为输入参数传递。 427 428**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 429 430**参数：** 431 432| **参数名** | **类型** | **必填** | 说明 | 433| ----------- | -------- | -------- | -------------------------- | 434| columnIndex | number | 是 | 表示结果集中指定列的索引。 | 435 436**返回值：** 437 438| 类型 | 说明 | 439| ------ | ------------------ | 440| string | 返回指定列的名称。 | 441 442**示例：** 443 444```ts 445let columnIndex = 1; 446if (resultSet != undefined) { 447 let getColumnName = (resultSet as DataShareResultSet).getColumnName(columnIndex); 448 console.info('resultSet.getColumnName: ' + getColumnName); 449} 450``` 451 452### getDataType 453 454getDataType(columnIndex: number): DataType 455 456指定列索引获取该列的数据类型。 457 458如果当前行中指定的列或键的值为空，或者指定的列或键不是DataType类型，则使用方需要确定是否抛出此异常。 459 460**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 461 462**参数：** 463 464| **参数名** | **类型** | **必填** | 说明 | 465| ----------- | -------- | -------- | -------------------------- | 466| columnIndex | number | 是 | 表示结果集中指定列的索引。 | 467 468**返回值：** 469 470| 类型 | 说明 | 471| --------------------- | ------------------ | 472| [DataType](#datatype) | 返回指定列的类型。 | 473 474**示例：** 475 476```ts 477let columnIndex = 1; 478if (resultSet != undefined) { 479 let getDataType = (resultSet as DataShareResultSet).getDataType(columnIndex); 480 console.info('resultSet.getDataType: ' + getDataType); 481} 482``` 483 484## DataType 485 486数据类型枚举。 487 488**系统能力：** SystemCapability.DistributedDataManager.DataShare.Core 489 490| 名称 | 值 | 说明 | 491| ----------- | ------ | -------------------- | 492| TYPE_NULL | 0 | 表示值类型为空。 | 493| TYPE_LONG | 1 | 表示值类型为长整数值。 | 494| TYPE_DOUBLE | 2 | 表示值类型为双浮点数。 | 495| TYPE_STRING | 3 | 表示值类型为字符串。 | 496| TYPE_BLOB | 4 | 表示值类型为字节数组。 |