diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 6afef41..832392a 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,5 +1,5 @@ -name: Bug 报告 -description: 报告一个可以稳定复现的问题 +name: Bug report +description: Report a reproducible problem title: "[Bug]: " labels: - bug @@ -7,52 +7,52 @@ body: - type: markdown attributes: value: | - 感谢反馈!提交前请先确认问题能在最新线上版本或 `master` 分支复现。 + Thanks for the report. Please confirm that the problem reproduces on the latest live version or the `master` branch. - type: input id: browser attributes: - label: 浏览器与版本 - placeholder: 例如 Chrome 128 / Safari 18 + label: Browser and version + placeholder: e.g. Chrome 128 / Safari 18 validations: required: true - type: input id: tool attributes: - label: 受影响的工具或页面 - placeholder: 例如 Markdown 编辑器、二维码工具 + label: Affected tool or page + placeholder: e.g. Markdown editor, QR code tool validations: required: true - type: textarea id: steps attributes: - label: 复现步骤 - description: 请按顺序写出最小复现路径。 + label: Steps to reproduce + description: List the smallest reproducible path in order. placeholder: | - 1. 打开…… - 2. 输入…… - 3. 点击…… + 1. Open … + 2. Enter … + 3. Click … validations: required: true - type: textarea id: expected attributes: - label: 预期行为 + label: Expected behavior validations: required: true - type: textarea id: actual attributes: - label: 实际行为 + label: Actual behavior validations: required: true - type: textarea id: context attributes: - label: 补充信息 - description: 可以附截图、控制台错误、操作系统或其他上下文。请先移除敏感数据。 + label: Additional context + description: Add screenshots, console errors, operating-system details, or other context. Remove sensitive data first. diff --git a/.github/ISSUE_TEMPLATE/bug_report_zh.yml b/.github/ISSUE_TEMPLATE/bug_report_zh.yml new file mode 100644 index 0000000..a1a8249 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report_zh.yml @@ -0,0 +1,58 @@ +name: Bug 报告(中文) +description: 使用中文报告一个可以稳定复现的问题 +title: "[Bug][中文]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + 感谢反馈!提交前请先确认问题能在最新线上版本或 `master` 分支复现。 + + - type: input + id: browser + attributes: + label: 浏览器与版本 + placeholder: 例如 Chrome 128 / Safari 18 + validations: + required: true + + - type: input + id: tool + attributes: + label: 受影响的工具或页面 + placeholder: 例如 Markdown 编辑器、二维码工具 + validations: + required: true + + - type: textarea + id: steps + attributes: + label: 复现步骤 + description: 请按顺序写出最小复现路径。 + placeholder: | + 1. 打开…… + 2. 输入…… + 3. 点击…… + validations: + required: true + + - type: textarea + id: expected + attributes: + label: 预期行为 + validations: + required: true + + - type: textarea + id: actual + attributes: + label: 实际行为 + validations: + required: true + + - type: textarea + id: context + attributes: + label: 补充信息 + description: 可以附截图、控制台错误、操作系统或其他上下文。请先移除敏感数据。 diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index e61d373..856f4fb 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,8 +1,11 @@ blank_issues_enabled: true contact_links: - - name: 在线体验 + - name: Live demo url: https://htool.vercel.app/ - about: 先在最新线上版本确认问题是否可以复现。 - - name: 使用文档 - url: https://github.com/Hughhhhcoder/HTooL#快速开始 + about: Confirm whether the problem reproduces on the latest live version. + - name: English documentation + url: https://github.com/Hughhhhcoder/HTooL#quick-start + about: Read setup, testing, deployment, and privacy guidance. + - name: 简体中文文档 + url: https://github.com/Hughhhhcoder/HTooL/blob/master/README.zh-CN.md#快速开始 about: 查看安装、测试、部署和隐私说明。 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 21792b8..b87d5a1 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,5 +1,5 @@ -name: 功能建议 -description: 提议一个能让 HTooL 更有用的改进 +name: Feature request +description: Suggest an improvement that would make HTooL more useful title: "[Feature]: " labels: - enhancement @@ -7,28 +7,28 @@ body: - type: textarea id: problem attributes: - label: 要解决的问题 - description: 请描述场景和当前遇到的限制,而不仅是解决方案。 - placeholder: 我在……场景下,需要…… + label: Problem to solve + description: Describe the scenario and current limitation, not only the solution. + placeholder: In …, I need … validations: required: true - type: textarea id: proposal attributes: - label: 建议方案 - description: 你希望工具如何工作? + label: Proposed solution + description: How would you like the tool to work? validations: required: true - type: textarea id: alternatives attributes: - label: 备选方案 - description: 你尝试过哪些替代做法? + label: Alternatives considered + description: What other approaches have you tried? - type: textarea id: context attributes: - label: 补充信息 - description: 可以附示例、草图、截图或相关链接。 + label: Additional context + description: Add examples, sketches, screenshots, or related links. diff --git a/.github/ISSUE_TEMPLATE/feature_request_zh.yml b/.github/ISSUE_TEMPLATE/feature_request_zh.yml new file mode 100644 index 0000000..f737466 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request_zh.yml @@ -0,0 +1,34 @@ +name: 功能建议(中文) +description: 使用中文提议一个能让 HTooL 更有用的改进 +title: "[Feature][中文]: " +labels: + - enhancement +body: + - type: textarea + id: problem + attributes: + label: 要解决的问题 + description: 请描述场景和当前遇到的限制,而不仅是解决方案。 + placeholder: 我在……场景下,需要…… + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: 建议方案 + description: 你希望工具如何工作? + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: 备选方案 + description: 你尝试过哪些替代做法? + + - type: textarea + id: context + attributes: + label: 补充信息 + description: 可以附示例、草图、截图或相关链接。 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ab5ef39..a4aa04d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,12 +1,14 @@ -## 变更摘要 +

