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