{"id":18733151,"url":"https://github.com/bioforestchain/web-components","last_synced_at":"2025-10-10T04:43:39.228Z","repository":{"id":58576178,"uuid":"530584496","full_name":"BioforestChain/web-components","owner":"BioforestChain","description":null,"archived":false,"fork":false,"pushed_at":"2022-09-18T14:08:12.000Z","size":5068,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-14T10:03:53.405Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BioforestChain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-30T09:24:37.000Z","updated_at":"2024-04-07T05:56:52.000Z","dependencies_parsed_at":"2022-09-21T12:44:41.991Z","dependency_job_id":null,"html_url":"https://github.com/BioforestChain/web-components","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioforestChain%2Fweb-components","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioforestChain%2Fweb-components/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioforestChain%2Fweb-components/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioforestChain%2Fweb-components/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BioforestChain","download_url":"https://codeload.github.com/BioforestChain/web-components/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239605124,"owners_count":19666998,"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":[],"created_at":"2024-11-07T15:08:52.382Z","updated_at":"2025-10-10T04:43:34.183Z","avatar_url":"https://github.com/BioforestChain.png","language":"TypeScript","readme":"# Bnqkl Web Component\n\n\u003e 该项目目前使用了 pnpm 进行管理。yarn 理论上也可以，但目前精力有限，暂不维护 yarn 的版本\n\n⚠️ 注意，因为项目中使用 [patch-package](https://www.npmjs.com/package/patch-package) 对一些 npm 包进行了修复，而因为 pnpm 的特性，这会污染到全局，所以请谨慎使用\n\n## 如何使用 Usage\n\n1. [在 Angular 项目使用](./angular/projects/lib/README.md)\n1. [在其它项目中使用](./core/README.md)\n\n## 🚀 贡献者·快速开始\n\n1. 安装依赖\n   1. 在内网环境中，我们在 .npmrc 配置了一些环境变量来确保在能正常通过依赖的安装。所以你可能需要了解以下这些指令帮助你完成依赖的安装\n      ```ini\n      PUPPETEER_DOWNLOAD_HOST=\"https://npm.taobao.org/mirrors/\" # 外网\n      PUPPETEER_DOWNLOAD_HOST=\"http://192.168.110.154:8080/puppeteer/\" # 内网\n      PUPPETEER_SKIP_DOWNLOAD=1 # 内网如果没有及时更新 puppeteer 所需版本的 chromium-browser-snapshots\n      ```\n   1. 然后执行安装\n      ```shell\n      pnpm install # 确保依赖安装完毕\n      # 依赖安装完毕后，我们会自动对node_modules中的一些第三方代码进行补丁修补\n      # 此外，还会在你的电脑中安装证书，目的是能够启动受信任的https服务。\n      # 因为storybook的预览，用到了iframe，而只有https才能彻底规避一些奇怪的限制带来的bug：比如iframe中slotchange不触发\n      ```\n   1. 安装后执行的 package.json 的 postintall 命令里，我们会自动对 node_modules 中的一些第三方代码进行补丁修补。此外，还会在你的电脑中安装证书服务[mkcert](https://github.com/FiloSottile/mkcert)，目的是能够启动受信任的 https 服务。如果你看到错误，那么可能是权限问题导致，使用管理员系统权限重新`scripts/mkcert-v1.4.4-windows-amd64.exe -install \u0026\u0026 scripts/mkcert-v1.4.4-windows-amd64.exe localhost`即可。\n2. 启动开发编译，并启动 storybook 预览组件，并进行实时预览\n   ```shell\n   pnpm run dev\n   # 启动 stencil 内部的 ts+rollup 编译，导出js、并实时生成类型源文件、与文档\n   # 启动 storybook 来对组件进行预览开发\n   ```\n3. 编译输出\n   ```shell\n   pnpm run build # 编译\n   ```\n4. 插件\n   - [lit-html.vsix](https://marketplace.visualstudio.com/items?itemName=bierner.lit-html) [内网](http://192.168.110.154:8000/bierner.lit-html-1.11.1.vsix)\n     \u003e 测试的编写是使用 lit-html 来进行开发的，所以该插件可以很好地改进相关的开发体验\n\n## 📦 贡献者·创建组件\n\n\u003e 以下命令均要进入到 [core](./core) 目录中执行\n\n```shell\npnpm g YOUR_COMPONENT_NAME\n```\n\n其中`YOUR_COMPONENT_NAME`的命名风格有着严格的命名规范，比如：\n\n1.  `pnpm g your-component`，`-`用于替代空格\n    \u003e 最终你的组件会在 `your-component/bn-your-component.tsx`中定义出`\u003cbn-your-component/\u003e`的组件\n1.  `pnpm g button/some-feature`，`-`用于替代空格，`/`用于定义文件夹\n    \u003e 最终你的组件会在 `button/bn-some-feature-button.tsx`中定义出`\u003cbn-some-feature-button/\u003e`的组件\n\n与此同时，组件中会自动生成 `stories` 文件夹下会出现一个对应的“故事文件”，比如`your-component.stories.ts`。在该文件中，也同样享有严格的类型检查。前提是你要安装 vscode-lit 插件\n\n`.const.ts(x)` 后缀的文件是特殊的文件，它所定义的“类型”最终会被一并导出。所以贡献者可以将跨组件“共享的类型”定义到这些文件中以统一导出。\n\n## 📦 贡献者·调试\n\n1. 在组件开发时，你可以使用 `this.console.verbose/log/info/warn/error/success` 这几个接口来进行日志打印。它们的日志等级依次提高\n1. 在组件部署的环境中，通过将全局变量 `self.__bn_dev__ = true` 来开启调试。\n1. 使用 `localStorage.getItem('bn-debug')` 来进行全局的调试配置：\n   1. `*`代表调试任何组件\n   1. `bn-tag-name:*` 代表调试指定组件\n   1. `bn-tag-name:warn` 代表将指定组件设定为特定的最低日志等级\n   1. `*,bn-tag-name:warn` 使用逗号`,`来进行多项配置\n1. 使用 `ele.dataset.bnDebug` （也就是`data-bn-debug`）来对指定的元素进行最低日志等级配置\n   1. 比如说 `\u003cbn-tag-name data-bn-debug=\"*\"\u003e\u003c/bn-tag-name\u003e` 代表日志全开\n   1. 比如说 `\u003cbn-tag-name data-bn-debug=\"info\"\u003e\u003c/bn-tag-name\u003e` 代表只打印 `info` 及以上的日志\n   1. 比如说 `\u003cbn-tag-name data-bn-debug=\"disable\"\u003e\u003c/bn-tag-name\u003e` 代表关闭该元素的打印。\n1. 可以通过为元素配置 `id` 属性，来使得日志打印的时候带上 id 信息，使得更有可分辨性\n\n## 📦 贡献者·一些已知的问题\n\n1. 在 Angular 项目开发时，的 HMR 模式下启动，webcomponet 是无法正确重载的（因为 WebComponent 无法重新注册）。所以建议是：\n   1. 如果在编写 Angular-HTML 或者是开发调试 WebComponent，那么关闭 HMR，等将元素的结构放置完成后，再进入 .scss 的编写\n   1. 如果再编写 Angular-SCSS，那么开启 HMR，.scss 文件可以动态重载，但是这时候如果有修改到 .html 文件的时候，可能需要手动刷新才能让 WebComponent 正确渲染\n1. 当你在组件中配置了 assetDir 的属性后，需要重启编译，否则无法正确进行资源拷贝\n\n## 📦 贡献者·动态图标\n\nlottie 动画图标会占用大量的资源，所以我们新的方案是将之预渲染成图片，使用精灵图+CSS-Animation-API 进行动画控制。\n精灵图的制作方法是：\n\n1.  到 [https://www.codeandweb.com/free-sprite-sheet-packer]() 中，将图片一帧帧“水平”放上去，然后将帧间距 Padding 改成 0（它有 bug，一定要先 1px 再 0px 才能正确生效）\n1.  如果一个动画有多种风格，那么将水平图垂直放置合并在一张精灵图中\n1.  到 [https://squoosh.app]() 中，将合并好的 png 图片导入：\n    1.  选择 webp 格式\n    1.  勾上 Lossless 配置（不然颜色会丢，这对图标动画这种精致的、色调单一的小图片来说并不友好）\n    1.  Effort 拉满\n    1.  Quality 控制在 100%~60%之间，越高越好，前提是不要丢失细节\n\n这样导出的图片跟 lottie-web 的 json 文件差不多大，甚至可以更小，同时渲染效率也会更高。\n\n## 📦 贡献者·静态图标\n\n我们使用 iconmoon 来管理图标\n\n## 📦 贡献者·发布流程\n\n在做完一些修改后，请**务必**根据以下的流程来进行发布：\n\n1. `pnpm changeset`\n   \u003e 一般来说只选中 1 个要发布的包，并描述发布内容\n1. `pnpm changeset version`\n   \u003e 变更版本号并将刚才些的内容存放到 CHANGELOG.md 中去\n1. `pnpm changeset`+`pnpm changeset version`\n   \u003e 继续以上的流程，直到所有包的版本号都变更完毕\n1. `pnpm build`\n   \u003e 会依此编译 core 和 angular，并执行一些脚本工作\n1. 提交 Git\n1. `pnpm pub`\n   \u003e 会依此发布 core 和 angular（编译好的）\n\n## TODO\n\n- [ ] 一个文件夹中放置多个组件的支持不够好，readme 只会有一个。\n  \u003e 正确的操作是将这些组件的文档的内容分别放在对应的 stories.mdx 中。同时 readme.md 归纳了所有组件的文档，并提供 readme 该有的信息\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbioforestchain%2Fweb-components","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbioforestchain%2Fweb-components","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbioforestchain%2Fweb-components/lists"}