English · 简体中文

- +## Summary -## 关联 Issue + - +## Related issue -## 验证方式 + + +## Validation - [ ] `npm run test:unit` - [ ] `npm run test:no-gradient` @@ -14,14 +16,14 @@ - [ ] `npm run test:perf-budget` - [ ] `npm run test:e2e` -## 检查清单 +## Checklist -- [ ] 我已检查浅色和暗色模式。 -- [ ] 我已检查移动端布局。 -- [ ] 我已补充或更新了相关测试。 -- [ ] 我没有提交密钥、个人数据或真实用户文件。 -- [ ] 如果涉及 UI,我已附上截图或录屏。 +- [ ] I checked both light and dark modes. +- [ ] I checked the mobile layout. +- [ ] I added or updated relevant tests. +- [ ] I did not commit secrets, personal data, or real user files. +- [ ] I included screenshots or a recording for UI changes. -## 兼容性与风险 +## Compatibility and risk - + diff --git a/.github/PULL_REQUEST_TEMPLATE/zh-CN.md b/.github/PULL_REQUEST_TEMPLATE/zh-CN.md new file mode 100644 index 0000000..ca0ecd5 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/zh-CN.md @@ -0,0 +1,29 @@ +

English · 简体中文

+ +## 变更摘要 + + + +## 关联 Issue + + + +## 验证方式 + +- [ ] `npm run test:unit` +- [ ] `npm run test:no-gradient` +- [ ] `npm run build` +- [ ] `npm run test:perf-budget` +- [ ] `npm run test:e2e` + +## 检查清单 + +- [ ] 我已检查浅色和暗色模式。 +- [ ] 我已检查移动端布局。 +- [ ] 我已补充或更新了相关测试。 +- [ ] 我没有提交密钥、个人数据或真实用户文件。 +- [ ] 如果涉及 UI,我已附上截图或录屏。 + +## 兼容性与风险 + + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index ab2cfa1..c8a5fa2 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,23 +1,25 @@ -# 行为准则 +# Code of Conduct -## 我们的承诺 +

English · 简体中文

