From b9bbaed369a0f2cb82f5d84f1d150850618c394a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A4=9A=E5=90=83=E7=82=B9=E8=8B=B9=E6=9E=9C?= <73388495+eatmoreapple@users.noreply.github.com> Date: Tue, 24 Jan 2023 21:44:35 +0800 Subject: [PATCH] [doc]: update docs (#214) --- README.md | 8 +-- source/bot.md | 39 +++++++------- source/message.md | 127 +++++++++++++++------------------------------- 3 files changed, 67 insertions(+), 107 deletions(-) diff --git a/README.md b/README.md index 21dadc2..12d9df5 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,16 @@ [![Go Doc](https://pkg.go.dev/badge/github.com/eatMoreApple/openwechat)](https://godoc.org/github.com/eatMoreApple/openwechat)[![Release](https://img.shields.io/github/v/release/eatmoreapple/openwechat.svg?style=flat-square)](https://github.com/eatmoreapple/openwechat/releases)[![Go Report Card](https://goreportcard.com/badge/github.com/eatmoreapple/openwechat)](https://goreportcard.com/badge/github.com/eatmoreapple/openwechat)[![Stars](https://img.shields.io/github/stars/eatmoreapple/openwechat.svg?style=flat-square)](https://img.shields.io/github/stars/eatmoreapple/openwechat.svg?style=flat-square)[![Forks](https://img.shields.io/github/forks/eatmoreapple/openwechat.svg?style=flat-square)](https://img.shields.io/github/forks/eatmoreapple/openwechat.svg?style=flat-square) -> golang版个人微信号API, 突破网页版限制，类似开发公众号一样，开发个人微信号 +> golang版个人微信号API, 突破登录限制，类似开发公众号一样，开发个人微信号 微信机器人:smiling_imp:，利用微信号完成一些功能的定制化开发⭐ - +* 模块简单易用，易于扩展 * 支持定制化开发，如日志记录，自动回复 -* 突破网页版登录限制📣 +* 突破登录限制📣 * 无需重复扫码登录 * 支持多个微信号同时登陆 @@ -115,7 +115,7 @@ func main() { ### 添加微信(EatMoreApple):apple:（备注: openwechat），进群交流:smiling_imp: -**如果二维码图片没显示出来，请添加微信号 EatMoreApple** +**如果二维码图片没显示出来，请添加微信号 eatmoreapple** diff --git a/source/bot.md b/source/bot.md index 002ea7e..b5e3148 100644 --- a/source/bot.md +++ b/source/bot.md @@ -84,6 +84,8 @@ bot.Login() // 创建热存储容器对象 reloadStorage := openwechat.NewJsonFileHotReloadStorage("storage.json") +defer reloadStorage.Close() + // 执行热登录 bot.HotLogin(reloadStorage) ``` @@ -95,7 +97,7 @@ bot.HotLogin(reloadStorage) 我们只需要在`HotLogin`增加一个参数，让它在失败后执行扫码登录即可 ```go -bot.HotLogin(reloadStorage, openwechat.HotLoginWithRetry(true)) +bot.HotLogin(reloadStorage, openwechat.NewRetryLoginOption()) ``` 当扫码登录成功后，会将会话信息写入到`热存储容器`中，下次再执行热登录的时候就会从`热存储容器`中读取会话信息，直接登录成功。 @@ -119,29 +121,23 @@ type HotReloadStorage io.ReadWriter openwechat也提供了这样的功能。 ```go -bot.PushLogin(storage HotReloadStorage, opts ...PushLoginOptionFunc) error +bot.PushLogin(storage HotReloadStorage, opts ...openwechat.BotLoginOption) error ``` `PushLogin`需要传入一个`热存储容器`，和一些可选参数。 `HotReloadStorage` 跟上面一样，用来保存会话信息，必要参数。 -`PushLoginOptionFunc`是一个可选参数，用来设置一些额外的行为。 +`openwechat.BotLoginOption`是一个可选参数，用来设置一些额外的行为。 目前有下面几个可选参数： ```go -// PushLoginWithoutUUIDCallback 设置 PushLogin 不执行二维码回调, 默认为 true -func PushLoginWithoutUUIDCallback(flag bool) PushLoginOptionFunc +// NewSyncReloadDataLoginOption 登录成功后定时同步热存储容器数据 +func NewSyncReloadDataLoginOption(duration time.Duration) BotLoginOption -// PushLoginWithoutScanCallback 设置 PushLogin 不执行扫码回调， 默认为true -func PushLoginWithoutScanCallback(flag bool) PushLoginOptionFunc - -// PushLoginWithoutLoginCallback 设置 PushLogin 不执行登录回调，默认为false -func PushLoginWithoutLoginCallback(flag bool) PushLoginOptionFunc - -// PushLoginWithRetry 设置 PushLogin 失败后执行扫码登录，默认为false -func PushLoginWithRetry(flag bool) PushLoginOptionFunc +// NewRetryLoginOption 登录失败后进行扫码登录 +func NewRetryLoginOption() BotLoginOption ``` 注意：如果是第一次登录，``PushLogin`` 一定会失败的，因为我们的`HotReloadStorage`里面没有会话信息，你需要设置失败会进行扫码登录。 @@ -149,7 +145,8 @@ func PushLoginWithRetry(flag bool) PushLoginOptionFunc ```go bot := openwechat.DefaultBot() reloadStorage := openwechat.NewJsonFileHotReloadStorage("storage.json") -err = bot.PushLogin(reloadStorage, openwechat.PushLoginWithRetry(true)) +defer reloadStorage.Close() +err = bot.PushLogin(reloadStorage, openwechat.NewRetryLoginOption()) ``` 这样当第一次登录失败的时候，会自动执行扫码登录。 @@ -164,13 +161,21 @@ err = bot.PushLogin(reloadStorage, openwechat.PushLoginWithRetry(true)) 通过对`bot`对象绑定扫码回调即可实现对应的功能。 ```go -bot.ScanCallBack = func(body []byte) { fmt.Println(string(body)) } +bot.ScanCallBack = func(body openwechat.CheckLoginResponse) { fmt.Println(string(body)) } ``` 用户扫码后，body里面会携带用户的头像信息。 **注**：绑定扫码回调须在登录前执行。 +`CheckLoginResponse` 是一个`[]byte`包装类型, 扫码成功后可以通过该类型获取用户的头像信息。 + +```go +type CheckLoginResponse []byte + +func (c CheckLoginResponse) Avatar() (string, error) +``` + ### 登录回调 @@ -178,13 +183,13 @@ bot.ScanCallBack = func(body []byte) { fmt.Println(string(body)) } 对`bot`对象绑定登录 ```go -bot.LoginCallBack = func(body []byte) { +bot.LoginCallBack = func(body openwechat.CheckLoginResponse) { fmt.Println(string(body)) // to do your business } ``` -登录回调的参数就是当前客户端需要跳转的链接，可以不用关心它。 +登录回调的参数就是当前客户端需要跳转的链接，用户可以不用关心它。（其实可以拿来做一些骚操作😈） 登录回调函数可以当做一个信号处理，表示当前扫码登录的用户已经确认登录。 diff --git a/source/message.md b/source/message.md index 0d6b3e3..f55b376 100644 --- a/source/message.md +++ b/source/message.md @@ -1,7 +1,5 @@ # 消息 - - ### 接受消息 被动接受的消息对象，由微信服务器发出 @@ -9,29 +7,25 @@ 消息对象通过绑定在`bot`上的消息回调函数获取 ```go -bot.MessageHandler = func(msg *openwechat.Message) { - if msg.IsText() && msg.Content == "ping" { - msg.ReplyText("pong") - } +bot.MessageHandler = func (msg *openwechat.Message) { +if msg.IsText() && msg.Content == "ping" { +msg.ReplyText("pong") +} } ``` 以下简写为`msg` - - #### 消息内容 ```go -msg.Content // 获取消息内容 +msg.Content // 获取消息内容 ``` 通过访问`Content`属性可直接获取消息内容 由于消息分为很多种类型，它们都共用`Content`属性。一般当消息类型为文本类型的时候，我们才会去访问`Content`属性。 - - #### 消息类型判断 下面的判断消息类型的方法均返回`bool`值 @@ -117,13 +111,17 @@ msg.IsIsPaiYiPai() // 拍一拍消息 msg.IsTickled() ``` +##### 判断是否拍了拍自己 +```go +msg.IsTickledMe() +``` + ##### 判断是否有新人加入群聊 + ```go msg.IsJoinGroup() ``` - - #### 获取消息的发送者 ```go @@ -132,16 +130,12 @@ sender, err := msg.Sender() 如果是群聊消息，该方法返回的是群聊对象(需要自己将`User`转换为`Group`对象) - - #### 获取消息的接受者 ```go receiver, err := msg.Receiver() ``` - - #### 获取消息在群里面的发送者 ```go @@ -150,8 +144,6 @@ sender, err := msg.SenderInGroup() 获取群聊中具体发消息的用户，前提该消息必须来自群聊。 - - #### 是否由自己发送 ```go @@ -164,31 +156,24 @@ msg.IsSendBySelf() msg.IsTickled() ``` - #### 消息是否由好友发出 ```go msg.IsSendByFriend() ``` - - #### 消息是否由群聊发出 ```go msg.IsSendByGroup() ``` - - #### 回复文本消息 ```go msg.ReplyText("hello") ``` - - #### 回复图片消息 ```go @@ -197,8 +182,6 @@ defer img.Close() msg.ReplyImage(img) ``` - - #### 回复文件消息 ```go @@ -207,14 +190,12 @@ defer file.Close() msg.ReplyFile(file) ``` - - #### 获取消息里的其他信息 ##### 名片消息 ```go -card, err := msg. Card() +card, err := msg.Card() ``` 该方法调用的前提为`msg.IsCard()`返回为`true` @@ -230,31 +211,29 @@ alias := card.Alias ```go // 名片消息内容 type Card struct { - XMLName xml.Name `xml:"msg"` - ImageStatus int `xml:"imagestatus,attr"` - Scene int `xml:"scene,attr"` - Sex int `xml:"sex,attr"` - Certflag int `xml:"certflag,attr"` - BigHeadImgUrl string `xml:"bigheadimgurl,attr"` - SmallHeadImgUrl string `xml:"smallheadimgurl,attr"` - UserName string `xml:"username,attr"` - NickName string `xml:"nickname,attr"` - ShortPy string `xml:"shortpy,attr"` - Alias string `xml:"alias,attr"` // Note: 这个是名片用户的微信号 - Province string `xml:"province,attr"` - City string `xml:"city,attr"` - Sign string `xml:"sign,attr"` - Certinfo string `xml:"certinfo,attr"` - BrandIconUrl string `xml:"brandIconUrl,attr"` - BrandHomeUr string `xml:"brandHomeUr,attr"` - BrandSubscriptConfigUrl string `xml:"brandSubscriptConfigUrl,attr"` - BrandFlags string `xml:"brandFlags,attr"` - RegionCode string `xml:"regionCode,attr"` +XMLName xml.Name `xml:"msg"` +ImageStatus int `xml:"imagestatus,attr"` +Scene int `xml:"scene,attr"` +Sex int `xml:"sex,attr"` +Certflag int `xml:"certflag,attr"` +BigHeadImgUrl string `xml:"bigheadimgurl,attr"` +SmallHeadImgUrl string `xml:"smallheadimgurl,attr"` +UserName string `xml:"username,attr"` +NickName string `xml:"nickname,attr"` +ShortPy string `xml:"shortpy,attr"` +Alias string `xml:"alias,attr"` // Note: 这个是名片用户的微信号 +Province string `xml:"province,attr"` +City string `xml:"city,attr"` +Sign string `xml:"sign,attr"` +Certinfo string `xml:"certinfo,attr"` +BrandIconUrl string `xml:"brandIconUrl,attr"` +BrandHomeUr string `xml:"brandHomeUr,attr"` +BrandSubscriptConfigUrl string `xml:"brandSubscriptConfigUrl,attr"` +BrandFlags string `xml:"brandFlags,attr"` +RegionCode string `xml:"regionCode,attr"` } ``` - - ##### 获取已撤回的消息 ```go @@ -267,19 +246,17 @@ revokeMsg, err := msg.RevokeMsg() ```go type RevokeMsg struct { - SysMsg xml.Name `xml:"sysmsg"` - Type string `xml:"type,attr"` - RevokeMsg struct { - OldMsgId int64 `xml:"oldmsgid"` - MsgId int64 `xml:"msgid"` - Session string `xml:"session"` - ReplaceMsg string `xml:"replacemsg"` - } `xml:"revokemsg"` +SysMsg xml.Name `xml:"sysmsg"` +Type string `xml:"type,attr"` +RevokeMsg struct { +OldMsgId int64 `xml:"oldmsgid"` +MsgId int64 `xml:"msgid"` +Session string `xml:"session"` +ReplaceMsg string `xml:"replacemsg"` +} `xml:"revokemsg"` } ``` - - #### 同意好友请求 ```go @@ -291,8 +268,6 @@ friend, err := msg.Agree() 该方法调用成功的前提是`msg.IsFriendAdd()`返回为`true` - - #### 设置为已读 ```go @@ -301,10 +276,6 @@ msg.AsRead() 该当前消息设置为已读 - - - - #### 设置消息的上下文 用于多个消息处理函数之间的通信，并且是协程安全的。 @@ -321,10 +292,6 @@ msg.Set("hello", "world") value, exist := msg.Get("hello") ``` - - - - ### 已发送消息 已发送消息指当前用户发送出去的消息 @@ -339,8 +306,6 @@ sentMsg, err := msg.ReplyText("hello") // 通过回复消息获取 // and so on ``` - - #### 撤回消息 撤回刚刚发送的消息，撤回消息的有效时间为2分钟，超过了这个时间则无法撤回 @@ -349,16 +314,12 @@ sentMsg, err := msg.ReplyText("hello") // 通过回复消息获取 sentMsg.Revoke() ``` - - #### 判断是否可以撤回 ```go sentMsg.CanRevoke() ``` - - #### 转发给好友 ```go @@ -367,8 +328,6 @@ sentMsg.ForwardToFriends(friend1, friend2) 将刚发送的消息转发给好友 - - #### 转发给群聊 ```go @@ -377,10 +336,6 @@ sentMsg.ForwardToGroups(group1, group2) 将刚发送的消息转发给群聊 - - - - ### Emoji表情 openwechat提供了微信全套`emoji`表情的支持 @@ -392,7 +347,7 @@ emoji表情可以通过发送`Text`类型的函数发送 如 ```go -firend.SendText(openwechat.Emoji.Doge) // 发送狗头表情 +firend.SendText(openwechat.Emoji.Doge) // 发送狗头表情 msg.ReplyText(openwechat.Emoji.Awesome) // 发送666的表情 ```