{"id":19251974,"url":"https://github.com/jiangjie/minigame-std","last_synced_at":"2025-04-21T13:30:40.376Z","repository":{"id":239456115,"uuid":"799550348","full_name":"JiangJie/minigame-std","owner":"JiangJie","description":"Mini Game Standard Development Library.","archived":false,"fork":false,"pushed_at":"2025-03-31T10:04:31.000Z","size":662,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-20T06:34:32.735Z","etag":null,"topics":["base64","clipboard","crypto","decode","encode","fetch","fs","image","lbs","md5","minigame","network","rsa","sha","socket","std","storage","webaudio"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JiangJie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-12T13:35:30.000Z","updated_at":"2025-03-31T10:03:44.000Z","dependencies_parsed_at":"2024-06-11T19:27:34.423Z","dependency_job_id":"459e2bef-cfc7-4a40-bf77-5b6c0171f7d9","html_url":"https://github.com/JiangJie/minigame-std","commit_stats":{"total_commits":194,"total_committers":1,"mean_commits":194.0,"dds":0.0,"last_synced_commit":"383174c8ccd177b6b9c5b41047dbb407138194b7"},"previous_names":["jiangjie/minigame-std"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JiangJie%2Fminigame-std","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JiangJie%2Fminigame-std/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JiangJie%2Fminigame-std/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JiangJie%2Fminigame-std/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JiangJie","download_url":"https://codeload.github.com/JiangJie/minigame-std/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250064509,"owners_count":21368917,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["base64","clipboard","crypto","decode","encode","fetch","fs","image","lbs","md5","minigame","network","rsa","sha","socket","std","storage","webaudio"],"created_at":"2024-11-09T18:24:51.324Z","updated_at":"2025-04-21T13:30:39.210Z","avatar_url":"https://github.com/JiangJie.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 小游戏“标准开发库”\n\n[![NPM version](https://img.shields.io/npm/v/minigame-std.svg)](https://npmjs.org/package/minigame-std)\n[![NPM downloads](https://badgen.net/npm/dm/minigame-std)](https://npmjs.org/package/minigame-std)\n[![JSR Version](https://jsr.io/badges/@happy-js/minigame-std)](https://jsr.io/@happy-js/minigame-std)\n[![JSR Score](https://jsr.io/badges/@happy-js/minigame-std/score)](https://jsr.io/@happy-js/minigame-std/score)\n[![Build Status](https://github.com/jiangjie/minigame-std/actions/workflows/test.yml/badge.svg)](https://github.com/jiangjie/minigame-std/actions/workflows/test.yml)\n\n\u003e [!NOTE]\n\u003e 这不是任何一家小游戏平台的官方项目。\n\n\u003e 以下文档以微信小游戏为例进行说明，其他小游戏平台基本也是一样的（dddd）。\n\n---\n\n## 动机\n\n本项目的目的是提供一套能同时运行于小游戏环境和浏览器环境，具有相同 API 的常用开发库。\n\n鉴于小游戏平台通常在运行时之外还有一套官方的基础库（Core），而本项目是基于基础库的再次封装，定位为基础库的补充，希望可以作为“标准开发库（Std）”存在。\n\n按照[微信小游戏](https://developers.weixin.qq.com/minigame/dev/guide/)的官方说法（其他小游戏平台类似），小游戏和浏览器运行环境的主要差别在于没有 BOM 和 DOM API，而提供了类似功能的 wx API，但两者存在较大差异。\n\n比如将 UTF-8 字符串编码为 ArrayBuffer。\n\n**浏览器**\n\n```ts\nnew TextEncoder().encode(data);\n```\n\n**微信小游戏**\n\n```ts\nwx.encode({\n    data,\n    format: 'utf8',\n});\n```\n\n首先，小游戏基本都是先在浏览器上进行开发调试，而后再发布到小游戏平台；进而，通常同一套代码还会同时发布到小游戏平台和 web 平台。\n\n在这种情况下，以上差异则是不得不面对的问题，处理这些差异将是一种繁琐的挑战，本项目就是为了抹平这种差异，帮助开发者做到使用相同的 API 兼容不同的平台。\n\n## 安装\n\n```sh\n# via pnpm\npnpm add minigame-std\n# or via yarn\nyarn add minigame-std\n# or just from npm\nnpm install --save minigame-std\n# via JSR\njsr add @happy-js/minigame-std\n```\n\n## 特性\n\n-   平台相关\n    ```js\n    import { platform } from 'minigame-std';\n    ```\n-   UTF-8 字符串和 ArrayBuffer 之间编解码\n    ```js\n    import { textDecode, textEncode } from 'minigame-std';\n    ```\n-   base64 编解码\n    ```js\n    import { decodeBase64, encodeBase64 } from 'minigame-std';\n    ```\n-   文件系统\n    - 支持 `zip` `unzip` `zipSync` `unzipSync`\n    ```js\n    import { fs } from 'minigame-std';\n    ```\n-   剪贴板\n    ```js\n    import { clipboard } from 'minigame-std';\n    ```\n-   全局 error 和 unhandledrejection 处理\n    ```js\n    import { addErrorListener, addUnhandledrejectionListener } from 'minigame-std';\n-   网络状态/类型\n    ```js\n    import { addNetworkChangeListener, getNetworkType } from 'minigame-std';\n    ```\n-   https 请求（fetch）\n    ```js\n    import { fetchT } from 'minigame-std';\n    ```\n-   socket（WebSocket）\n    ```js\n    import { connectSocket } from 'minigame-std';\n    ```\n-   storage（localStorage）\n    ```js\n    import { storage } from 'minigame-std';\n    ```\n-   WebAudio\n    ```js\n    import { audio } from 'minigame-std';\n-   加密 md5/sha/rsa\n    ```js\n    import { cryptos } from 'minigame-std';\n-   LBS\n    ```js\n    import { lbs } from 'minigame-std';\n    ```\n-   更多特性请查看[文档](docs/README.md)\n\n## 和 Adapter 是什么关系\n\n[Adapter](https://developers.weixin.qq.com/minigame/dev/game-engine/workflow/adapter.html) 也是为了适配 wx API 和 DOM/BOM API 的差异，相比 Adapter，minigame-std 具有一些显著的优势。\n\n-   Adapter 使用小游戏 API 模拟浏览器特有的 API，但两者在功能上其实并不等价，所以这样会丧失一些小游戏 API 特有的功能。\n\n    比如 `wx.request` 支持 `enableHttpDNS` 参数，但浏览器环境的 `fetch` 和 `XMLHttpRequest` 都不支持，所以完全模拟就无法传递这样的参数。\n\n    使用 `minigame-std` 完全可以这样写，平台特有的参数会被其他平台自动忽略。\n\n    ```ts\n    fetchT(url, {\n        mode: 'no-cors', // 浏览器特有\n        enableHttpDNS: true, // 小游戏特有\n    });\n    ```\n\n    再如 `wx.request` 的返回值是一个支持 `abort` 的 `RequestTask`，而 `fetch` 的返回值是一个 `Promise\u003cResponse\u003e`，需要由额外的 `AbortController` 控制才能实现 `abort` 功能，如果为了模拟而将 `wx.request` 返回 `Promise\u003cResponse\u003e`，则将失去`abort` 功能。\n\n    `minigame-std` 的 `fetchT` 沿用了 `wx.request` 的返回值设计，由一个 `abortable` 参数控制是否可 abort。\n\n    ```ts\n    fetchT(url, {\n        abortable: true,\n    }).abort();\n    ```\n\n-   Adapter 会产生很多胶水代码，这些代码不管是否使用都会打进包体，如果能直接调用小游戏 API 的话，这些胶水代码实际上是一种负担，某种情况下甚至是负优化，完全可以舍弃。\n\n    使用 `minigame-std` 不需要在运行时注入 Adapter，通过构建流程可以自动为特定平台去除其他平台的代码，达到节省包体大小和提高运行性能的效果。\n\n    `minigame-std` 使用 ESM 规范开发，支持`tree shake`，没有使用的特性可以在构建时删除，进一步节省包体大小。\n\n-   `minigame-std` 额外提供了一些特性，如 `base64` `fs`等。\n\n    对于某些平台独有的特性，也会为其他平台补齐实现。\n\n    所有平台都不原生支持，但一些常用的功能逐渐添加中。\n\n### 能替代 Adapter 吗\n\n**还不能！**\n\n一些 DOM Element 相关的适配代码仍需要 Adapter，主要是游戏引擎需要使用。\n\n## 小游戏平台的支持情况\n\n-   微信小游戏\n\n    100% 经过测试。\n\n-   其他小游戏\n\n    由于小游戏平台的 API 全部使用 `wx` 全局 namespace 进行调用，其他小游戏平台为了兼容微信小游戏，通常也会设置 `wx` namespace，比如 `GameGlobal.wx = qq`，且 API 会大体保持一致，所以基本也是支持的。\n\n    如发现有差异，请提 [issue](https://github.com/JiangJie/minigame-std/issues)。\n\n## 代码裁剪\n\n**`__MINIGAME_STD_MINA__`**\n\n代码打包时通过设置 `__MINIGAME_STD_MINA__` boolean 变量来控制需要裁剪掉 web 平台还是小游戏平台的专属代码，所有平台特有的代码都是 `side effect free` 的，可以放心裁剪。\n\n设置为 `true` 则裁减掉 web 平台的代码，适合发布小游戏时的构建。\n\n设置为 `false` 则裁减掉小游戏平台代码，适合在浏览器上开发阶段或者发布到 web 平台时的构建。\n\n构建流程可参考 [minigame-std-demo](https://github.com/JiangJie/minigame-std-demo)。\n\n## 测试\n\n```\npnpm install\npnpm test\n```\n\n\u003e [!NOTE]\n\u003e 由于测试环境的局限性，测试用例并不能覆盖所有功能。\n\n`tests` 目录下的测试用例是基于 web 平台的测试场景，相当于设置 `__MINIGAME_STD_MINA__: false` 的代码，测试工具为 [deno](https://deno.com/)。\n\n对 web 平台文件系统的测试可以转到 [happy-opfs](https://github.com/JiangJie/happy-opfs)。\n\n小游戏平台的测试用例请转到 [minigame-std-demo](https://github.com/JiangJie/minigame-std-demo)。\n\n## [文档](docs/README.md)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiangjie%2Fminigame-std","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjiangjie%2Fminigame-std","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiangjie%2Fminigame-std/lists"}