-为了营造开放、友善且可持续的协作环境,参与 HTooL 的每个人都应以尊重、善意和专业的方式交流,无论其经验、背景或身份如何。 +## Our commitment -## 可接受的行为 +To create an open, friendly, and sustainable collaboration environment, everyone participating in HTooL is expected to communicate with respect, good faith, and professionalism, regardless of experience, background, or identity. -- 使用清晰、建设性的语言提出意见; -- 讨论实现、体验和证据,而不是评价个人; -- 接受不同观点,并在有新信息时修正自己的判断; -- 尊重项目维护者和其他贡献者的时间。 +## Acceptable behavior -## 不可接受的行为 +- Use clear and constructive language. +- Discuss implementation, experience, and evidence rather than judging people. +- Stay open to different perspectives and update your view when new information appears. +- Respect the time of maintainers and contributors. -- 骚扰、歧视、威胁、人身攻击或故意羞辱; -- 发布他人的私人信息; -- 破坏讨论、刷屏、冒充他人或以恶意方式提交内容; -- 任何不适合公开协作环境的行为。 +## Unacceptable behavior -## 执行 +- Harassment, discrimination, threats, personal attacks, or deliberate humiliation. +- Publishing someone else’s private information. +- Disrupting discussions, spamming, impersonating others, or submitting content maliciously. +- Any other behavior that is inappropriate for a public collaboration space. -请通过 [维护者主页](https://github.com/Hughhhhcoder) 私下联系维护者,报告违反本准则的行为。维护者会根据事实采取适当措施,并尽可能保护报告者的隐私。 +## Enforcement + +Please contact the maintainer privately through the [maintainer profile](https://github.com/Hughhhhcoder) to report a violation. Reports will be reviewed based on the available facts, with the reporter’s privacy protected as far as possible. diff --git a/CODE_OF_CONDUCT.zh-CN.md b/CODE_OF_CONDUCT.zh-CN.md new file mode 100644 index 0000000..1e3bbb8 --- /dev/null +++ b/CODE_OF_CONDUCT.zh-CN.md @@ -0,0 +1,25 @@ +# 行为准则 + +

English · 简体中文

+ +## 我们的承诺 + +为了营造开放、友善且可持续的协作环境,参与 HTooL 的每个人都应以尊重、善意和专业的方式交流,无论其经验、背景或身份如何。 + +## 可接受的行为 + +- 使用清晰、建设性的语言提出意见; +- 讨论实现、体验和证据,而不是评价个人; +- 接受不同观点,并在有新信息时修正自己的判断; +- 尊重项目维护者和其他贡献者的时间。 + +## 不可接受的行为 + +- 骚扰、歧视、威胁、人身攻击或故意羞辱; +- 发布他人的私人信息; +- 破坏讨论、刷屏、冒充他人或以恶意方式提交内容; +- 任何不适合公开协作环境的行为。 + +## 执行 + +请通过 [维护者主页](https://github.com/Hughhhhcoder) 私下联系维护者,报告违反本准则的行为。维护者会根据事实采取适当措施,并尽可能保护报告者的隐私。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3237c7..67ee0f8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,31 +1,33 @@ -# 贡献指南 +# Contributing -感谢你愿意改进 HTooL。小而明确的 Pull Request 更容易被审阅,也更容易保持这个工具箱的稳定和克制。 +

English · 简体中文

-## 开始之前 +Thanks for helping improve HTooL. Small, focused Pull Requests are easier to review and help keep the toolkit stable and deliberate. -1. 确认 Node.js 版本为 20 或更高版本。 -2. 安装依赖:`npm ci`。 -3. 启动开发环境:`npm run dev`。 -4. 对行为变更先搜索现有 Issue,避免重复工作。 +## Before you start -## 开发约定 +1. Use Node.js 20 or newer. +2. Install dependencies with `npm ci`. +3. Start the development environment with `npm run dev`. +4. Search existing Issues before starting behavioral changes so work is not duplicated. -- 页面放在 `src/views/`,跨页面组件放在 `src/components/`,纯逻辑放在 `src/utils/`。 -- 新增功能时同步补充单元/组件测试;涉及用户流程时补充 E2E 测试。 -- 保持工具页面响应式,并同时检查浅色和暗色模式。 -- 项目当前有两个设计门禁:不要在 `src/` 中使用 CSS gradient,并确保构建产物不超过性能预算。 -- 不要把密钥、个人数据或真实用户文件提交到仓库。 +## Development conventions -## 分支与提交 +- Put pages in `src/views/`, shared components in `src/components/`, and reusable logic in `src/utils/`. +- Add unit/component tests for new behavior and E2E coverage for user-facing flows. +- Keep tool pages responsive and check both light and dark modes. +- Respect the two current design gates: do not use CSS gradients in `src/`, and keep the production bundle within its performance budget. +- Never commit secrets, personal data, or real user files. -从 `master` 创建分支,例如: +## Branches and commits + +Create a branch from `master`, for example: ```bash git switch -c feat/your-change ``` -提交信息建议使用简短的 Conventional Commits 风格前缀: +Commit messages should use a short Conventional Commits-style prefix: ```text feat: add a new utility @@ -35,19 +37,19 @@ refactor: simplify converter state test: cover keyboard shortcut ``` -## 提交 Pull Request +## Opening a Pull Request -提交前至少运行: +Run the full verification suite before submitting: ```bash npm run check ``` -如果本地没有 Playwright 浏览器,先运行 `npx playwright install chromium`。PR 描述请说明: +If Playwright browsers are not installed, run `npx playwright install chromium` first. A PR description should explain: -- 做了什么,以及为什么做; -- 如何验证; -- 是否有 UI 变化(有的话附截图或录屏); -- 是否存在兼容性、性能或破坏性变更。 +- what changed and why; +- how it was verified; +- whether the UI changed, with screenshots or a recording when useful; +- any compatibility, performance, or breaking changes. -PR 会经过 CI 检查。维护者可能会要求拆分范围、补测试或调整交互细节。 +Every PR runs through CI. Maintainers may ask for a narrower scope, additional tests, or interaction refinements. diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md new file mode 100644 index 0000000..b4d461c --- /dev/null +++ b/CONTRIBUTING.zh-CN.md @@ -0,0 +1,55 @@ +# 贡献指南 + +

