Kivi API/工具函数 文档
<h1>Kivi API/工具函数 文档</h1>
<p>TIP</p>
<p>大部分都是工具函数，ctx.bot 是 icqq(oicq)的 client 实例，更多 API 参考 <a href="https://www.showdoc.com.cn/p/f57926ae832fbe6dcb2ffdeb5fd48c0c">Bot API</a></p>
<h2>核心 API</h2>
<h3>handle</h3>
<h4>注册事件处理器</h4>
<p>typescript</p>
<pre><code>declare function handle&lt;EventName extends keyof oicq.EventMap&gt;(
eventName: EventName,
handler: oicq.EventMap[EventName]
): any;</code></pre>
<h3>hasRight</h3>
<h4>是否有权限，即：主人或管理员</h4>
<p>typescript</p>
<pre><code>declare function hasRight(
id: number | { sender: { user_id: number } }
): boolean;</code></pre>
<h3>isOwner</h3>
<h4>是否为主人</h4>
<p>typescript</p>
<pre><code>declare function isOwner(id: number | { sender: { user_id: number } }): boolean;</code></pre>
<h3>isAdmin</h3>
<h4>是否为管理员</h4>
<p>typescript</p>
<pre><code>declare function isAdmin(id: number | { sender: { user_id: number } }): boolean;</code></pre>
<h3>http</h3>
<h4>用于发送 HTTP 请求的 axios 实例</h4>
<p>typescript</p>
<pre><code>declare const http: ReturnType&lt;typeof oicq.axios.create&gt;;</code></pre>
<h3>createVanilla</h3>
<h4>创建一个简单的状态管理器</h4>
<p>typescript</p>
<pre><code>declare function createVanilla&lt;T extends object&gt;(
initial: T
): {
mutate: T;
snapshot: () =&gt; Snapshot&lt;T&gt;;
subscribe(fn: (state: Snapshot&lt;T&gt;) =&gt; any): () =&gt; void;
};</code></pre>
<h2>加密与编码</h2>
<h3>md5</h3>
<h4>MD5 加密</h4>
<p>typescript</p>
<pre><code>declare function md5(text: BinaryLike, encoding: &quot;buffer&quot;): Buffer;
declare function md5(text: BinaryLike, encoding?: BinaryToTextEncoding): string;</code></pre>
<h3>base64Encode</h3>
<h4>Base64 编码</h4>
<p>typescript</p>
<pre><code>declare function base64Encode(str: string | number): string | number;</code></pre>
<h3>base64Decode</h3>
<h4>Base64 解码</h4>
<p>typescript</p>
<pre><code>declare function base64Decode(str: string): string;</code></pre>
<h2>数据处理</h2>
<h3>unique</h3>
<h4>数组去重</h4>
<p>typescript</p>
<pre><code>declare function unique&lt;T&gt;(array: T[]): T[];</code></pre>
<h3>ensureArray</h3>
<h4>确保值为数组</h4>
<p>typescript</p>
<pre><code>declare function ensureArray&lt;T&gt;(value: T | T[]): T[];</code></pre>
<h2>类型判断</h2>
<h3>isGroupMsg</h3>
<h4>是否是群消息</h4>
<p>typescript</p>
<pre><code>declare const isGroupMsg: (
event: AllMessageEvent
) =&gt; event is oicq.GroupMessageEvent;</code></pre>
<h3>isDiscussMsg</h3>
<h4>是否是讨论组消息</h4>
<p>typescript</p>
<pre><code>declare const isDiscussMsg: (
event: AllMessageEvent
) =&gt; event is oicq.DiscussMessageEvent;</code></pre>
<h3>isPrivateMsg</h3>
<h4>是否是私聊消息</h4>
<p>typescript</p>
<pre><code>declare const isPrivateMsg: (
event: AllMessageEvent
) =&gt; event is oicq.PrivateMessageEvent;</code></pre>
<h3>isBoolean</h3>
<h4>判断是否为布尔值</h4>
<p>typescript</p>
<pre><code>declare function isBoolean(val: unknown): val is boolean;</code></pre>
<h3>isNumber</h3>
<h4>判断是否为数字</h4>
<p>typescript</p>
<pre><code>declare function isNumber(val: unknown): val is number;</code></pre>
<h3>isString</h3>
<h4>判断是否为字符串</h4>
<p>typescript</p>
<pre><code>declare function isString(val: unknown): val is string;</code></pre>
<h3>isObject</h3>
<h4>判断是否为对象</h4>
<p>typescript</p>
<pre><code>declare function isObject(val: unknown): val is object;</code></pre>
<h3>isFunction</h3>
<h4>判断是否为函数</h4>
<p>typescript</p>
<pre><code>declare function isFunction&lt;T extends AnyFunc&gt;(val: unknown): val is T;</code></pre>
<h3>isDefined</h3>
<h4>判断是否定义</h4>
<p>typescript</p>
<pre><code>declare function isDefined&lt;T = unknown&gt;(val?: T): val is T;</code></pre>
<h3>noNullish</h3>
<h4>排除 null 和 undefined</h4>
<p>typescript</p>
<pre><code>declare function noNullish&lt;T&gt;(val: T | null): val is T;</code></pre>
<h2>时间与延时</h2>
<h3>wait</h3>
<h4>异步延时函数</h4>
<p>typescript</p>
<pre><code>declare function wait(ms: number): Promise&lt;void&gt;;</code></pre>
<h3>now</h3>
<h4>获取当前时间</h4>
<p>typescript</p>
<pre><code>declare function now(): number;</code></pre>
<h3>timestamp</h3>
<h4>获取当前时间戳</h4>
<p>typescript</p>
<pre><code>declare function timestamp(): number;</code></pre>
<h2>随机数</h2>
<h3>randomInt</h3>
<h4>生成随机整数</h4>
<p>typescript</p>
<pre><code>declare function randomInt(min: number, max: number): number;</code></pre>
<h3>randomItem</h3>
<h4>取数组内随机一项</h4>
<p>typescript</p>
<pre><code>declare function randomItem&lt;T = any&gt;(array: T[]): T;</code></pre>
<h2>工具函数</h2>
<h3>noop</h3>
<h4>空函数</h4>
<p>typescript</p>
<pre><code>declare function noop(): undefined;</code></pre>
<h3>clamp</h3>
<h4>限制数值在指定范围内</h4>
<p>typescript</p>
<pre><code>declare function clamp(n: number, min: number, max: number): number;</code></pre>
<h3>stringifyError</h3>
<h4>错误信息字符串格式化</h4>
<p>typescript</p>
<pre><code>declare function stringifyError(error: any): string;</code></pre>
<h3>qs</h3>
<h4>JS 对象转换成 <code>urlencoded</code> 格式字符串</h4>
<p>typescript</p>
<pre><code>declare function qs(obj: Record&lt;number | string, any&gt;): string;</code></pre>
<h2>图片处理</h2>
<h3>getQQAvatarLink</h3>
<h4>通过 QQ 号获取任意头像链接</h4>
<p>typescript</p>
<pre><code>declare function getQQAvatarLink(qq: number, size?: number): string;</code></pre>
<h3>getGroupAvatarLink</h3>
<h4>通过群号获取任意群头像链接</h4>
<p>typescript</p>
<pre><code>declare function getGroupAvatarLink(group: number, size?: number): string;</code></pre>
<h3>getImageUrl</h3>
<h4>获取消息中的图片链接</h4>
<p>typescript</p>
<pre><code>declare function getImageUrl(event: AllMessageEvent): string;</code></pre>
<h3>getQuoteImageUrl</h3>
<h4>获取引用回复的消息中的图片链接</h4>
<p>typescript</p>
<pre><code>declare function getQuoteImageUrl(event: AllMessageEvent): Promise&lt;string&gt;;</code></pre>
<h3>getMentionedImageUrl</h3>
<h4>获取消息提及的图片链接（消息或者引用消息）</h4>
<p>typescript</p>
<pre><code>declare function getMentionedImageUrl(event: AllMessageEvent): Promise&lt;string&gt;;</code></pre>
<h3>getImage</h3>
<h4>获取消息中的图片元素</h4>
<p>typescript</p>
<pre><code>declare function getImage(event: AllMessageEvent): oicq.ImageElem | null;</code></pre>
<h3>getFaceImage</h3>
<h4>获取消息中的图片元素</h4>
<p>typescript</p>
<pre><code>declare function getFaceImage(event: AllMessageEvent): oicq.BfaceElem | null;</code></pre>
<h3>getQuoteImage</h3>
<h4>获取引用回复的图片消息</h4>
<p>typescript</p>
<pre><code>declare function getQuoteImage(
event: AllMessageEvent
): Promise&lt;oicq.ImageElem | null&gt;;</code></pre>
<h3>getMentionedImage</h3>
<h4>获取消息提及的图片（消息或者引用消息）</h4>
<p>typescript</p>
<pre><code>declare function getMentionedImage(
event: AllMessageEvent
): Promise&lt;oicq.ImageElem | null&gt;;</code></pre>
<h2>消息处理</h2>
<h3>getText</h3>
<h4>获取消息中的文本内容</h4>
<p>typescript</p>
<pre><code>declare function getText(event: {
message: AllMessageEvent[&quot;message&quot;];
}): string;</code></pre>
<h3>getQuoteText</h3>
<h4>获取回复的消息中的文本内容</h4>
<p>typescript</p>
<pre><code>declare function getQuoteText(event: AllMessageEvent): Promise&lt;string&gt;;</code></pre>
<h3>getMentionedUserId</h3>
<h4>获取提到的用户 QQ 号</h4>
<p>typescript</p>
<pre><code>declare function getMentionedUserId(
event: AllMessageEvent
): Promise&lt;number | 0&gt;;</code></pre>
<h2>图片搜索</h2>
<h3>BaiDuSearchPic</h3>
<h4>百度图片以图搜图</h4>
<p>typescript</p>
<pre><code>declare function BaiDuSearchPic(urlOrBuffer: string | Buffer): Promise&lt;any&gt;;</code></pre>
<h2>图片代理</h2>
<h3>proxyImageWithCgi</h3>
<h4>使用 CGI 服务代理图片链接</h4>
<p>typescript</p>
<pre><code>declare function proxyImageWithCgi(url: string): Promise&lt;any&gt;;</code></pre>
<h2>消息发送</h2>
<h3>noticeGroups</h3>
<h4>群发群消息</h4>
<p>typescript</p>
<pre><code>declare function noticeGroups(
this: oicq.Client,
groupIdList: number[],
message: oicq.Sendable,
delay?: number
): Promise&lt;void&gt;;</code></pre>
<h3>noticeFriends</h3>
<h4>群发好友消息</h4>
<p>typescript</p>
<pre><code>declare function noticeFriends(
this: oicq.Client,
friendIdList: number[],
message: oicq.Sendable,
delay?: number
): Promise&lt;void&gt;;</code></pre>
<h3>noticeAdmins</h3>
<h4>群发通知给管理员</h4>
<p>typescript</p>
<pre><code>declare function noticeAdmins(
this: oicq.Client,
message: oicq.Sendable,
delay?: number
): Promise&lt;void&gt;;</code></pre>
<h3>noticeOwners</h3>
<h4>群发通知给主人</h4>
<p>typescript</p>
<pre><code>declare function noticeOwners(
this: oicq.Client,
message: oicq.Sendable,
delay?: number
): Promise&lt;void&gt;;</code></pre>
<h3>noticeMainOwner</h3>
<h4>群发通知给第一个主人</h4>
<p>typescript</p>
<pre><code>declare function noticeMainOwner(
this: oicq.Client,
message: oicq.Sendable
): Promise&lt;void&gt;;</code></pre>
<h2>登录与认证</h2>
<h3>getPskey</h3>
<h4>通过域名获取 pskey</h4>
<p>typescript</p>
<pre><code>declare function getPskey(this: oicq.Client, domain: string): Promise&lt;string&gt;;</code></pre>
<h3>getCookie</h3>
<h4>通过域名获取 cookie 和其他认证信息，支持缓存</h4>
<p>typescript</p>
<pre><code>declare function getCookie(
this: oicq.Client,
domain: string
): Promise&lt;{
pskey: string;
skey: any;
uin: number;
gtk: string;
bkn: string;
cookie: string;
}&gt;;</code></pre>
<h3>getCookieByQRCode</h3>
<h4>通过扫码登录获取 cookie</h4>
<p>typescript</p>
<pre><code>declare function getCookieByQRCode(
this: oicq.Client,
appid: number,
appkey: string,
ticket: string
): Promise&lt;void&gt;;</code></pre>
<h3>getDevToolsLoginCode</h3>
<h4>获取开发者工具登录码</h4>
<p>typescript</p>
<pre><code>declare function getDevToolsLoginCode(): Promise&lt;string&gt;;</code></pre>
<h3>requestLoginViaDevTools</h3>
<h4>申请通过开发者工具登录，以获取 Cookie</h4>
<p>typescript</p>
<pre><code>declare function requestLoginViaDevTools(): Promise&lt;{
code: string;
url: string;
}&gt;;</code></pre>
<h3>queryDevToolsLoginStatus</h3>
<h4>获取开发者工具登录结果</h4>
<p>typescript</p>
<pre><code>declare function queryDevToolsLoginStatus(code: string): Promise&lt;{
status: &quot;OK&quot; | &quot;Wait&quot; | &quot;Expired&quot; | &quot;Used&quot; | &quot;Error&quot;;
ticket?: string;
}&gt;;</code></pre>
<h3>getAuthCodeViaTicket</h3>
<h4>通过开发者工具登录获取 AuthCode</h4>
<p>typescript</p>
<pre><code>declare function getAuthCodeViaTicket(
ticket: string,
appid: number
): Promise&lt;string&gt;;</code></pre>
<h3>getAuthCodeOfBot</h3>
<h4>通过 Oicq 协议获取小程序 AuthCode</h4>
<p>typescript</p>
<pre><code>declare function getAuthCodeOfBot(
this: oicq.Client,
appid: number
): Promise&lt;any&gt;;</code></pre>
<h3>getMinicoTokenViaAuthCode</h3>
<h4>通过 Auth Code 获取 minico Token</h4>
<p>typescript</p>
<pre><code>declare function getMinicoTokenViaAuthCode(
authCode: string,
appid: number
): Promise&lt;any&gt;;</code></pre>
<h3>getViolationRecords</h3>
<h4>获取 QQ 安全中心违规记录</h4>
<p>typescript</p>
<pre><code>declare function getViolationRecords(
this: oicq.Client,
authCode: string,
appid: number,
size?: number
): Promise&lt;
{
type: string;
time: string;
duration: string;
reason: number;
}[]
&gt;;</code></pre>
<h3>uid2uin</h3>
<h4>uid 转 uin</h4>
<p>typescript</p>
<pre><code>declare function uid2uin(this: oicq.Client, uid: string): Promise&lt;any&gt;;</code></pre>
<h2>文件上传</h2>
<h3>uploadFileToDir</h3>
<h4>上传文件到指定群的群文件的指定目录</h4>
<p>typescript</p>
<pre><code>declare function uploadFileToDir(
this: oicq.Client,
group: number,
filepath: string,
uploadFilename?: string,
dirname?: string
): Promise&lt;boolean&gt;;</code></pre>
<h3>uploadImageToCollection</h3>
<h4>上传图片到收藏</h4>
<p>typescript</p>
<pre><code>declare function uploadImageToCollection(
this: oicq.Client,
buffer: ArrayBuffer
): Promise&lt;string&gt;;</code></pre>
<h3>uploadImageToGroupHomework</h3>
<h4>上传图片到群作业</h4>
<p>typescript</p>
<pre><code>declare function uploadImageToGroupHomework(
this: oicq.Client,
imgBase64: string
): Promise&lt;string&gt;;</code></pre>
<h3>uploadImageToQQMail</h3>
<h4>上传图片到 QQ 邮箱</h4>
<p>typescript</p>
<pre><code>declare function uploadImageToQQMail(
this: oicq.Client,
url: string,
sid: {
sid: string;
qm_sid: string;
}
): Promise&lt;string&gt;;</code></pre>
<h3>uploadImageToGroupNotice</h3>
<h4>上传图片到群公告</h4>
<p>typescript</p>
<pre><code>declare function uploadImageToGroupNotice(
this: oicq.Client,
urlOrBlob: string | Blob
): Promise&lt;{
h: string;
w: string;
id: string;
url: string;
url2: string;
url3: string;
}&gt;;</code></pre>
<h2>高级消息功能</h2>
<h3>signArk</h3>
<h4>签名卡片 json</h4>
<p>typescript</p>
<pre><code>declare function signArk(this: oicq.Client, json: string): Promise&lt;any&gt;;</code></pre>
<h3>runWithErrorHandler</h3>
<h4>运行函数并捕获错误, 并通过 event.reply 发送错误信息</h4>
<p>typescript</p>
<pre><code>declare function runWithErrorHandler(
this: oicq.Client,
fn: () =&gt; any,
event?: {
reply: (
content: oicq.Sendable,
quote?: boolean
) =&gt; Promise&lt;oicq.MessageRet&gt;;
},
message?: oicq.Sendable | ((error: string) =&gt; oicq.Sendable)
): Promise&lt;any&gt;;</code></pre>
<h3>createMarkdown</h3>
<h4>创建 markdown 消息</h4>
<p>typescript</p>
<pre><code>declare function createMarkdown(
this: oicq.Client,
markdown: string
): Promise&lt;oicq.JsonElem&gt;;</code></pre>
<h3>createHighlightJson</h3>
<h4>创建高亮显示的 json 消息</h4>
<p>typescript</p>
<pre><code>declare function createHighlightJson(
this: oicq.Client,
json: string | object
): Promise&lt;oicq.JsonElem&gt;;</code></pre>
<h3>canBan</h3>
<h4>判断 Bot 是否有权限或者是否能够禁言目标群的目标 qq</h4>
<p>typescript</p>
<pre><code>declare function canBan(
this: oicq.Client,
gid: number,
qq: number
): Promise&lt;boolean&gt;;</code></pre>
<h3>getUserProfile</h3>
<h4>获取用户资料</h4>
<p>typescript</p>
<pre><code>declare function getUserProfile(
this: oicq.Client,
uin: number
): Promise&lt;{
qq: any;
qid: string;
uid: string;
nickname: string;
level: number;
signature: string;
registerAt: number;
}&gt;;</code></pre>