Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝Write doc of contact module #348

Merged
merged 1 commit into from
Jul 17, 2022
+168 −318
Merged

📝Write doc of contact module #348

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
317 changes: 52 additions & 265 deletions docs/references/contact.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,53 +2,53 @@
title: Contact
---

## Classes
> 所有的微信联系人（朋友）都会被封装成一个`Contact`联系人对象。

所有的微信联系人（朋友）都会被封装成一个`Contact`联系人对象。
::: wechaty.user.contact.Contact.__init__

::: wechaty.user.contact.Contact.get_id

## Contact
::: wechaty.user.contact.Contact.load

所有的微信联系人（朋友）都会被封装成一个`Contact`联系人对象。示例:
[示例/Contact-Bot](https://github.com/wechaty/python-wechaty-getting-started/blob/master/examples/basic/contact-bot.py)
::: wechaty.user.contact.Contact.find
### 示例代码
```python
import asyncio
from wechaty import Wechaty, Contact
from wechaty_puppet import ContactQueryFilter

**类型**: 全局**属性**
class MyBot(Wechaty):

| **属性名** | 类型 | **描述** |
| :--- | :--- | :--- |
| id | `str` | 获取联系人对象的id. 此函数取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table) |
async def on_login(self, contact: Contact) -> None:
contact = await self.Contact.find(ContactQueryFilter(name="lijiarui"))
contact = await self.Contact.find(ContactQueryFilter(alias="ruirui"))

* [Contact](contact.md#Contact)
* _实例方法_
* [.say\(textOrContactOrFileOrUrl\)](contact.md#Contact+say) ⇒ `Optional[Message]`
* [.name](contact.md#Contact+name)⇒ `str`
* [.alias\(new\_alias\)](contact.md#Contact+alias) ⇒ `Union[None, str]`
* [.is_friend\(\)](contact.md#Contact+friend) ⇒ `bool`
* [.is_offical\(\)](contact.md#Contact+offical) ⇒ `bool`
* [.is_personal\(\)](contact.md#Contact+personal) ⇒ `bool`
* [.type\(\)](contact.md#Contact+type) ⇒ `ContactType.CONTACT_TYPE_UNSPECIFIED` \| `ContactType.CONTACT_TYPE_PERSONAL` \| `ContactType.CONTACT_TYPE_OFFICIAL` \| `ContactType.CONTACT_TYPE_CORPORATION`
* [.gender\(\)](contact.md#Contact+gender) ⇒ `ContactGender.CONTACT_GENDER_UNSPECIFIED` \| `ContactGender.CONTACT_GENDER_MALE` \| `ContactGender.CONTACT_GENDER_FEMALE`
* [.province\(\)](contact.md#Contact+province) ⇒ `Optional[str]`
* [.city\(\)](contact.md#Contact+city) ⇒ `Optional[str]`
* [.avatar\(\)](contact.md#Contact+avatar) ⇒ `FileBox`
* [.sync\(\)](contact.md#Contact+sync) ⇒ `None`
* [.is_self\(\)](contact.md#Contact+self) ⇒ `bool`
* _静态方法_
* [.find\(query\)](contact.md#Contact.find) ⇒ `Optional[Contact]`
* [.find_all\(\[queryArg\]\)](contact.md#Contact.findAll) ⇒ `List[Contact]`
asyncio.run(MyBot().start())
```

### async def say\(self, message: `Union[str, Message, FileBox, Contact, UrlLink]`\) ⇒ `Optional[Message]`
::: wechaty.user.contact.Contact.find_all
### 示例代码
```python
import asyncio
from wechaty import Wechaty, Contact
from wechaty_puppet import ContactQueryFilter

> 提示: 此功能取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
class MyBot(Wechaty):

**类型**: [`Contact`](contact.md#Contact)的实例方法
async def on_login(self, contact: Contact) -> None:
contact = await self.Contact.find_all() # 获取一个列表, 里面包含了Bot所有的联系人
contact = await self.Contact.find_all(ContactQueryFilter(name="lijiarui")) # 获取一个包含所有名字为lijiarui的联系人的列表
contact = await self.Contact.find_all(ContactQueryFilter(alias="ruirui")) # 获取一个包含所有别名(备注)为ruirui的联系人的列表

asyncio.run(MyBot().start())
```

| 参数 | 类型 | 描述 |
| :--- | :--- | :--- |
| 文本, 联系人对象, 文件对象, 链接或者小程序对象 | `str` \| [`Contact`](contact.md#Contact) \| `FileBox` \| `UrlLink` \| `MiniProgram` | 发送文本、联系人名片、文件或链接到目标联系人。 您可以使用 [FileBox](https://github.com/wechaty/python-wechaty-puppet/tree/master/src/wechaty_puppet/file_box) 类来发送文件。 |

#### 示例
::: wechaty.user.contact.Contact.ready


::: wechaty.user.contact.Contact.say
### 示例代码
```python
import asyncio
from wechaty import Wechaty, Contact, FileBox, UrlLink
Expand Down Expand Up @@ -100,129 +100,29 @@ class MyBot(Wechaty):
asyncio.run(MyBot().start())
```

### `@property` def name\(self\) ⇒ `str`

获取联系人对象的名字

**类型**: [`Contact`](contact.md#Contact) 的实例方法

**示例:**

```python
name: str = contact.name
```

### async def alias\(self, `new_alias: Optional[str]` = None\) ⇒ `Union[None, str]`

为一个联系人获取 / 设置 / 删除别名

> 测试表明如果过于频繁地设置别名会导致失败\(每分钟60次\).

**类型**: [`Contact`](contact.md#Contact)对象的实例方法

**返回值**: Union\[None, str\]

| 参数 | 类型 |
| :--- | :--- |
| newAlias | Optional\[str\] |

**示例:**
_\(**获取**联系人对象的别名\(备注\)_
::: wechaty.user.contact.Contact.name

::: wechaty.user.contact.Contact.alias
### 示例代码
```python
alias = await contact.alias()
if alias is None or alias == "":
print('您还没有为联系人设置任何别名' + contact.name)
else:
print('您已经为联系人设置了别名 ' + contact.name + ':' + alias)
```

**示例**

_\(为一个联系人**设置**别名\(备注\)\)_

```python
try:
await contact.alias('lijiarui')
print(f"改变{contact.name}的备注成功!")
except Exception:
print(f"改变{contact.name}的备注失败~")
```

**示例**

_\(**删除**给联系人设置的别名\(备注\)\)_

```python
try:
oldAlias = await contact.alias(None)
print(f"成功删除{contact.name}的备注!")
print(f"旧的备注名为{oldAlias}")
except Exception:
print(f"删除{contact.name}的备注失败!")
```

### def is_friend\(self\) ⇒ `Optional[bool]`

检查这个联系人对象是否是自己的朋友

> 注意: 此功能取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)

**类型**: [`Contact`](contact.md#Contact) 的实例方法

**返回值**: `Optional[bool]` - 如果是自己的朋友则返回True, 不是则返回False, Unknown(未知)则返回None.

**示例**

```python
isFriend = contact.is_friend()
print(isFriend)
```

### def is_offical\(self\) ⇒ `bool`

检查这个联系人对象是否是公众号

> 注意: 此功能取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
::: wechaty.user.contact.Contact.is_friend

**类型**: [`Contact`](contact.md#Contact) 的实例方法
::: wechaty.user.contact.Contact.is_offical

**返回值**: `Optional[bool]` - 如果是公众号则返回True, 不是则返回False, Unknown(未知)则返回None.

**示例**

```python
isFriend = contact.is_offical()
print(isFriend)
```

### def is_personal\(self) ⇒ `bool`

检查这个联系人对象是否是个人账号

> 注意: 此功能取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)

**类型**: [`Contact`](contact.md#Contact) 的实例方法

**返回值**: `Optional[bool]` - 如果是个人账号则返回True, 不是则返回False, Unknown(未知)则返回None.

**示例**

```python
isFriend = contact.is_personal()
print(isFriend)
```

### def type\(self\) ⇒ `ContactType.CONTACT_TYPE_UNSPECIFIED` \| `ContactType.CONTACT_TYPE_PERSONAL` \| `ContactType.CONTACT_TYPE_OFFICIAL` \| `CONTACT_TYPE_CORPORATION`

返回联系人的类型
::: wechaty.user.contact.Contact.is_personal

::: wechaty.user.contact.Contact.type
### 示例代码
> 注意: ContactType是个枚举类型.

**类型**: [`Contact`](contact.md#Contact)的实例方法

**示例**

```python
import asyncio
from wechaty import Wechaty, Message, ContactType
Expand All @@ -236,16 +136,12 @@ class MyBot(Wechaty):
asyncio.run(MyBot().start())
```

### def gender(self)\(\) ⇒ `ContactGender.CONTACT_GENDER_UNSPECIFIED` \| `ContactGender.CONTACT_GENDER_MALE` \| `ContactGender.CONTACT_GENDER_FEMALE`

获取联系人的性别
::: wechaty.user.contact.Contact.star

::: wechaty.user.contact.Contact.gender
### 示例代码
> 注意: ContactGender是个枚举类型.

**类型**: [`Contact`](contact.md#Contact)的实例方法

**示例**

```python
import asyncio
from wechaty import Wechaty, Message, ContactGender
Expand All @@ -261,38 +157,11 @@ class MyBot(Wechaty):
asyncio.run(MyBot().start())
```

### def province\(self\) ⇒ `Optional[str]`

获取一个联系人-的省份信息

**类型**: [`Contact`](contact.md#Contact)的实例方法

**示例**

```python
province: str = contact.province()
```

### def city(self) ⇒ `Optional[str]`

获取联系人所设置的城市

**类型**: [`Contact`](contact.md#Contact)的实例方法

**示例**

```python
city: str = contact.city()
```

### sync def avatar\(self, file_box: `Optional[FileBox]` = None\) ⇒ `FileBox`

获取联系人头像图片的文件流

**类型**: [`Contact`](contact.md#Contact)的实例方法

**示例**
::: wechaty.user.contact.Contact.city

::: wechaty.user.contact.Contact.avatar
### 示例代码
```python
# 以类似 `1-name.jpg`的格式保存头像图片到本地
import asyncio
Expand All @@ -310,95 +179,12 @@ class MyBot(Wechaty):
asyncio.run(MyBot().start())
```

### async def sync\(self\) ⇒ `None`

强制重新加载联系人的数据，再次从低级 API 同步数据。

**类型**: [`Contact`](contact.md#Contact)的实例方法

**示例**

```python
await contact.sync()
```

### def is_self\(self\) ⇒ `bool`

检查该联系人对象是不是Bot自身

**类型**: [`Contact`](contact.md#Contact)的实例方法

**返回值**: `bool` - 如果该联系人对象是Bot自身则返回True, 若不是则返回False

**示例**

```python
is_self: bool = contact.self()
```

### `@classmethod` async def find\(cls, query: `Union[str, ContactQueryFilter, Callable[[Contact], bool]]`\) ⇒ `Optional[Contact]`

尝试通过过滤器查找联系人: {name: string \| RegExp} / {alias: string \| RegExp}

通过联系人的名字(name)或者别名(alias)来获取联系人对象, 如果查找的结果大于一个, 则返回第一个.

**类型**: [`Contact`](contact.md#Contact)的**静态方法**

**返回值**: `Optional[Contact]` - 如果能找到联系人，则返回找到的联系人对象，否则返回`None`
::: wechaty.user.contact.Contact.tags

| 参数 | 类型 |
| :--- | :--- |
| query | [`ContactQueryFilter`](contact.md#ContactQueryFilter) |
::: wechaty.user.contact.Contact.is_self

#### 示例
::: wechaty.user.contact.Contact.weixin

```python
import asyncio
from wechaty import Wechaty, Contact
from wechaty_puppet import ContactQueryFilter

class MyBot(Wechaty):

async def on_login(self, contact: Contact) -> None:
contact = await self.Contact.find(ContactQueryFilter(name="lijiarui"))
contact = await self.Contact.find(ContactQueryFilter(alias="ruirui"))

asyncio.run(MyBot().start())
```

### `@classmethod` async def find_all\(cls, query: `Optional[Union[str, ContactQueryFilter, Callable[[Contact], bool]]]` = None\) -> `List[Contact]`

通过 `name` 或者 `alias` 查找并获取联系人对象

使用 Contact.find_all\(\) 获取机器人的联系人列表。 包括来自机器人加入的房间内的联系人。

#### 定义

* `name` 由用户自己设置的名字, 叫做name
* `alias` 由Bot为联系人设置的名字\(备注/别名\). 该值可以传入正则表达式用于搜索用户

**类型**: [`Contact`](contact.md#Contact)的**静态方法**

| 参数 | 类型 |
| :--- | :--- |
| queryArg | [`ContactQueryFilter`](contact.md#ContactQueryFilter) |

#### 示例

```python
import asyncio
from wechaty import Wechaty, Contact
from wechaty_puppet import ContactQueryFilter

class MyBot(Wechaty):

async def on_login(self, contact: Contact) -> None:
contact = await self.Contact.find_all() # 获取一个列表, 里面包含了Bot所有的联系人
contact = await self.Contact.find_all(ContactQueryFilter(name="lijiarui")) # 获取一个包含所有名字为lijiarui的联系人的列表
contact = await self.Contact.find_all(ContactQueryFilter(alias="ruirui")) # 获取一个包含所有别名(备注)为ruirui的联系人的列表

asyncio.run(MyBot().start())
```
## Typedefs 类型定义

### [ContactQueryFilter](contact.md#ContactQueryFilter)
Expand All @@ -409,3 +195,4 @@ asyncio.run(MyBot().start())
| ---------- | -------- | ------------------------------------------------------------ |
| name | `str` | 由用户本身(user-self)设置的名字, 叫做name |
| alias | `str` | 由Bot为联系人设置的名字(备注/别名). 该值可以传入正则表达式用于搜索用户, 更多细节详见[issues#365](https://github.com/wechaty/wechaty/issues/365)和[源码](https://github.com/wechaty/python-wechaty-puppet/blob/master/src/wechaty_puppet/schemas/contact.py) |

Loading