English · 简体中文

+ +感谢你愿意改进 HTooL。小而明确的 Pull Request 更容易被审阅,也更容易保持这个工具箱的稳定和克制。 + +## 开始之前 + +1. 确认 Node.js 版本为 20 或更高版本。 +2. 安装依赖:`npm ci`。 +3. 启动开发环境:`npm run dev`。 +4. 对行为变更先搜索现有 Issue,避免重复工作。 + +## 开发约定 + +- 页面放在 `src/views/`,跨页面组件放在 `src/components/`,纯逻辑放在 `src/utils/`。 +- 新增功能时同步补充单元/组件测试;涉及用户流程时补充 E2E 测试。 +- 保持工具页面响应式,并同时检查浅色和暗色模式。 +- 项目当前有两个设计门禁:不要在 `src/` 中使用 CSS gradient,并确保构建产物不超过性能预算。 +- 不要把密钥、个人数据或真实用户文件提交到仓库。 + +## 分支与提交 + +从 `master` 创建分支,例如: + +```bash +git switch -c feat/your-change +``` + +提交信息建议使用简短的 Conventional Commits 风格前缀: + +```text +feat: add a new utility +fix: handle invalid input +docs: improve setup guide +refactor: simplify converter state +test: cover keyboard shortcut +``` + +## 提交 Pull Request + +提交前至少运行: + +```bash +npm run check +``` + +如果本地没有 Playwright 浏览器,先运行 `npx playwright install chromium`。PR 描述请说明: + +- 做了什么,以及为什么做; +- 如何验证; +- 是否有 UI 变化(有的话附截图或录屏); +- 是否存在兼容性、性能或破坏性变更。 + +PR 会经过 CI 检查。维护者可能会要求拆分范围、补测试或调整交互细节。 diff --git a/README.md b/README.md index ee88487..c12d065 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,51 @@
- HTooL 图标 + HTooL icon

HTooL

-

一套浏览器优先的实用工具箱,把常用的小工具收进一个克制、顺手的工作台。

+

A browser-first utility suite that brings everyday tools into one focused, dependable workspace.

- 在线体验 + Live demo · - 报告问题 + Report an issue · - 参与贡献 + Contribute

- CI 状态 + 简体中文 +

+ +

+ CI status GitHub Issues - 在线演示 + Live demo

