Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rt2zz/react-native-addressbook
React Native AddressBook
https://github.com/rt2zz/react-native-addressbook
Last synced: 6 days ago
JSON representation
React Native AddressBook
- Host: GitHub
- URL: https://github.com/rt2zz/react-native-addressbook
- Owner: rt2zz
- Created: 2015-04-27T05:20:29.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-04-16T23:25:09.000Z (over 7 years ago)
- Last Synced: 2024-09-15T18:15:30.099Z (3 months ago)
- Language: Objective-C
- Size: 57.6 KB
- Stars: 82
- Watchers: 6
- Forks: 13
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-react-native - react-native-addressbook ★81 - AddressBook module for react-native (Components / System)
- awesome-react-native - react-native-addressbook ★81 - AddressBook module for react-native (Components / System)
- awesome-react-native - react-native-addressbook ★81 - AddressBook module for react-native (Components / System)
- awesome-react-native - react-native-addressbook ★81 - AddressBook module for react-native (Components / System)
- awesome-react-native-ui - react-native-addressbook ★65 - AddressBook module for react-native (Components / System)
README
# React Native AddressBook
**NOTE** Future development will occur at [react-native-contacts](https://github.com/rt2zz/react-native-contacts). Migration is trivial (rename `getContacts` -> `getAll`)
## API
`getContacts` (callback) - returns *all* contacts as an array of objects
`addContact` (contact, callback) - adds a contact to the AddressBook.
`updateContact` (contact, callback) - where contact is an object with a valid recordID
`deleteContact` (contact, callback) - where contact is an object with a valid recordID
####Permissions Methods (optional)
`checkPermission` (callback) - checks permission to use AddressBook.
`requestPermission` (callback) - request permission to use AddressBook.
## Usage Example
```js
var AddressBook = require('react-native-addressbook')
AddressBook.getContacts( (err, contacts) => {
if(err && err.type === 'permissionDenied'){
// x.x
}
else{
console.log(contacts)
}
})
```
## Example Contact Record
```js
{
recordID: 1,
lastName: "Jung",
firstName: "Carl",
middleName: "",
emailAddresses: [{
label: "work",
email: "[email protected]",
}],
phoneNumbers: [{
label: "mobile",
number: "(555) 555-5555",
}],
thumbnailPath: "",
}
```
## Adding Contacts
Currently all fields from the contact record except for thumbnailPath are supported for writing
```js
var newPerson = {
lastName: "Nietzsche",
firstName: "Friedrich",
emailAddresses: [{
label: "work",
email: "[email protected]",
}],
}
AddressBook.addContact(newPerson, (err) => { /*...*/ })
```
## Updating and Deleting Contacts
```js
//contrived example
AddressBook.getContacts( (err, contacts) => {
//update the first record
let someRecord = contacts[0]
someRecord.emailAddresses.push({
label: "junk",
email: "[email protected]",
})
AddressBook.updateContact(someRecord, (err) => { /*...*/ })
//delete the second record
AddressBook.deleteContact(contacts[1], (err) => { /*...*/ })
})
```
Update and delete reference contacts by their recordID (as returned by the OS in getContacts). Apple does not guarantee the recordID will not change, e.g. it may be reassigned during a phone migration. Consequently you should always grab a fresh contact list with `getContacts` before performing update and delete operations.
You can also delete a record using only it's recordID like follows: `AddressBook.deleteContact({recordID: 1}, (err) => {})}`
##Permissions
Permissions will automatically be checked and if needed requested upon calling getContacts. If you need more granular control you can using the checkPermission and requestPermission methods as follows:
```js
AddressBook.checkPermission( (err, permission) => {
// AddressBook.PERMISSION_AUTHORIZED || AddressBook.PERMISSION_UNDEFINED || AddressBook.PERMISSION_DENIED
if(permission === 'undefined'){
AddressBook.requestPermission( (err, permission) => {
// ...
})
}
if(permission === 'authorized'){
// yay!
}
if(permission === 'denied'){
// x.x
}
})
```
## Getting started
1. `npm install react-native-addressbook`
2. In XCode, in the project navigator, right click `Libraries` ➜ `Add Files to [your project's name]`
3. add `./node_modules/react-native-addressbook/RCTAddressBook.xcodeproj`
4. In the XCode project navigator, select your project, select the `Build Phases` tab and in the `Link Binary With Libraries` section add **libRCTAddressBook.a**
## Todo
- [x] `checkPermission` & `requestPermission`
- [x] `getContacts` (get all contacts)
- [x] `addContact`
- [x] Update and Delete methods
- [ ] `getContacts` options (a la camera roll's getPhotos)
- [x] Automatic permission check & request in `getContacts`
- [ ] Contact Groups support
## Credits
Thanks to @mattotodd whose [RCTAddressBook](https://github.com/mattotodd/react-native-addressbook-ios) this is largely derived from.