diff --git a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact-self.md b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact-self.md new file mode 100644 index 00000000000..0df5638d2ca --- /dev/null +++ b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact-self.md @@ -0,0 +1,104 @@ +--- +title: ContactSelf +--- + +机器人自己的信息将会封装一个ContactSelf 类。这个类继承自 Contact。 + +## ContactSelf + +> 备注：这个类继承自 Contact + +**Kind**: global class + +* ContactSelf + * 实例 + * contactSelf.avatar\(\[file\]\) ⇒ `Promise ` + * contactSelf.qrcode\(\) ⇒ `Promise ` + * contactSelf.signature\(signature\) ⇒ `Promise ` + * contactSelf.name\(\[name\]\) ⇒ `Promise | string` + +### contactSelf.avatar\(\[file\]\) ⇒ `Promise ` + +设置机器人的头像 + +**Kind**: `ContactSelf`的实例方法 + +| Param | Type | +| :--- | :--- | +| \[file\] | `FileBox` | + +**示例** _\( GET the avatar for bot, return {Promise<FileBox>}\)_ + +```javascript +bot.on('login', async user => { + console.log(`user ${user} login`) + const file = await user.avatar() + const name = file.name + await file.toFile(name, true) + console.log(`Save bot avatar: ${user.name()} with avatar file: ${name}`) +}) + +### contactSelf.qrcode\(\) ⇒ `Promise ` + +获取机器人的二维码。 + +**Kind**: `ContactSelf`的实例方法 + +#### 示例 + +```javascript +import { generate } from 'qrcode-terminal' +bot.on('login', async user => { + console.log(`user ${user} login`) + const qrcode = await user.qrcode() + console.log(`Following is the bot qrcode!`) + generate(qrcode, { small: true }) +}) +``` + +### contactSelf.signature\(signature\) ⇒ `Promise ` + +修改机器人签名。 + +**Kind**: `ContactSelf`的实例方法 + +| Param | Description | +| :--- | :--- | +| signature | 机器人要修改的签名内容 | + +#### 示例 + +```javascript +bot.on('login', async user => { + console.log(`user ${user} login`) + try { + await user.signature(`Signature changed by wechaty on ${new Date()}`) + } catch (e) { + console.error('change signature failed', e) + } +}) +``` + +### contactSelf.name\(\[name\]\) ⇒ `Promise | string` + +修改机器人昵称。 + +**Kind**: `ContactSelf`的实例方法 + +| Param | Description | +| :--- | :--- | +| \[name\] | 机器人要修改的昵称内容 | + +#### 示例 + +```javascript +bot.on('login', async user => { + console.log(`user ${user} login`) + const oldName = user.name() // get bot name + try { + await user.name(`${oldName}-${new Date().getTime()}`) // change bot name + } catch (e) { + console.error('change name failed', e) + } +}) +``` diff --git a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact.md b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact.md new file mode 100644 index 00000000000..fe4f2bc631c --- /dev/null +++ b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact.md @@ -0,0 +1,307 @@ +--- +title: Contact Class +--- + +所有的联系人（好友）都会被封装成Contact类实例。 + +## Classes + +所有的联系人（好友）都会被封装成Contact类实例。 +[Examples/Contact-Bot](https://github.com/wechaty/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/contact-bot.ts) + +## Contact + +所有的联系人（好友）都会被封装成Contact类实例。 + +### Properties + +| 名称 | 类型 | 描述 | +| :--- | :--- | :--- | +| id | `string` | 获取联系人ID，这个ID 是否为永久唯一ID 取决于您使用什么puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) | + +## Global Class `Contact` + +### 实例方法 + +| 实例方法 | 返回类型 | +|--------------------------------------|-----------------------------------------------------------------------| +| say(text 或 Contact 或 File 或 URL) | `Promise` | +| name() | `String` | +| alias(newAlias) | `Promise` | +| friend() | `Boolean 或 null` | +| type() | `ContactType.Unknown 或 ContactType.Personal 或 ContactType.Official` | +| gender() | `ContactGender.Unknown 或 ContactGender.Male 或 ContactGender.Female` | +| province() | `String 或 null` | +| city() | `String 或 null` | +| avatar() | `Promise` | +| sync() | `Promise` | +| self() | `Boolean` | + +### 静态方法 + +| 静态方法 | 返回类型 | +|---------------------------|-----------------------------| +| find(query) | `Promise ` | +| findAll(Query Arguments) | `Promise ` | + +### contact.say\(textOrContactOrFileOrUrlLinkOrMiniProgram\) ⇒ `Promise ` + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +| Param | Type | Description | +| :--- | :--- | :--- | +| text或Contact或File或UrlLink或MiniProgram | `string` \| `Contact` \| `FileBox` \| `UrlLink` \| `MiniProgram` | 给微信好友发送文本，联系人名片，文件或者链接。你可以使用[FileBox](https://www.npmjs.com/package/file-box) 来发送文件。| + +### 示例 + +```javascript +import { FileBox } from 'file-box' +import { + Wechaty, + UrlLink, + MiniProgram, +} from 'wechaty' + +const bot = new Wechaty() +await bot.start() +const contact = await bot.Contact.find({name: 'lijiarui'}) + +// 1. 为contact发短信 + +await contact.say('welcome to wechaty!') + +// 2. 为contact发文件 + +import { FileBox } from 'file-box' +const fileBox1 = FileBox.fromUrl('https://wechaty.github.io/wechaty/images/bot-qr-code.png') +const fileBox2 = FileBox.fromFile('/tmp/text.txt') +await contact.say(fileBox1) +await contact.say(fileBox2) + +// 3. 为contact发contact card + +const contactCard = bot.Contact.load('contactId') +await contact.say(contactCard) + +// 4. 为contact发url链接 + +const urlLink = new UrlLink({ + description : 'WeChat Bot SDK for Individual Account, Powered by TypeScript, Docker, and Love', + thumbnailUrl: 'https://avatars0.githubusercontent.com/u/25162437?s=200&v=4', + title : 'Welcome to Wechaty', + url : 'https://github.com/wechaty/wechaty', +}) +await contact.say(urlLink) + +// 5. 发小程序 (仅`wechaty-puppet-macpro`支持) + +const miniProgram = new MiniProgram ({ + appid : 'gh_0aa444a25adc', + title : '我正在使用Authing认证身份，你也来试试吧', + pagePath : 'routes/explore.html', + description : '身份管家', + thumbUrl : '30590201000452305002010002041092541302033d0af802040b30feb602045df0c2c5042b777875706c6f61645f31373533353339353230344063686174726f6f6d3131355f313537363035393538390204010400030201000400', + thumbKey : '42f8609e62817ae45cf7d8fefb532e83', +}); + +await contact.say(miniProgram); +``` + +### contact.name\(\) ⇒ `string` + +获取联系人的昵称。 + +### 示例 + +```javascript +const name = contact.name() +``` + +### contact.alias\(newAlias\) ⇒ `Promise ` + +获取/设置/删除 好友的备注。如果设置备注过于频繁，设置将会失效\(比如1分钟设置60次\)。 + +| Param | Type | +| :--- | :--- | +| newAlias | `undefined` \| `string` \| `null` | + +### 示例 \( GET contact的备注, return {\(Promise<string \| null>\)}\) + +```javascript +const alias = await contact.alias() +if (alias === null) { + console.log('You have not yet set any alias for contact ' + contact.name()) +} else { + console.log('You have already set an alias for contact ' + contact.name() + ':' + alias) +} +``` + +### 示例 \(SET contact的备注\) + +```javascript +try { + await contact.alias('lijiarui') + console.log(`change ${contact.name()}'s alias successfully!`) +} catch (e) { + console.log(`failed to change ${contact.name()} alias!`) +} +``` + +### 示例 \(DELETE contact的备注\) + +```javascript +try { + const oldAlias = await contact.alias(null) + console.log(`delete ${contact.name()}'s alias successfully!`) + console.log(`old alias is ${oldAlias}`) +} catch (e) { + console.log(`failed to delete ${contact.name()}'s alias!`) +} +``` + +### Contact.friend\(\) ⇒ `boolean` \| `null` + +判断这个联系人是否为机器人的好友。Returns: `boolean` 或 `null`, 是friend, return`true`，不是friend, return`false`，`null`是unknown + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +### 示例 + +```javascript +const isFriend = contact.friend() +``` + +### Contact.type\(\) ⇒ `ContactType.Unknown` \| `ContactType.Personal` \| `ContactType.Official` + +获取好友的类型，是公众号还是普通还有。 + +> 备注：ContactType 在这里是enum + +### 示例 + +```javascript +const bot = new Wechaty() +await bot.start() +const isOfficial = contact.type() === bot.Contact.Type.Official +``` + +### contact.gender\(\) ⇒ `ContactGender.Unknown` \| `ContactGender.Male` \| `ContactGender.Female` + +获取联系人的性别。 +> 备注：ContactGender在这里是enum + +### 示例 + +```javascript +const gender = contact.gender() === bot.Contact.Gender.Male +``` + +### Contact.province\(\) ⇒ `string` \| `null` + +获取联系人设置的省份信息。 + +### 示例 + +```javascript +const province = contact.province() +``` + +### Contact.city\(\) ⇒ `string` \| `null` + +获取联系人设置的城市信息。 + +### 示例 + +```javascript +const city = contact.city() +``` + +### Contact.avatar\(\) ⇒ `Promise ` + +获取联系人的头像。 + +### 示例 + +```javascript +// Save avatar to local file like `1-name.jpg` + +const file = await contact.avatar() +const name = file.name +await file.toFile(name, true) +console.log(`Contact: ${contact.name()} with avatar file: ${name}`) +``` + +### Contact.sync\(\) ⇒ `Promise ` + +强制重新加载好友数据，会从低级别的 API 中重新同步一遍。 + +### 示例 + +```javascript +await contact.sync() +``` + +### Contact.self\(\) ⇒ `boolean` + +检测好友是否是机器人自己。 + +### 示例 + +```javascript +const isSelf = contact.self() +``` + +## Static Methods + +### Contact.find\(query\) ⇒ `Promise ` + +通过类似这样的命令查找联系人: {name: string \| RegExp} / {alias: string \| RegExp}。支持通过昵称或者备注查找。如果查到不止一个联系人，返回找到的第一个。能找contact, return `Promise`, 没有contact, return `null`. + +| Param | Type | +| :--- | :--- | +| query | `ContactQueryFilter` | + +#### 示例 + +```javascript +const bot = new Wechaty() +await bot.start() +const contactFindByName = await bot.Contact.find({ name:"ruirui"} ) +const contactFindByAlias = await bot.Contact.find({ alias:"lijiarui"} ) +``` + +### Contact.findAll\(\[queryArg\]\) ⇒ `Promise ` + +通过`name`(昵称)或者`alias`(备注)查找联系人。用 Contact.findAll() 获取机器人的所有联系人列表。 + +#### 定义 + +* `name` 用户自己设置的昵称叫做name +* `alias` 机器人给这个用户设置的昵称叫做alias + +| Param | Type | +| :--- | :--- | +| queryArg | `ContactQueryFilter` | + +#### 示例 + +```javascript +const bot = new Wechaty() +await bot.start() +const contactList = await bot.Contact.findAll() // get the contact list of the bot +const contactList = await bot.Contact.findAll({ name: 'ruirui' }) // find all of the contacts whose name is 'ruirui' +const contactList = await bot.Contact.findAll({ alias: 'lijiarui' }) // find all of the contacts whose alias is 'lijiarui' +``` + +## Typedefs + +### ContactQueryFilter + +搜索联系人的方式。 + +### Properties + +| Name | Type | Description | +| :--- | :--- | :--- | +| name | `string` | 用户自己设置的昵称叫做name | +| alias | `string` | 机器人或者其他人给这个用户设置的昵称叫做alias [更多](https://github.com/wechaty/wechaty/issues/365) | diff --git a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/friendship.md b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/friendship.md new file mode 100644 index 00000000000..0a42c5d1f78 --- /dev/null +++ b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/friendship.md @@ -0,0 +1,189 @@ +--- +title: Friendship +--- + +Wechaty机器人允许你通过其名为`Friendship`的全球类结交朋友。本节完全是关于`Friendship`类的。 + +[Examples or Friend-Bot](https://github.com/wechaty/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/friend-bot.ts) + +## Global class Friendship + +发送，接受好友请求的Class，有以下三种: + +1. 发送好友请求 +2. 在 \(friend event\) 中收到好友请求 +3. 在 \(friend event\) 中确认好友请求 + +### 实例方法 + +| 实例方法 | 返回类型 | +|------------------|------------------| +| accept() | `Promise (void)` | +| hello() | `string` | +| contact() | `Contact` | +| type() | `FriendshipType` | + +### 静态方法 + +| 静态方法 | 返回类型 | +|----------------|------------------| +| add() | `Promise (void)` | + +### friendship.accept\(\) ⇒ `Promise ` + +通过好友请求。 + +#### 示例 + +```javascript +const bot = new Wechaty() +bot.on('friendship', async friendship => { + try { + console.log(`received friend event.`) + switch (friendship.type()) { + + // 1. 新好友请求 + + case bot.Friendship.Type.Receive: + await friendship.accept() + break + + // 2. 好友请求接受 + + case bot.Friendship.Type.Confirm: + console.log(`friend ship confirmed`) + break + } + } catch (e) { + console.error(e) + } +}) +.start() +``` + +### friendship.hello\(\) ⇒ `string` + +获取对方发送好友请求的验证信息。 + +**示例** _\(如内容是 \`ding\`, 接受好友请求\)_ + +```javascript +const bot = new Wechaty() +bot.on('friendship', async friendship => { + try { + console.log(`received friend event from ${friendship.contact().name()}`) + if (friendship.type() === bot.Friendship.Type.Receive && friendship.hello() === 'ding') { + await friendship.accept() + } + } catch (e) { + console.error(e) + } +} +.start() +``` + +### friendship.contact\(\) ⇒ `Contact` + +获取发送好友请求的联系人。 + +#### 示例 + +```javascript +const bot = new Wechaty() +bot.on('friendship', friendship => { + const contact = friendship.contact() + const name = contact.name() + console.log(`received friend event from ${name}`) +} +.start() +``` + +### friendship.type\(\) ⇒ `FriendshipType` + +返回好友请求的类型。 + +> 备注：在这里是enum: +> +> * FriendshipType.Unknown +> * FriendshipType.Confirm +> * FriendshipType.Receive +> * FriendshipType.Verify + +### 示例 _\(如内容是 \`ding\`, 接受好友请求\)_ + +```javascript +const bot = new Wechaty() +bot.on('friendship', async friendship => { + try { + if (friendship.type() === bot.Friendship.Type.Receive && friendship.hello() === 'ding') { + await friendship.accept() + } + } catch (e) { + console.error(e) + } +} +.start() +``` + +### Friendship.search\(phone\) ⇒ `Promise ` + +该方法通过电话号码搜索联系人并获取联系人。 +> 最佳实践：每分钟加1次，如果发送的过于频繁，你可能会被封号，每天能添加的好友数量是有上限的。 + +| Param | Type | Description | +| :--- | :--- | :--- | +| phone | `number` | 搜索电话号码 | + +#### 示例 + +```javascript +const phone = '131xxx1234' +const searchContact = await bot.Friendship.search({ + phone, +}) +``` + +### Friendship.add\(contact, options\) ⇒ `Promise ` + +发送好友请求给contact 发送的内容是 hello. +> 最佳实践：每分钟加1次，如果发送的过于频繁，你可能会被封号，每天能添加的好友数量是有上限的。 + +| Param | Type | Description | +| :--- | :--- | :--- | +| contact | `Contact` | 需要发送好友请求的联系人 | +| options | `FriendshipAddOptions` | 发送好友请求的内容 | + +#### 示例 \(Add搜索的contact\) + +```javascript +await bot.Friendship.add(searchContact, { hello: 'Nice to meet you! I am wechaty bot!' }) +``` + +#### 示例 \(add room member\) + +```javascript +const memberList = await room.memberList() +for (let i = 0; i < memberList.length; i++) { + await bot.Friendship.add(member, { + room: message.room(), + hello: 'Nice to meet you! I am wechaty bot!', + }) +} + +``` + +#### 示例 \(add contact card\) + +```javascript +if (message.type() === bot.Message.Type.Contact) { + const contact = await message.toContact() + const options = { + contact: message.talker(), + hello: 'Nice to meet you! I am wechaty bot!', + } + if (message.room()) { + options.room = message.room() + } + await bot.Friendship.add(contact, options) +} +``` diff --git a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/message.md b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/message.md new file mode 100644 index 00000000000..2682b4d6b0c --- /dev/null +++ b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/message.md @@ -0,0 +1,356 @@ +--- +title: Message +--- +本节对消息类、其方法及其用途进行了清晰的描述。所有的微信消息会被封装成一个`Message`类。 + +[Examples/Ding-Dong-Bot](https://github.com/wechaty/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/ding-dong-bot.ts) + +## Global Class `Message` + +### 实例方法 + +| 实例方法 | 返回类型 | +|--------------------------------|---------------------| +| from\(\) | `Contact` 或 `null` | +| to\(\) | `Contact` 或 `null` | +| room\(\) | `Room` 或 `null` | +| text\(\) | `string` | +| say\(text Or Contact Or File\) | `Promise` | +| type\(\) | `MessageType` | +| self\(\) | `boolean` | +| mention\(\) | `Promise` | +| mentionSelf\(\) | `Promise` | +| forward\(to\) | `Promise` | +| date\(\) | `Date` | +| age\(\) | `Number` | +| toFileBox\(\) | `Promise` | +| toContact\(\) | `Promise` | +| toUrlLink\(\) | `Promise` | + +### 静态方法 + +| 静态方法 | 返回类型 | +|----------------|-------------| +| find\(\) | `Promise` | +| findAll\(\) | `Promise` | + +## 实例方法 + +### message.from\(\) ⇒ `Contact | null` + +获取发送消息的联系人。 +找不到发送的人，return `null`. + +### 示例 + +```javascript +const bot = new Wechaty() +bot +.on('message', async message => { + const contact = message.from() + const text = message.text() + const room = message.room() + if (room) { + const topic = await room.topic() + console.log(`Room: ${topic} Contact: ${contact.name()} Text: ${text}`) + } else { + console.log(`Contact: ${contact.name()} Text: ${text}`) + } +}) +.start() +``` + +### message.to\(\) ⇒ `Contact` \| `null` + +获取消息发送的联系人。在room中， return `null`。 使用Message.room\(\) 获取room信息。 + +### 示例 + +```javascript +const bot = new Wechaty() +bot +.on('message', async message => { + const contact = message.from() + const text = message.text() + const toContact = message.to() + if (toContact) { + const name = toContact.name() + console.log(`toContact: ${name} Contact: ${contact.name()} Text: ${text}`) + } else { + console.log(`Contact: ${contact.name()} Text: ${text}`) + } +}) +.start() +``` + +### message.room\(\) ⇒ `Room` \| `null` + +获取消息所在的room，如果这条消息不在room中，会返回`null`。 + +### 示例 + +```javascript +const bot = new Wechaty() +bot +.on('message', async message => { + const contact = message.from() + const text = message.text() + const room = message.room() + if (room) { + const topic = await room.topic() + console.log(`Room: ${topic} Contact: ${contact.name()} Text: ${text}`) + } else { + console.log(`Contact: ${contact.name()} Text: ${text}`) + } +}) +.start() +``` + +### message.text\(\) ⇒ `string` + +获取消息的文本内容。 + +### 示例 + +```javascript +const bot = new Wechaty() +bot +.on('message', async message => { + const contact = message.from() + const text = message.text() + const room = message.room() + if (room) { + const topic = await room.topic() + console.log(`Room: ${topic} Contact: ${contact.name()} Text: ${text}`) + } else { + console.log(`Contact: ${contact.name()} Text: ${text}`) + } +}) +.start() +``` + +### message.toRecalled\(\) ⇒ `Promise ` + +获取撤回消息的文本内容。 + +### 示例 + +```javascript +const bot = new Wechaty() +bot +.on('message', async message => { + if (message.type() === bot.Message.Type.Recalled) { + const recalledMessage = await message.toRecalled() + console.log(`Message: ${recalledMessage} has been recalled.`) + } +}) +.start() +``` + +### message.say\(text或Contact或File或UrlLink或MiniProgram\) ⇒ `Promise ` + +回复多媒体、微信名片、文本或者链接给这条消息的发送者。 + +| Param | Type | Description | +| :--- | :--- | :--- | +| text 或 Contact 或 File 或 UrlLink 或 MiniProgram | `string` \| `Contact` \| `FileBox` \| `UrlLink` \| `MiniProgram` | 发送文本、名片或者文件 可以使用 [FileBox](https://www.npmjs.com/package/file-box) 来发送文件 | + +备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +**See🏻**: [Examples/ding-dong-bot](https://github.com/wechaty/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/ding-dong-bot.ts) + +### 示例 + +```javascript +import { FileBox } from 'file-box' +import { + Wechaty, + UrlLink, + MiniProgram, +} from 'wechaty' + +const bot = new Wechaty() +bot +.on('message', async message => { + +// 1. 发照片 + + if (/^ding$/i.test(message.text())) { + const fileBox = FileBox.fromUrl('https://wechaty.github.io/wechaty/images/bot-qr-code.png') + await message.say(fileBox) + } + +// 2. 发短信 + + if (/^dong$/i.test(message.text())) { + await message.say('dingdingding') + } + +// 3. 发contact + + if (/^lijiarui$/i.test(message.text())) { + const contactCard = await bot.Contact.find({name: 'lijiarui'}) + if (!contactCard) { + console.log('not found') + return + } + await message.say(contactCard) + } + +// 4. 发链接 + + if (/^link$/i.test(message.text())) { + const urlLink = new UrlLink({ + description: 'Wechaty is a Bot SDK for Wechat Individual Account which can help you create a bot in 6 lines of javascript, with cross-platform support including Linux, Windows, Darwin(OSX/Mac) and Docker.', + thumbnailUrl: 'https://camo.githubusercontent.com/f310a2097d4aa79d6db2962fa42bb3bb2f6d43df/68747470733a2f2f6368617469652e696f2f776563686174792f696d616765732f776563686174792d6c6f676f2d656e2e706e67', + title: 'Wechaty', + url: 'https://github.com/wechaty/wechaty', + }); + + await message.say(urlLink); + } + +// 5. 发小程序 (仅 `wechaty-puppet-macpro`支持) + + if (/^mini-program$/i.test(message.text())) { + const miniProgram = new MiniProgram ({ + appid : 'gh_0aa444a25adc', + title : '我正在使用Authing认证身份，你也来试试吧', + pagePath : 'routes/explore.html', + thumbUrl : '30590201000452305002010002041092541302033d0af802040b30feb602045df0c2c5042b777875706c6f61645f31373533353339353230344063686174726f6f6d3131355f313537363035393538390204010400030201000400', + thumbKey : '42f8609e62817ae45cf7d8fefb532e83', + }); + + await message.say(miniProgram); + } +}) +.start() +``` + +### message.type\(\) ⇒ `MessageType` + +此方法获取Wechaty消息的类型。下面列出了支持的不同方法类型： + +| 消息类型 | +|------------------------| +| MessageType.Unknown | +| MessageType.Attachment | +| MessageType.Audio | +| MessageType.Contact | +| MessageType.Emoticon | +| MessageType.Image | +| MessageType.Text | +| MessageType.Video | +| MessageType.Url | + +### 示例 + +```javascript +const bot = new Wechaty() +if (message.type() === bot.Message.Type.Text) { + console.log('This is a text message') +} +``` + +### message.self\(\) ⇒ `boolean` + +查看这条消息是否为机器人发送的。 +message是自己发的，return `true`，是其他发的，return`false` + +### 示例 + +```javascript +if (message.self()) { + console.log('this message is sent by myself!') +} +``` + +### message.mention\(\) ⇒ `Promise ` + +获取在群中@的用户列表。 + +| | Web | Mac PC Client | iOS Mobile | android Mobile | +| :--- | :---: | :---: | :---: | :---: | +| \[You were mentioned\] tip \(\[有人@我\]的提示\) | ✘ | √ | √ | √ | +| Identify magic code \(8197\) by copy & paste in mobile | ✘ | √ | √ | ✘ | +| Identify magic code \(8197\) by programming | ✘ | ✘ | ✘ | ✘ | +| Identify two contacts with the same roomAlias by \[You were mentioned\] tip | ✘ | ✘ | √ | √ | + +### 示例 + +```javascript +const contactList = await message.mention() +console.log(contactList) +``` + +### message.mentionSelf\(\) ⇒ `Promise ` + +获取机器人是否在群里被@ 了。 +是被@了，return`true` + +### 示例 + +```javascript +if (await message.mentionSelf()) { + console.log('this message were mentioned me! [You were mentioned] tip ([有人@我]的提示)') +} +``` + +### message.forward\(to\) ⇒ `Promise ` + +转发收到的消息。 + +| Param | Type | Description | +| :--- | :--- | :--- | +| to (Recipient) | `Sayable` \| `Array` |Room 或者 Contact。指的是收消息方。 | + +### 示例 + +```javascript +const bot = new Wechaty() +bot +.on('message', async message => { + const room = await bot.Room.find({topic: 'wechaty'}) + if (room) { + await message.forward(room) + console.log('forward this message to wechaty room!') + } +}) +.start() +``` + +### message.date\(\) ⇒ `Date` + +消息发送的时间。 + +### message.age\(\) ⇒ `number` + +消息的时差。 +例如： 消息在`8:43:01`发送的，当我们在wechaty 上收到消息的时候，时间是`8:43:15`,那么 age\(\) 为 `8:43:15 - 8:43:01 = 14 (seconds)`。 + +### message.toFileBox\(\) ⇒ `Promise ` + +从消息中提取多媒体文件并把它 存入到FileBox 里面。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +### message.toContact\(\) ⇒ `Promise ` + +提取转发的微信好友名片内容，并封装成Contact 类型。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +### message.toUrlLink\(\) ⇒ `Promise ` + +该方法从消息中提取Url链接，并将其封装到UrlLink类中。 +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +## 静态方法 + +### Message.find\(\) ⇒ `Promise ` + +在缓存中找消息。 + +### Message.findAll\(\) ⇒ `Promise ` + +在缓存中找消息。 diff --git a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/overview.mdx b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/overview.mdx new file mode 100644 index 00000000000..e6014d9a0fe --- /dev/null +++ b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/overview.mdx @@ -0,0 +1,25 @@ +--- +slug: /api/ +title: Wechaty API +sidebar_label: 'API：简介' +--- + +import TOCInline from '@theme/TOCInline' +export const Toc = () => + + + + +## Wechaty API + +API—应用程序编程接口是为其他软件服务提供服务的软件接口。Wechaty API是一个非常易于导入的API，允许用户尽可能使用Wechaty的所有功能。本文档概述Wechaty API。 + +## 上手 + +以下是一个最简单上手的示例代码： + +## ES6/TypeScript + +```js +import { WechatyBuilder } from 'wechaty' +``` \ No newline at end of file diff --git a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room-invitation.md b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room-invitation.md new file mode 100644 index 00000000000..1eab7f6f17b --- /dev/null +++ b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room-invitation.md @@ -0,0 +1,74 @@ +--- +title: Room Invitation +--- + +## Room Invitation + +自动通过入群邀请。 + +| 实例方法 | 返回类型 | +|----------------|---------------| +| accept\(\) | `Promise` | +| inviter\(\) | `Promise`(Contact) | +| topic\(\) | `Promise` (String) | +| date\(\) | `Promise` (Date) | +| age\(\) | `Promise` (Number) | + +### roomInvitation.accept\(\) ⇒ `Promise ` + +自动通过入群邀请。 + +#### 示例 + +```javascript +const bot = new Wechaty() +bot.on('room-invite', async roomInvitation => { + try { + console.log(`received room-invite event.`) + await roomInvitation.accept() + } catch (e) { + console.error(e) + } +}) +.start() +``` + +### roomInvitation.inviter\(\) ⇒ `Promise ` + +获取发送入群邀请的联系人。 + +#### 示例 + +```javascript +const bot = new Wechaty() +bot.on('room-invite', async roomInvitation => { + const inviter = await roomInvitation.inviter() + const name = inviter.name() + console.log(`received room invitation event from ${name}`) +}) +.start() +``` + +### roomInvitation.topic\(\) ⇒ `Promise ` + +获取需要进的群的群名称。 + +#### 示例 + +```javascript +const bot = new Wechaty() +bot.on('room-invite', async roomInvitation => { + const topic = await roomInvitation.topic() + console.log(`received room invitation event from room ${topic}`) +}) +.start() +``` + +### roomInvitation.date\(\) ⇒ `Promise ` + +获取发送入群邀请的时间。 + +### roomInvitation.age\(\) ⇒ `Promise ` + +获取入群邀请的时间间隔。 +例如：入群邀请的发送时间在`8:43:15`, 当我们在Wechaty 上收到这个信息的时间是`8:43:01`, 那么age\(\)的值为： `8:43:15 - 8:43:01 = 14 (seconds)` diff --git a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room.md b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room.md new file mode 100644 index 00000000000..2e723f4352a --- /dev/null +++ b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room.md @@ -0,0 +1,589 @@ +--- +title: Room +--- + +## Class + +### Room + +所有的微信群都会被封装成 Room 类。 + +[Examples/Room-Bot](https://github.com/wechaty/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/room-bot.ts) + +#### Properties + +| 名称 | 类型 | 描述 | +| :--- | :--- | :--- | +| id | `string` | 获取群ID。这个ID 是否是永久不变的ID 取决于使用哪一个puppet，具体 查看puppet兼容性清单，参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) | + +## Global class `Room` + +### 实例方法 + +| 实例方法 | 返回类型 | +|-----------------------------------------------------|-------------------| +| sync() | `Promise` | +| say(text 或 Contact 或 File 或 Url, ...mentionList) | `Promise` | +| on(event, listener) | `Room` | +| add(contact) | `Promise` | +| del(contact) | `Promise` | +| quit() | `Promise` | +| topic(newTopic) | `Promise` | +| announce(text) | `Promise` | +| qrcode() | `Promise` | +| alias(contact) | `Promise` | +| has(contact) | `Promise` | +| memberAll(query) | `Promise` | +| member(queryArg) | `Promise` | +| owner() | `Contact 或 null` | +| avatar() | `Promise` | + +### 静态方法 + +| 静态方法 | 返回类型 | +|---------------------------|--------------------------| +| create(contactList,topic) | `Promise ` | +| findAll(query) | `Promise` | +| find(query) | `Promise 或 null` | + +### room.sync\(\) ⇒ `Promise ` + +强制加载群的数据，从底层API 重新加载数据。 + +#### 示例 + +```javascript +await room.sync() +``` + +### room.say\(text 或 Contact 或 File 或 UrlLink 或 MiniProgram, ...mentionList\) ⇒ `Promise ` + +在群内发消息，如果设置了 ...mentionList 参数，机器人在群内发送消息的时候还会@这些联系人。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +| Param | Type | Description | +| :--- | :--- | :--- | +| text 或 Contact 或 File 或 UrlLink 或 MiniProgram | `string` \| `Contact` \| `FileBox` \| `UrlLink` \| `MiniProgram` | 群内发送text或者media file或者链接。可以通过 [FileBox](https://www.npmjs.com/package/file-box) 来发送文件。 | +| ...mentionList | `Contact []` | 可选参数，当设置这个参数的时候，在群内发送文本消息会@这些联系人。 | + +#### 示例 + +```javascript +import { FileBox } from 'file-box' +import { + Wechaty, + UrlLink, + MiniProgram, +} from 'wechaty' + +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'wechaty'}) + +// 1. 在Room发短信 + +await room.say('Hello world!') + +// 2. 在Room发文件 + +import { FileBox } from 'file-box' +const fileBox1 = FileBox.fromUrl('https://wechaty.github.io/wechaty/images/bot-qr-code.png') +const fileBox2 = FileBox.fromLocal('/tmp/text.txt') +await room.say(fileBox1) +await room.say(fileBox2) + +// 3. 在room发contact card + +const contactCard = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of the room member +await room.say(contactCard) + +// 4. 在room发短信和@mention contact + +const members = await room.memberAll() // all members in this room +const someMembers = members.slice(0, 3); +await room.say('Hello world!', ...someMembers) + +// 5. 在room发链接 + +const linkPayload = new UrlLink({ + description : 'WeChat Bot SDK for Individual Account, Powered by TypeScript, Docker, and Love', + thumbnailUrl: 'https://avatars0.githubusercontent.com/u/25162437?s=200&v=4', + title : 'Welcome to Wechaty', + url : 'https://github.com/wechaty/wechaty', +}) +await room.say(linkPayload) + +// 6. 发小程序 (仅 `wechaty-puppet-macpro`支持) + +const miniProgram = new MiniProgram ({ + appid : 'gh_0aa444a25adc', + title : '我正在使用Authing认证身份，你也来试试吧', + pagePath : 'routes/explore.html', + description : '身份管家', + thumbUrl : '30590201000452305002010002041092541302033d0af802040b30feb602045df0c2c5042b777875706c6f61645f31373533353339353230344063686174726f6f6d3131355f313537363035393538390204010400030201000400', + thumbKey : '42f8609e62817ae45cf7d8fefb532e83', +}); +await room.say(miniProgram); +``` + +### room.on\(event, listener\) ⇒ `this` + +Return `this` - - Room for chain. + +| Param | Type | Description | +| :--- | :--- | :--- | +| event | `RoomEventName` | 群内事件触发 | +| listener | `RoomEventFunction` | 取决于是哪一个事件 | + +#### 示例 \(Event:join \) + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your wechat +if (room) { + room.on('join', (room, inviteeList, inviter) => { + const nameList = inviteeList.map(c => c.name()).join(',') + console.log(`Room got new member ${nameList}, invited by ${inviter}`) + }) +} +``` + +#### 示例 \(Event:leave \) + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your wechat +if (room) { + room.on('leave', (room, leaverList) => { + const nameList = leaverList.map(c => c.name()).join(',') + console.log(`Room lost member ${nameList}`) + }) +} +``` + +#### 示例 \(Event:topic \) + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your wechat +if (room) { + room.on('topic', (room, topic, oldTopic, changer) => { + console.log(`Room topic changed from ${oldTopic} to ${topic} by ${changer.name()}`) + }) +} +``` + +#### 示例 \(Event:invite \) + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your wechat +if (room) { + room.on('invite', roomInvitation => roomInvitation.accept()) +} +``` + +### room.add\(contact\) ⇒ `Promise ` + +邀请好友加入群聊。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) +> +> 参照 [网页版微信封闭群界面](https://github.com/wechaty/wechaty/issues/1441) + +| Param | Type | +| :--- | :--- | +| contact | `Contact` | + +#### 示例 + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any contact in your wechat +const room = await bot.Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat +if (room) { + try { + await room.add(contact) + } catch(e) { + console.error(e) + } +} +``` + +### room.del\(contact\) ⇒ `Promise ` + +将好友移出群聊，这个功能仅在机器人是群主的时候会生效。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) +> +> 参照 [网页版微信封闭群界面](https://github.com/wechaty/wechaty/issues/1441) + +| Param | Type | +| :--- | :--- | +| contact | `Contact` | + +#### 示例 + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat +const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any room member in the room you just set +if (room) { + try { + await room.del(contact) + } catch(e) { + console.error(e) + } +} +``` + +### room.quit\(\) ⇒ `Promise ` + +机器人主动退群。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +#### 示例 + +```javascript +await room.quit() +``` + +### room.topic\(\[newTopic\]\) ⇒ `Promise ` + +设置 / 获取 群名称。 + +| Param | Type | Description | +| :--- | :--- | :--- | +| \[newTopic\] | `string` | If set this para, it will change room topic. | + +#### 示例 \(当你在群里说话的时候，打印群名称\) + +```javascript +const bot = new Wechaty() +bot +.on('message', async m => { + const room = m.room() + if (room) { + const topic = await room.topic() + console.log(`room topic is : ${topic}`) + } +}) +.start() +``` + +#### 示例 _\(当你在群内说话的时候，机器人修改群名称\)_ + +```javascript +const bot = new Wechaty() +bot +.on('message', async m => { + const room = m.room() + if (room) { + const oldTopic = await room.topic() + await room.topic('change topic to wechaty!') + console.log(`room topic change from ${oldTopic} to ${room.topic()}`) + } +}) +.start() +``` + +### room.announce\(\[text\]\) ⇒ `Promise ` + +设置 / 获取 群公告。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +| Param | Type | Description | +| :--- | :--- | :--- | +| \[text\] | `string` | If set this para, it will change room announce. | + +#### 示例 \(当你在群里说话的时候，打印群公告\) + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'your room'}) +const announce = await room.announce() +console.log(`room announce is : ${announce}`) +``` + +#### 示例 \(当你在群里说话的时候，修改群公告\) + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'your room'}) +const oldAnnounce = await room.announce() +await room.announce('change announce to wechaty!') +console.log(`room announce change from ${oldAnnounce} to ${room.announce()}`) +``` + +### room.qrcode\(\) ⇒ `Promise ` + +获取群二维码，用户可以通过扫描这个二维码加入群聊。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +### room.alias\(contact\) ⇒ `Promise ` + +获取这个联系人在群内的群昵称。 + +| Param | Type | +| :--- | :--- | +| contact | `Contact` | + +#### 示例 + +```javascript +const bot = new Wechaty() +bot +.on('message', async m => { + const room = m.room() + const contact = m.from() + if (room) { + const alias = await room.alias(contact) + console.log(`${contact.name()} alias is ${alias}`) + } +}) +.start() +``` + +### room.has\(contact\) ⇒ `Promise ` + +检查群内是否有这个群成员。 + +| Param | Type | +| :--- | :--- | +| contact | `Contact` | + +#### 示例 _\(检查'lijiarui'是否在'wechaty'群\)_ + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of contact in your wechat +const room = await bot.Room.find({topic: 'wechaty'}) // change 'wechaty' to any of the room in your wechat +if (contact && room) { + if (await room.has(contact)) { + console.log(`${contact.name()} is in the room wechaty!`) + } else { + console.log(`${contact.name()} is not in the room wechaty!`) + } +} +``` + +### room.memberAll\(\[query\]\) ⇒ `Promise ` + +根据 query 获取群内所有的群成员列表。如果没有设置query，返回所有的群成员信息。 + +#### 定义 + +* `name` 微信联系人自己设置的昵称，等于`Contact.name()` +* `roomAlias` 微信联系人自己在群内设置的昵称 +* `contactAlias` 机器人给微信联系人设置的，等于`Contact.alias()` + +**Kind**: `Room`实例方法 + +| Param | Type | Description | +| :--- | :--- | :--- | +| \[query\] | `RoomMemberQueryFilter` \| `string` | 1. RoomMemberQueryFilter 可通过 name, roomAlias, contactAlias 查找指定的群成员。 2. 当memberAll(name) 的参数为string 类型的时候, 返回所有找到的群成员。这里面的name 包括上面定义的name, roomAlias, contactAlias。 | + +#### 示例 + +```javascript +const memberList: Conatct[] = await room.memberAll() +console.log(`room all member list: `, memberList) + +const memberContactList: Conatct[] = await room.memberAll(`abc`) +console.log(`contact list with all name, room alias, alias are abc:`, memberContactList) +``` + +### room.member\(queryArg\) ⇒ `Promise ` + +根据 query 获取群内的群成员。 + +| Param | Type | Description | +| :--- | :--- | :--- | +| queryArg | [`RoomMemberQueryFilter`](room.md#RoomMemberQueryFilter) \| `string` | RoomMemberQueryFilter 可通过 name, roomAlias, contactAlias 查找指定的群成员。 | + +#### 示例 \(用名字找member\) + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat +if (room) { + const member = await room.member('lijiarui') // change 'lijiarui' to any room member in your wechat + if (member) { + console.log(`wechaty room got the member: ${member.name()}`) + } else { + console.log(`cannot get member in wechaty room!`) + } +} +``` + +#### 示例 \(用MemberQueryFilter找member\) + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const room = await bot.Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat +if (room) { + const member = await room.member({name: 'lijiarui'}) // change 'lijiarui' to any room member in your wechat + if (member) { + console.log(`wechaty room got the member: ${member.name()}`) + } else { + console.log(`cannot get member in wechaty room!`) + } +} +``` + +### room.owner\(\) ⇒ `Contact` \| `null` + +获取群主的信息。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +#### 示例 + +```javascript +const owner = room.owner() +``` + +### room.avatar\(\) ⇒ `Promise ` + +获取群头像的信息。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +#### 示例 + +```javascript +const owner = room.avatar() +``` + +## 静态方法 + +### Room.create\(contactList, \[topic\]\) ⇒ `Promise ` + +创建群聊。 + +| Param | Type | +| :--- | :--- | +| contactList | `Array` | +| \[topic\] | `string` | + +#### 示例 _\(创造新群拉'lijiarui'和'juxiaomi', 群名称是 'ding - created'\)_ + +```javascript +const helperContactA = await Contact.find({ name: 'lijiarui' }) // change 'lijiarui' to any contact in your wechat +const helperContactB = await Contact.find({ name: 'juxiaomi' }) // change 'juxiaomi' to any contact in your wechat +const contactList = [helperContactA, helperContactB] +console.log('Bot', 'contactList: %s', contactList.join(',')) +const room = await Room.create(contactList, 'ding') +console.log('Bot', 'createDingRoom() new ding room created: %s', room) +await room.topic('ding - created') +await room.say('ding - created') +``` + +### Room.findAll\(\[query\]\) ⇒ `Promise ` + +通过 {topic: string \| RegExp}, 查找群，返回找到的所有群的数组。 + +| Param | Type | +| :--- | :--- | +| \[query\] | `RoomQueryFilter` | + +#### 示例 + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in +const roomList = await bot.Room.findAll() // get the room list of the bot +const roomList = await bot.Room.findAll({topic: 'wechaty'}) // find all of the rooms with name 'wechaty' +``` + +### Room.find\(query\) ⇒ `Promise ` + +通过 {topic: string \| RegExp}，查找群，如果找到多个群，返回找到的第一个群。 + +| Param | Type | +| :--- | :--- | +| query | [`RoomQueryFilter`](room.md#RoomQueryFilter) | + +#### 示例 + +```javascript +const bot = new Wechaty() +await bot.start() +// after logged in... +const roomList = await bot.Room.find() +const roomList = await bot.Room.find({topic: 'wechaty'}) +``` + +## Typedefs + +## RoomQueryFilter + +查找群的过滤器，{topic: string \| RegExp}. + +### Properties + +| 名字 | 类型 | +| :--- | :--- | +| topic | `string` | + +## RoomEventName + +群事件的类型 + +### Properties + +| 名字 | 类型 | 描述 | +| :--- | :--- | :--- | +| join | `string` | 当有人入群的时候，会触发这个事件。 | +| topic | `string` | 当有人修改群名称的时候，会触发这个事件。 | +| leave | `string` | 当有人离群的时候，会触发这个事件。如果是用户主动离群，是无法获取到这个事件的。 | + +## RoomEventFunction + +### Properties + +| Name | Type | Description | +| :--- | :--- | :--- | +| room-join | `function` | \(this: Room, inviteeList: Contact\[\] , inviter: Contact\) => void | +| room-topic | `function` | \(this: Room, topic: string, oldTopic: string, changer: Contact\) => void | +| room-leave | `function` | \(this: Room, leaver: Contact\) => void | + +## RoomMemberQueryFilter + +通过Room.member\(\)搜索群成员的过滤器。 + +### Properties + +| Name | Type | Description | +| :--- | :--- | :--- | +| name | `string` | 通过用户的昵称查找群成员，这里面的name 等于`Contact.name()` | +| roomAlias | `string` | 通过用户设置的群昵称查找群成员 | +| contactAlias | `string` | 通过机器人给用户设置的备注查找群成员，这里面的contactAlias 等于 `Contact.alias()`. [更多](https://github.com/wechaty/wechaty/issues/365) | diff --git a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty-class.md b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty-class.md new file mode 100644 index 00000000000..c2035d169d1 --- /dev/null +++ b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty-class.md @@ -0,0 +1,18 @@ +## Classes + +### Wechaty + +Wechaty 的构造类用于构造 Wechaty 实例。 + +一个Wechaty Bot 代表着一个微信的客户端，他取决于你具体使用哪一个Puppet。 + +* **web-WeChat** - 当使用Puppet-Puppeteer 或 Puppet-wechat4u +* **iPad-WeChat** - 当使用Puppet-padchat +* **iOS-WeChat** - 当使用Puppet-ioscat + +了解puppet及其用途，请访问以下链接- + +### [What is a Puppet in Wechaty](https://github.com/wechaty/wechaty-getting-started/wiki/FAQ-EN#31-what-is-a-puppet-in-wechaty)? + +> 如果您想知道如何发送消息，请参阅Message +> 如果您想了解如何获得联系，请参阅Contact diff --git a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty.md b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty.md index 109af99c209..7c8944c4250 100644 --- a/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty.md +++ b/docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty.md @@ -2,63 +2,378 @@ title: Wechaty --- -- [Class: WechatyBuilder](#class-wechatybuilder) - - [Static method: WechatyBuilder.build(options?: WechatyOptions)](#static-method-wechatybuilderbuildoptions-wechatyoptions) - - [Static method: WechatyBuilder.singleton(options?: WechatyOptions)](#static-method-wechatybuildersingletonoptions-wechatyoptions) - - [Static method: WechatyBuilder.valid(target: any)](#static-method-wechatybuildervalidtarget-any) -- [Class: Wechaty](#class-wechaty) - - [wechaty.start()](#wechatystart) - - [wechaty.say()](#wechatysaysayable-sayable) - - [wechaty.publish(post: PostInterface)](#wechatypublishpost-postinterface) +一个Wechaty Bot代表着一个微信的客户端，他取决于你具体使用哪一个Puppet。 -## Class: WechatyBuilder +## Classes -Wechaty 的构造类用于构造 Wechaty 实例。 +一个Wechaty Bot代表着一个微信的客户端，他取决于你具体使用哪一个Puppet。 -### Static method: WechatyBuilder.build(options?: WechatyOptions) +* **web-wechat** - 当使用Puppet-Puppeteer 或 Puppet-wechat4u +* **ipad-wechat** - 当使用Puppet-padchat +* **ios-wechat** - 当使用Puppet-ioscat -返回 Wechaty 实例。 +了解puppet及其用途，请访问以下链接- -根据 option 构造一个 Wechaty 实例。 +* [What is a Puppet in Wechaty](https://github.com/wechaty/wechaty-getting-started/wiki/FAQ-EN#31-what-is-a-puppet-in-wechaty) -示例: +> 如果您想知道如何发送消息，请参阅Message +> 如果您想了解如何获得联系，请参阅Contact -```ts -import { WechatyBuilder } from 'wechaty' +**Kind**: global class -WechatyBuilder.build(options) // 在单例模式使用 instance() - .on('scan', (url, status) => console.log(`Scan QR Code to login: ${status}\n${url}`)) - .on('login', user => console.log(`User ${user} logged in`)) - .on('message', message => console.log(`Message: ${message}`)) - .start() +* Wechaty + * new Wechaty\(\[options\]\) + * _实例_ + * .on\(event, listener\) ⇒ `Wechaty` + * .start\(\) ⇒ `Promise ` + * .stop\(\) ⇒ `Promise ` + * .logout\(\) ⇒ `Promise ` + * .logonoff\(\) ⇒ `boolean` + * .userSelf\(\) ⇒ `ContactSelf` + * .say\(textOrContactOrFileOrUrl\) ⇒ `Promise ` + * _static_ + * .instance\(\[options\]\) + +### new Wechaty\(\[options\]\) + +创建一个 Wechaty 的实例。 + +| Param | Type | Default | +| :--- | :--- | :--- | +| \[options\] | `WechatyOptions` | `{}` | + +**Example** _\(世界上最短的对话机器人代码\)_ + +```javascript +import { Wechaty } from 'wechaty' +const bot = new Wechaty() +bot.on('scan', (qrcode, status) => console.log(['https://api.qrserver.com/v1/create-qr-code/?data=',encodeURIComponent(qrcode),'&size=220x220&margin=20',].join(''))) +bot.on('login', user => console.log(`User ${user} logined`)) +bot.on('message', message => console.log(`Message: ${message}`)) +bot.start() +``` + +### wechaty.on\(event, listener\) ⇒ `Wechaty` + +当机器人收到消息，会触发一个事件，一些简单的事件介绍如下： + +* **scan**: 当机器人需要扫码登录的时候，会触发这个事件，当手机扫码登录后，机器人就可以登录进去了。 +* **login**: 当机器人登陆成功后，会触发这个事件。 +* **logout**: 当机器人退出登陆的时候，会触发到这个事件。 +* **message**: 当有新消息的时候会触发这个事件。 + +更多在 WechatyEventName + +**Kind**: `Wechaty`的实例方法 +**Returns**: `Wechaty` + +| Param | Type | Description | +| :--- | :--- | :--- | +| event | `WechatyEventName` | Emit WechatyEvent | +| listener | `WechatyEventFunction` | Depends on the WechatyEvent | + +**示例** _\(Event:scan\)_ + +```javascript +bot.on('scan', (url, code) => { + console.log(`[${code}] Scan ${url} to login.` ) +}) +``` + +**示例** _\(Event:login \)_ + +```javascript +bot.on('login', (user) => { + console.log(`user ${user} login`) +}) +``` + +**示例** _\(Event:logout \)_ + +```javascript +bot.on('logout', (user) => { + console.log(`user ${user} logout`) +}) +``` + +**示例** _\(Event:message \)_ + +```javascript +wechaty.on('message', (message) => { + console.log(`message ${message} received`) +}) +``` + +**示例** _\(Event:friendship \)_ + +```javascript +bot.on('friendship', async (friendship) => { + const contact = friendship.contact() + if (friendship.type() === bot.Friendship.Type.Receive) { // 1.接收新友谊请求 + let result = await friendship.accept() + if (result) { + console.log(`Request from ${contact.name()} is accept succesfully!`) + } else { + console.log(`Request from ${contact.name()} failed to accept!`) + } + } else if (friendship.type() === bot.Friendship.Type.Confirm) { // 2.确认友谊请求 + console.log(`New friendship confirmed with ${contact.name()}`) + } +}) +``` + +**示例** _\(Event:room-join \)_ + +```javascript +bot.on('room-join', async (room, inviteeList, inviter) => { + const nameList = inviteeList.map(c => c.name()).join(',') + console.log(`Room ${await room.topic()} got new member ${nameList}, invited by ${inviter}`) +}) +``` + +**示例** _\(Event:room-leave \)_ + +```javascript +bot.on('room-leave', async (room, leaverList, remover) => { + const nameList = leaverList.map(c => c.name()).join(',') + console.log(`Room ${await room.topic()} lost member ${nameList}, the remover is: ${remover}`) +}) +``` + +**示例** _\(Event:room-topic \)_ + +```javascript +bot.on('room-topic', async (room, topic, oldTopic, changer) => { + console.log(`Room ${await room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`) +}) +``` + +**示例** _\(Event:room-invite \)_ + +```javascript +bot.on('room-invite', async roomInvitation => { + try { + console.log(`received room-invite event.`) + await roomInvitation.accept() + } catch (e) { + console.error(e) + } +} +``` + +**示例** _\(Event:error \)_ + +```javascript +bot.on('error', (error) => { + console.error(error) +}) +``` + +### wechaty.start\(\) ⇒ `Promise ` + +启动机器人 +> 备注：机器人所有的操作必须在这个函数执行完成之后。 + +**Kind**: `Wechaty`的实例方法 + +#### 示例 + +```javascript +await bot.start() ``` -### Static method: WechatyBuilder.singleton(options?: WechatyOptions) +### wechaty.stop\(\) ⇒ `Promise ` + +停止机器人 + +**Kind**: `Wechaty`的实例方法 + +#### 示例 + +```javascript +await bot.stop() +``` + +### wechaty.logout\(\) ⇒ `Promise ` + +退出机器人 + +**Kind**: `Wechaty`的实例方法 + +#### 示例 + +```javascript +await bot.logout() +``` + +### wechaty.logonoff\(\) ⇒ `boolean` + +获取机器人logon/logoff 的状态 + +**Kind**: `Wechaty`的实例方法 + +#### 示例 + +```javascript +if (bot.logonoff()) { + console.log('Bot logined') +} else { + console.log('Bot not logined') +} +``` + +### wechaty.userSelf\(\) ⇒ `ContactSelf` + +获取当前机器人的所有信息 + +**Kind**: `Wechaty`的实例方法 + +#### 示例 + +```javascript +const contact = bot.userSelf() +console.log(`Bot is ${contact.name()}`) +``` + +### wechaty.say\(text或Contact或File或Url\) ⇒ `Promise ` + +机器人自己给自己发消息。 + +> 备注: 这个方法是否能实现，取决于用的是什么Puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) + +**Kind**: `Wechaty`的实例方法 + +| Param | Type | Description | +| :--- | :--- | :--- | +| textOrContactOrFileOrUrl | `string` \| `Contact` \| `FileBox` \| `UrlLink` | 发送文本、联系人名片或者文件给机器人自己。可以使用 [FileBox](https://www.npmjs.com/package/file-box) 来发送文件 | + +#### 示例 + +```javascript +const bot = new Wechaty() +await bot.start() +// 登录后 + +// 1. 机器人为自己发消息 +await bot.say('hello!') + +// 2. 机器人为自己发contact +const contact = bot.Contact.load('contactId') +await bot.say(contact) + +// 3. 机器人为自己发照片url +import { FileBox } from 'file-box' +const fileBox = FileBox.fromUrl('https://wechaty.github.io/wechaty/images/bot-qr-code.png') +await bot.say(fileBox) + +// 4. 机器人为自己发文件 +import { FileBox } from 'file-box' +const fileBox = FileBox.fromFile('/tmp/text.jpg') +await bot.say(fileBox) + +// 5. 机器人为自己发链接 +const linkPayload = new UrlLink({ + description : 'WeChat Bot SDK for Individual Account, Powered by TypeScript, Docker, and Love', + thumbnailUrl: 'https://avatars0.githubusercontent.com/u/25162437?s=200&v=4', + title : 'Welcome to Wechaty', + url : 'https://github.com/wechaty/wechaty', +}) +await bot.say(linkPayload) +``` + +### Wechaty.instance\(\[options\]\) + +获取Wechaty的全局实例。 + +**Kind**: `Wechaty`的静态方法 + +| Param | Type | Default | +| :--- | :--- | :--- | +| \[options\] | `WechatyOptions` | `{}` | + +#### 示例 + +```javascript +import { Wechaty } from 'wechaty' + +Wechaty.instance() // Global instance +.on('scan', (url, code) => console.log(`Scan QR Code to login: ${code}\n${url}`)) +.on('login', user => console.log(`User ${user} logined`)) +.on('message', message => console.log(`Message: ${message}`)) +.start() +``` + +## PuppetName + +Wechaty中的Puppet是一个用于实现协议插件的抽象类。插件是帮助微信控制微信的组件\(这就是我们称之为puppet的原因\). 这些插件被命名为PuppetXXX，例如： + +* [PuppetPuppeteer](https://github.com/wechaty/wechaty-puppet-puppeteer) +* [PuppetPadchat](https://github.com/lijiarui/wechaty-puppet-padchat) -返回 Wechaty 实例。 +**Kind**: global typedef +**Properties** -根据 option 构造一个单例模式的 Wechaty 实例。 +| 名字 | 类型 | 描述 | +| :--- | :--- | :--- | +| wechat4u | `string` | 默认的puppet，使用 [wechat4u](https://github.com/nodeWechat/wechat4u) 来控制 [WeChat Web API](https://wx.qq.com/) | +| padchat | `string` | 使用WebSocket 协议链接一个协议服务器，来控制iPad 微信。 | +| puppeteer | `string` | 使用 [google puppeteer](https://github.com/GoogleChrome/puppeteer) 来控制 [WeChat Web API](https://wx.qq.com/) | +| mock | `string` | 为单元测试提供模拟调用的Puppet | -### Static method: WechatyBuilder.valid(target: any) +## WechatyOptions -返回 target 是否是 Wechaty 实例。 +创建 Wechaty 实例的可选参数类型。 -## Class: Wechaty +**Kind**: global typedef +**Properties** -主要的 bot 类。 +| 名字 | 类型 | 描述 | +| :--- | :--- | :--- | +| profile | `string` | Wechaty 机器人的名称. 当你按照下面的方式设置的时候： `new Wechaty({profile: 'wechatyName'})` 他会自动生成一个叫做`wechatyName.memory-card.json`的文件 。这个文件会存储机器人的登陆信息。如果这个文件有效，启动wechaty的时候，你不需要扫码登陆就能自动登陆机器人\(只对wechaty-puppet-padchat有效\)。 这个名字在启动机器人的时候，是可以通过环境变量WECHATY_NAME设置的，如：`WECHATY_NAME="wechatyName" node bot.jsWechaty` [更多](https://github.com/wechaty/wechaty/issues/2049) | +| puppet | `PuppetModuleName` \| `Puppet` | 使用puppet名称指定相关puppet或者直接传入puppet实例作为Wechaty底层插件， 了解更多puppet信息 | +| puppetOptions | `Partial.` | Puppet TOKEN | +| ioToken | `string` | Io TOKEN | -一个 bot 是指一个代表了某个特定即时通讯软件的实力，根据使用的 puppet 不同而有所区别。 +## WechatyEventName -### wechaty.start() +Wechaty 事件的类型 -启动 bot 。 +**Kind**: global typedef +**Properties** -### wechaty.say(sayable: Sayable) +| Name | Type | Description | +| :--- | :--- | :--- | +| error | `string` | 当机器人内部出错的时候会触发error 事件。 | +| login | `string` | 当机器人成功登陆后，会触发login 事件，并会在事件中传递当前登陆机器人的信息。 | +| logout | `string` | 当机器人检测到登出的时候，会触发logout 事件，并会在事件中传递机器人的信息。 | +| heartbeat | `string` | 获取机器人的心跳。 | +| friendship | `string` | 当有人给机器人发好友请求的时候会触发这个事件。 | +| message | `string` | 当机器人收到消息的时候会触发这个事件。 | +| ready | `string` | 当所有数据加载完成后，会触发这个事件。在wechaty-puppet-padchat 中，它意味着已经加载完成Contact 和Room 的信息。 | +| room-join | `string` | 当有人进入微信群的时候会触发这个事件。机器人主动进入某个微信群，t那个样会触发这个事件。 | +| room-topic | `string` | 当有人修改群名称的时候会触发这个事件。 | +| room-leave | `string` | 当机器人把群里某个用户移出群聊的时候会触发这个时间。用户主动退群是无法检测到的。 | +| room-invite | `string` | 当收到群邀请的时候，会触发这个事件。具体请RoomInvitation | +| scan | `string` | 当机器人需要扫码登陆的时候会触发这个事件。 建议你安装 qrcode-terminal\(运行 npm install qrcode-terminal\)这个包，这样你可以在命令行中直接看到二维码。 | -对 bot 的当前用户发送消息。 +## WechatyEventFunction -### wechaty.publish(post: PostInterface) +Wechaty 事件的函数 -返回一个 postInterface 或者 void ，根据 puppet 不同有所区别。 +**Kind**: global typedef +**Properties** -发送一条朋友圈，详情请参考 Post 部分。（编写中） +| 名字 | 类型 | 描述 | +| :--- | :--- | :--- | +| error | `function` | \(this: Wechaty, error: Error\) => void callback function | +| login | `function` | \(this: Wechaty, user: ContactSelf\)=> void | +| logout | `function` | \(this: Wechaty, user: ContactSelf\) => void | +| scan | `function` | \(this: Wechaty, url: string, code: number\) => void | +| heartbeat | `function` | \(this: Wechaty, data: any\) => void | +| friendship | `function` | \(this: Wechaty, friendship: Friendship\) => void | +| message | `function` | \(this: Wechaty, message: Message\) => void | +| ready | `function` | \(this: Wechaty\) => void | +| room-join | `function` | \(this: Wechaty, room: Room, inviteeList: Contact\[\], inviter: Contact\) => void | +| room-topic | `function` | \(this: Wechaty, room: Room, newTopic: string, oldTopic: string, changer: Contact\) => void | +| room-leave | `function` | \(this: Wechaty, room: Room, leaverList: Contact\[\]\) => void | +| room-invite | `function` | \(this: Wechaty, room: Room, leaverList: Contact\[\]\) => void | diff --git a/package.json b/package.json index cf5907342f5..223b00fa9f6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "wechaty-docusaurus", - "version": "0.11.7", + "version": "0.11.11", "description": "Wechaty Official Website for Documentations", "private": true, "type": "module",