-## 项目定位 +## What is HTooL? -HTooL 面向写作、开发和日常信息处理场景,优先把数据留在浏览器中完成处理。它不是一个需要账号和后端服务的复杂平台,而是一组打开即用、按任务分组的轻量工具。 +HTooL is a small, task-oriented toolkit for writing, development, and everyday data handling. It keeps most work in the browser and avoids turning simple utilities into an account-based platform. -## 工具一览 +## Tools -| 分组 | 工具 | 能力 | +| Group | Tool | Capabilities | | --- | --- | --- | -| 文档创作 | Markdown 编辑器 | 编辑、工具栏、实时预览、本地文件夹读写与保存 | -| 文档创作 | Markdown ↔ HTML | 双向转换、预览、复制与下载 | -| 图像与编码 | 图片格式转换 | 单个/批量转换、PNG/JPG/WebP/GIF 选择、质量调节 | -| 图像与编码 | 二维码工具 | 文本/链接生成、尺寸与颜色设置、图片解析、下载 | -| 图像与编码 | 手绘板 | 画笔、橡皮擦、颜色/粗细调节与 PNG 导出 | -| 系统与数据 | 数据处理工具 | 正则测试、URL 编码/解码、Base64、MD5 与 SHA-256 | -| 系统与数据 | IP 地址定位 | 查询 IPv4 的地域、时区与运营商信息 | +| Writing | Markdown editor | Editing, toolbar actions, live preview, local folder access, and saving | +| Writing | Markdown ↔ HTML | Two-way conversion, preview, copy, and download | +| Image & encoding | Image converter | Single/batch conversion, PNG/JPG/WebP/GIF selection, and quality control | +| Image & encoding | QR code tool | Text/URL generation, size and color settings, image decoding, and download | +| Image & encoding | Drawing board | Brush, eraser, color/size controls, and PNG export | +| System & data | Data processor | Regex testing, URL encoding/decoding, Base64, MD5, and SHA-256 | +| System & data | IP lookup | IPv4 location, timezone, and network information | -## 主要特点 +## Highlights -- 浏览器优先:图片转换、二维码、绘图和文本处理默认在本地完成。 -- 按需加载:Markdown、二维码等较重依赖仅在进入对应工具后加载。 -- 克制的界面:响应式布局、浅色/暗色模式,以及明确的任务分组。 -- 可验证的质量门禁:单元测试、组件测试、E2E 流程、构建体积预算和设计约束检查。 -- 可直接部署:Vercel 配置已包含单页应用路由回退规则。 +- Browser-first: image conversion, QR codes, drawing, and text processing run locally by default. +- Lazy-loaded tools: heavier Markdown and QR dependencies load only when their tools are opened. +- Focused interface: responsive layouts, light/dark mode, and clear task groups. +- Verifiable quality gates: unit/component tests, E2E flows, bundle budgets, and design-constraint checks. +- Deployment-ready: the Vercel configuration includes the SPA route fallback required by Vue Router. -## 技术栈 +## Tech stack - [Vue 3](https://vuejs.org/) + [Vue Router](https://router.vuejs.org/) - [Vite](https://vite.dev/) @@ -51,15 +55,15 @@ HTooL 面向写作、开发和日常信息处理场景,优先把数据留在 - [DOMPurify](https://github.com/cure53/DOMPurify) - [QRCode](https://github.com/soldair/node-qrcode) + [jsQR](https://github.com/cozmo/jsQR) -## 快速开始 +## Quick start -### 环境要求 +### Requirements -- Node.js 20 或更高版本 -- npm 10 或更高版本 -- 需要运行 E2E 测试时,额外安装 Playwright Chromium +- Node.js 20 or newer +- npm 10 or newer +- Playwright Chromium for E2E tests -### 本地开发 +### Run locally ```bash git clone https://github.com/Hughhhhcoder/HTooL.git @@ -68,92 +72,92 @@ npm ci npm run dev ``` -开发服务器默认地址为 。 +The development server runs at by default. -### 构建与预览 +### Build and preview ```bash npm run build npm run preview ``` -### 运行测试 +### Test ```bash -# 单元测试与组件测试 +# Unit and component tests npm run test:unit -# 设计约束检查:禁止 CSS gradient +# Design constraint check: CSS gradients are not allowed npm run test:no-gradient -# 构建产物性能预算检查 +# Production bundle performance budget npm run test:perf-budget -# 首次运行前安装 Playwright 浏览器 +# Install the Playwright browser the first time npx playwright install chromium -# E2E 测试 +# End-to-end tests npm run test:e2e -# 聚合检查:单测 + 设计约束 + 构建 + 性能预算 + E2E +# Full verification: tests + constraints + build + budget + E2E npm run check ``` -## 环境变量 +## Environment variables -复制 `.env.example` 为 `.env` 后按需修改: +Copy `.env.example` to `.env` and adjust as needed: -| 变量 | 默认值 | 说明 | +| Variable | Default | Description | | --- | --- | --- | -| `VITE_ENABLE_ANALYTICS` | `false` | 设置为 `true` 后,在生产环境注入 Vercel Analytics。 | +| `VITE_ENABLE_ANALYTICS` | `false` | Set to `true` to inject Vercel Analytics in production. | -## 隐私与数据边界 +## Privacy and data boundaries -- 图片、二维码、绘图、Markdown、编码和哈希处理在浏览器中完成,项目不会因为这些功能主动上传内容到自建服务器。 -- “获取当前 IP”会请求 `api.ipify.org`;IP 归属查询会请求 `ipinfo.io`。这两个请求只在使用 IP 工具时发生。 -- Vercel Analytics 默认关闭,只有显式设置 `VITE_ENABLE_ANALYTICS=true` 才会启用。 -- Markdown 预览和 HTML 预览会经过 DOMPurify 清理;下载 HTML 前仍应审阅内容,尤其不要把不可信内容当作生产页面直接发布。 +- Images, QR codes, drawings, Markdown, encoding, and hash operations run in the browser; HTooL does not upload those inputs to a project-owned server. +- “Get current IP” calls `api.ipify.org`; IP location lookup calls `ipinfo.io`. These requests happen only when the IP tool is used. +- Vercel Analytics is disabled by default and is enabled only with `VITE_ENABLE_ANALYTICS=true`. +- Markdown and HTML previews are sanitized with DOMPurify. Review downloaded HTML before publishing it, especially when the source is untrusted. -## 项目结构 +## Project structure ```text . -├── public/ # favicon 等静态资源 -├── scripts/ # 性能预算与设计约束检查脚本 +├── public/ # Static assets such as the favicon +├── scripts/ # Performance and design-constraint checks ├── src/ -│ ├── components/ # 跨页面组件 -│ ├── utils/ # 可复用的转换与校验逻辑 -│ ├── views/ # 工具页面 +│ ├── components/ # Shared Vue components +│ ├── utils/ # Reusable conversion and validation logic +│ ├── views/ # Tool pages │ ├── App.vue -│ └── router/ # 路由与按需加载 +│ └── router/ # Routes and lazy loading ├── tests/ -│ ├── component/ # Vue 组件测试 -│ ├── e2e/ # Playwright 端到端流程 -│ └── unit/ # 工具函数与路由测试 -├── .github/ # CI、Issue/PR 模板与依赖更新配置 -└── vercel.json # SPA 部署回退配置 +│ ├── component/ # Vue component tests +│ ├── e2e/ # Playwright end-to-end flows +│ └── unit/ # Utility and router tests +├── .github/ # CI, bilingual templates, and dependency updates +└── vercel.json # SPA deployment fallback ``` -## 部署 +## Deployment -项目可以直接导入 Vercel: +HTooL can be imported directly into Vercel: -1. 在 Vercel 中导入本仓库。 -2. Framework Preset 选择 Vite(通常会自动识别)。 -3. Build Command 使用 `npm run build`。 -4. Output Directory 使用 `dist`。 -5. 如果需要统计,再设置 `VITE_ENABLE_ANALYTICS=true`。 +1. Import this repository in Vercel. +2. Select the Vite framework preset, which is normally detected automatically. +3. Use `npm run build` as the Build Command. +4. Use `dist` as the Output Directory. +5. Set `VITE_ENABLE_ANALYTICS=true` only if analytics are needed. -仓库内的 `vercel.json` 已配置前端路由回退,刷新 `/markdown`、`/qrcode` 等路径时不会被当成静态文件丢失。 +The included `vercel.json` handles SPA route fallback, so refreshing `/markdown`, `/qrcode`, and other client-side routes works as expected. -## 参与贡献 +## Contributing -欢迎提交 Bug 修复、体验改进和新工具。开始之前请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md),提交 Issue 时尽量提供浏览器、复现步骤和截图。 +Bug fixes, UX improvements, and new tools are welcome. Start with [CONTRIBUTING.md](./CONTRIBUTING.md), and include your browser, reproduction steps, and screenshots when opening an Issue. -- [行为准则](./CODE_OF_CONDUCT.md) -- [安全策略](./SECURITY.md) -- [Issue 模板](https://github.com/Hughhhhcoder/HTooL/issues/new/choose) +- [Code of Conduct](./CODE_OF_CONDUCT.md) +- [Security Policy](./SECURITY.md) +- [Issue templates](https://github.com/Hughhhhcoder/HTooL/issues/new/choose) -## 许可证 +## License -当前仓库尚未声明开源许可证。除非仓库后续补充明确的许可证文件,否则代码默认不授予复制、修改或分发权限。 +This repository does not currently declare an open-source license. Unless a license file is added, the code is not granted for copying, modification, or distribution by default. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..1e68533 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,163 @@ +
+ HTooL 图标 +

