联系人

需要设置权限

fetchContacts在使用“fetchContacts”之前，需要先设置联系人权限。请先查看权限设置指南。

---

获取联系人

SDK 函数： fetchContacts

fetchContacts是一个按页获取用户联系人列表的函数。

签名

function fetchContacts(options: {
  size: number;
  offset: number;
  query?: {
    contains?: string;
  };
}): Promise<ContactResult>;

参数

• options · 必填

  这是获取联系人时指定的选项对象。

  • options.size · 必填

    一次获取的联系人数量。例如，传入 10 时，最多获取 10 个联系人。
  • options.offset · 必填

    要获取的联系人的起始位置。首次调用时 0需要传入该值。之后使用上一次调用返回的 nextOffset 值。

    • options.query · 必填

      这是额外的筛选选项。

      • options.query.contains · 必填

        当你只想获取姓名中包含特定字符串的联系人时使用。若不传入该值，则获取所有联系人。

属性

• openPermissionDialog

  会显示一个重新请求联系人读取权限的对话框。用户可以选择“允许”、“仅允许一次”或“不允许”之一。若选择“允许”或“仅允许一次”，则 allowed会返回，并在选择“不允许”时 denied则返回。
• getPermission

  返回联系人读取权限的当前状态。 allowed表示用户已允许联系人读取权限。 denied表示用户已拒绝联系人读取权限。 notDetermined表示从未请求过联系人读取权限。若在 Toss App 设置中联系人权限被拒绝，则 osPermissionDenied则返回。

返回值

• Promise<ContactResult>

返回包含联系人列表和分页信息的对象。

• result：获取到的联系人列表。
• nextOffset：下次调用要使用的偏移值。若没有更多联系人可获取，则 null。
• done：表示是否已获取全部联系人。若已全部获取，则 true。

联系人权限错误

错误类型： FetchContactsPermissionError

这是在联系人权限被拒绝时发生的错误。发生错误时 error instanceof FetchContactsPermissionError可以通过它来确认。

签名

class FetchContactsPermissionError extends PermissionError {
  constructor();
}

示例

获取包含特定字符串的联系人列表

这是获取联系人列表的示例。点击“检查权限”按钮来检查当前的联系人读取权限。若用户拒绝了权限或系统限制了该权限，则 FetchContactsPermissionError会返回。可以点击“请求权限”按钮来请求联系人读取权限。

js

import { fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/web-framework';

async function handleFetchContacts() {
  try {
    const response = await fetchContacts({
      size: 10,
      offset: 0,
      query: { contains: '金' },
    });

    return response;
  } catch (error) {
    if (error instanceof FetchContactsPermissionError) {
      console.log('没有联系人读取权限');
    }
    console.error('获取联系人失败：', error);
  }
}

async function handleGetPermissionForFetchContacts() {
  const permission = await fetchContacts.getPermission();
  return permission;
}

async function handleOpenPermissionDialogForFetchContacts() {
  const permission = await fetchContacts.openPermissionDialog();
  return permission;
}

React

import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function ContactsList() {
  const [contacts, setContacts] = useState<{
    result: ContactEntity[];
    nextOffset: number | null;
    done: boolean;
  }>({
    result: [],
    nextOffset: null,
    done: false,
  });

  const handlePress = async () => {
    try {
      if (contacts.done) {
        console.log('已获取所有联系人。');
        return;
      }

      const response = await fetchContacts({
        size: 10,
        offset: contacts.nextOffset ?? 0,
        query: { contains: '金' },
      });
      setContacts((prev) => ({
        result: [...prev.result, ...response.result],
        nextOffset: response.nextOffset,
        done: response.done,
      }));
    } catch (error) {
      if (error instanceof FetchContactsPermissionError) {
        console.log('没有联系人读取权限');
      }
      console.error('获取联系人失败：', error);
    }
  };

  return (
    <div>
      {contacts.result.map((contact, index) => (
        <span key={index}>
          {contact.name}: {contact.phoneNumber}
        </span>
      ))}
      <input
        type="button"
        value={contacts.done ? '已获取所有联系人。' : '获取下一个联系人'}
        disabled={contacts.done}
        onClick={handlePress}
      />
      <input
        type="button"
        value="检查权限"
        onClick={async () => {
          const permission = await fetchContacts.getPermission();
          alert(permission);
        }}
      />
      <input
        type="button"
        value="请求权限"
        onClick={async () => {
          const permission = await fetchContacts.openPermissionDialog();
          alert(permission);
        }}
      />

  );
}

React Native

import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

function ContactsList() {
  const [contacts, setContacts] = useState<{
    result: ContactEntity[];
    nextOffset: number | null;
    done: boolean;
  }>({
    result: [],
    nextOffset: null,
    done: false,
  });

  const handlePress = async () => {
    try {
      if (contacts.done) {
        console.log('已获取所有联系人。');
        return;
      }

      const response = await fetchContacts({
        size: 10,
        offset: contacts.nextOffset ?? 0,
        query: { contains: '金' },
      });
      setContacts((prev) => ({
        result: [...prev.result, ...response.result],
        nextOffset: response.nextOffset,
        done: response.done,
      }));
    } catch (error) {
      if (error instanceof FetchContactsPermissionError) {
        console.log('没有联系人读取权限');
      }
      console.error('获取联系人失败：', error);
    }
  };

  return (
    <View>
      {contacts.result.map((contact, index) => (
        <Text key={index}>
          {contact.name}: {contact.phoneNumber}
        </Text>
      ))}
      <Button
        title={contacts.done ? '已获取所有联系人。' : '获取下一个联系人'}
        disabled={contacts.done}
        onPress={handlePress}
      />
      <Button
        title="检查权限"
        onPress={async () => {
          const permission = await fetchContacts.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="请求权限"
        onPress={async () => {
          const permission = await fetchContacts.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}