HTooL

+

一套浏览器优先的实用工具箱,把常用的小工具收进一个克制、顺手的工作台。

+

+ 在线体验 + · + 报告问题 + · + 参与贡献 +

+
+ +

+ 简体中文 · English +

+ +

+ CI 状态 + GitHub Issues + 在线演示 +

+ +## 项目定位 + +HTooL 面向写作、开发和日常信息处理场景,优先把数据留在浏览器中完成处理。它不是一个需要账号和后端服务的复杂平台,而是一组打开即用、按任务分组的轻量工具。 + +## 工具一览 + +| 分组 | 工具 | 能力 | +| --- | --- | --- | +| 文档创作 | Markdown 编辑器 | 编辑、工具栏、实时预览、本地文件夹读写与保存 | +| 文档创作 | Markdown ↔ HTML | 双向转换、预览、复制与下载 | +| 图像与编码 | 图片格式转换 | 单个/批量转换、PNG/JPG/WebP/GIF 选择、质量调节 | +| 图像与编码 | 二维码工具 | 文本/链接生成、尺寸与颜色设置、图片解析、下载 | +| 图像与编码 | 手绘板 | 画笔、橡皮擦、颜色/粗细调节与 PNG 导出 | +| 系统与数据 | 数据处理工具 | 正则测试、URL 编码/解码、Base64、MD5 与 SHA-256 | +| 系统与数据 | IP 地址定位 | 查询 IPv4 的地域、时区与运营商信息 | + +## 主要特点 + +- 浏览器优先:图片转换、二维码、绘图和文本处理默认在本地完成。 +- 按需加载:Markdown、二维码等较重依赖仅在进入对应工具后加载。 +- 克制的界面:响应式布局、浅色/暗色模式,以及明确的任务分组。 +- 可验证的质量门禁:单元测试、组件测试、E2E 流程、构建体积预算和设计约束检查。 +- 可直接部署:Vercel 配置已包含单页应用路由回退规则。 + +## 技术栈 + +- [Vue 3](https://vuejs.org/) + [Vue Router](https://router.vuejs.org/) +- [Vite](https://vite.dev/) +- [Vitest](https://vitest.dev/) + [Vue Test Utils](https://test-utils.vuejs.org/) +- [Playwright](https://playwright.dev/) +- [Marked](https://marked.js.org/) + [Turndown](https://github.com/mixmark-io/turndown) +- [DOMPurify](https://github.com/cure53/DOMPurify) +- [QRCode](https://github.com/soldair/node-qrcode) + [jsQR](https://github.com/cozmo/jsQR) + +## 快速开始 + +### 环境要求 + +- Node.js 20 或更高版本 +- npm 10 或更高版本 +- 需要运行 E2E 测试时,额外安装 Playwright Chromium + +### 本地开发 + +```bash +git clone https://github.com/Hughhhhcoder/HTooL.git +cd HTooL +npm ci +npm run dev +``` + +开发服务器默认地址为 。 + +### 构建与预览 + +```bash +npm run build +npm run preview +``` + +### 运行测试 + +```bash +# 单元测试与组件测试 +npm run test:unit + +# 设计约束检查:禁止 CSS gradient +npm run test:no-gradient + +# 构建产物性能预算检查 +npm run test:perf-budget + +# 首次运行前安装 Playwright 浏览器 +npx playwright install chromium + +# E2E 测试 +npm run test:e2e + +# 聚合检查:单测 + 设计约束 + 构建 + 性能预算 + E2E +npm run check +``` + +## 环境变量 + +复制 `.env.example` 为 `.env` 后按需修改: + +| 变量 | 默认值 | 说明 | +| --- | --- | --- | +| `VITE_ENABLE_ANALYTICS` | `false` | 设置为 `true` 后,在生产环境注入 Vercel Analytics。 | + +## 隐私与数据边界 + +- 图片、二维码、绘图、Markdown、编码和哈希处理在浏览器中完成,项目不会因为这些功能主动上传内容到自建服务器。 +- “获取当前 IP”会请求 `api.ipify.org`;IP 归属查询会请求 `ipinfo.io`。这两个请求只在使用 IP 工具时发生。 +- Vercel Analytics 默认关闭,只有显式设置 `VITE_ENABLE_ANALYTICS=true` 才会启用。 +- Markdown 预览和 HTML 预览会经过 DOMPurify 清理;下载 HTML 前仍应审阅内容,尤其不要把不可信内容当作生产页面直接发布。 + +## 项目结构 + +```text +. +├── public/ # favicon 等静态资源 +├── scripts/ # 性能预算与设计约束检查脚本 +├── src/ +│ ├── components/ # 跨页面组件 +│ ├── utils/ # 可复用的转换与校验逻辑 +│ ├── views/ # 工具页面 +│ ├── App.vue +│ └── router/ # 路由与按需加载 +├── tests/ +│ ├── component/ # Vue 组件测试 +│ ├── e2e/ # Playwright 端到端流程 +│ └── unit/ # 工具函数与路由测试 +├── .github/ # CI、双语模板与依赖更新配置 +└── vercel.json # SPA 部署回退配置 +``` + +## 部署 + +项目可以直接导入 Vercel: + +1. 在 Vercel 中导入本仓库。 +2. Framework Preset 选择 Vite(通常会自动识别)。 +3. Build Command 使用 `npm run build`。 +4. Output Directory 使用 `dist`。 +5. 如果需要统计,再设置 `VITE_ENABLE_ANALYTICS=true`。 + +仓库内的 `vercel.json` 已配置前端路由回退,刷新 `/markdown`、`/qrcode` 等路径时不会被当成静态文件丢失。 + +## 参与贡献 + +欢迎提交 Bug 修复、体验改进和新工具。开始之前请阅读 [贡献指南](./CONTRIBUTING.zh-CN.md),提交 Issue 时尽量提供浏览器、复现步骤和截图。 + +- [行为准则](./CODE_OF_CONDUCT.zh-CN.md) +- [安全策略](./SECURITY.zh-CN.md) +- [Issue 模板](https://github.com/Hughhhhcoder/HTooL/issues/new/choose) + +## 许可证 + +当前仓库尚未声明开源许可证。除非仓库后续补充明确的许可证文件,否则代码默认不授予复制、修改或分发权限。 diff --git a/SECURITY.md b/SECURITY.md index 9fde7c4..a060f52 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,21 +1,23 @@ -# 安全策略 +# Security Policy -## 支持范围 +

English · 简体中文

-目前项目没有正式发布版本,默认仅维护 `master` 分支上的最新代码。 +## Supported scope -| 版本/分支 | 支持情况 | +HTooL does not have formal releases yet. Security reports are handled against the latest code on the `master` branch. + +| Version/branch | Support | | --- | --- | -| `master` | ✅ 接受安全问题报告 | -| 其他旧提交 | ❌ 不提供修复承诺 | +| `master` | ✅ Security reports accepted | +| Older commits | ❌ No fix commitment | -## 报告漏洞 +## Reporting a vulnerability -请不要在公开 Issue 中发布可被利用的漏洞、攻击脚本或敏感数据。请通过 [维护者主页](https://github.com/Hughhhhcoder) 的公开联系方式私下报告,并尽量附上: +Do not publish exploitable vulnerabilities, attack scripts, or sensitive data in a public Issue. Please contact the maintainer privately through the [maintainer profile](https://github.com/Hughhhhcoder) and include, when possible: -- 影响范围和复现步骤; -- 浏览器、操作系统和项目版本; -- 最小化的复现样例; -- 你认为合理的修复建议(如果有)。 +- impact and reproduction steps; +- browser, operating system, and project version; +- a minimal reproduction case; +- a suggested fix, if you have one. -收到报告后,维护者会先确认问题,再评估影响范围、修复方式和公开时间。 +The maintainer will acknowledge the report, assess its impact, and coordinate the fix and disclosure timing. diff --git a/SECURITY.zh-CN.md b/SECURITY.zh-CN.md new file mode 100644 index 0000000..ec6bbe8 --- /dev/null +++ b/SECURITY.zh-CN.md @@ -0,0 +1,23 @@ +# 安全策略 + +

English · 简体中文

+ +## 支持范围 + +目前项目没有正式发布版本,默认仅维护 `master` 分支上的最新代码。 + +| 版本/分支 | 支持情况 | +| --- | --- | +| `master` | ✅ 接受安全问题报告 | +| 其他旧提交 | ❌ 不提供修复承诺 | + +## 报告漏洞 + +请不要在公开 Issue 中发布可被利用的漏洞、攻击脚本或敏感数据。请通过 [维护者主页](https://github.com/Hughhhhcoder) 的公开联系方式私下报告,并尽量附上: + +- 影响范围和复现步骤; +- 浏览器、操作系统和项目版本; +- 最小化的复现样例; +- 你认为合理的修复建议(如果有)。 + +收到报告后,维护者会先确认问题,再评估影响范围、修复方式和公开时间。