# circuitjs1

**Repository Path**: creedassin/circuitjs1

## Basic Information

- **Project Name**: circuitjs1
- **Description**: 电路仿真工具
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CircuitJS1

## 简介

CircuitJS1 是一款运行在浏览器中的电子电路模拟器。它最初由 Paul Falstad 以 Java 小程序（Java Applet）的形式编写，后经 Iain Sharp 适配，采用 GWT（Google Web Toolkit）技术实现浏览器端运行。

你可以通过以下托管版本体验该应用：
- Paul 的官方页面：[http://www.falstad.com/circuit/](http://www.falstad.com/circuit/)
- Iain 的适配页面：[http://lushprojects.com/circuitjs/](http://lushprojects.com/circuitjs/)

致谢名单：
- Edward Calver：新增 15 种元器件及其他功能优化
- Rodrigo Hausen：实现文件导入/导出功能及多项 UI 改进
- J. Mike Rollins：齐纳二极管（Zener diode）相关代码实现
- Julius Schmidt：火花隙（spark gap）代码及部分示例电路
- Dustin Soodak：UI 交互体验优化支持
- Jacob Calvert：T 触发器（T Flip Flop）功能实现
- Ben Hayden：示波器频谱（scope spectrum）功能
- Thomas Reitinger、Krystian Sławiński、Usevalad Khatkevich、Lucio Sciamanna、Mauro Hemerly Gazzani、J. Miguel Silva、Franck Viard：多语言翻译支持
- Andre Adrian：改进发射极耦合振荡器（emitter coupled oscillator）
- Felthry：提供大量示例电路
- Colin Howell：代码性能优化
- LZString 库：© 2013 pieroxy

## 构建 Web 应用

该 Web 应用可通过 Eclipse 本地编译运行，也可在 GitHub Codespaces 或 gitpod.io 等云开发容器中构建。这两个云服务每月提供一定时长的免费使用额度，你也可以在本地 Linux 机器或 Docker 容器中通过 `./dev.sh` 脚本使用云开发工具。

### 使用 Eclipse 进行开发

构建项目需准备以下工具：
- Eclipse Oxygen 版本
- Eclipse 的 GWT 插件

安装步骤：
1. 从 [Eclipse 官网](https://www.eclipse.org/downloads/packages/) 下载“Eclipse for Java developers”
2. 按照 [GWT 插件安装指南](https://gwt-plugins.github.io/documentation/gwt-eclipse-plugin/Download.html) 安装 Eclipse 的 GWT 插件

本仓库可直接作为 Eclipse 项目目录使用。获取本地副本后，可通过以下方式构建运行：
- 开发模式运行：点击工具栏“运行”图标，在弹出的“Development Mode”标签中选择 `http://127.0.0.1:8888/circuitjs.html`
- 部署构建：选中项目根节点，点击 Eclipse 任务栏的 GWT 按钮，选择“GWT Compile Project...”（GWT 编译项目）

GWT 编译输出文件将保存至“war”目录：
- 该目录下的 `iframe.html` 文件会以内嵌框架（iFrame）形式加载在应用右侧面板底部的空白区域，可用于添加品牌标识等自定义内容

### 使用云容器进行开发

1. 安装 [Visual Studio Code](https://code.visualstudio.com/) 及对应远程扩展：
   - [Gitpod 扩展](https://marketplace.visualstudio.com/items?itemName=gitpod.gitpod-desktop)
   - 或 [Codespaces 扩展](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces)
2. 在所选云服务的开发容器中打开 `circuitjs1` 仓库的分支
3. 浏览器将新建标签页打开 VS Code，点击左下角绿色按钮，在弹出菜单中选择“Open in VS Code Desktop”（在 VS Code 桌面端打开），允许所有 URL 弹窗并通过 GitHub 授权登录

成功将本地 VS Code 连接至远程工作区后，按以下步骤配置：
4. 打开容器终端：按 `Ctrl+反引号` 或按 `F1` 输入“Create new Terminal”（新建终端）
5. 确保终端当前目录为容器内的 `/workspaces/circuitjs1`（仅新容器首次需确认）
6. 运行 `./dev.sh setup` 安装所有开发依赖（包括 GWT 和 Java）
7. 运行 `./dev.sh start` 启动 Web 服务器和 GWT 代码服务器，将启动两个服务：
   - http://localhost:8000（应用访问地址）
   - http://localhost:9876（代码服务器地址）
8. 在“Ports”（端口）标签页中确认 8000 和 9876 端口已转发
9. 编辑 VS Code 中的 Java 文件后，刷新 http://localhost:8000 即可自动重新编译，代码服务器（http://localhost:9876）会加载编译后的 JavaScript 及对应的源映射文件，修改内容将实时生效

> **注意**：
> 1. 远程开发容器中运行 Web 服务器时，需通过本地 VS Code 进行端口转发，才能从本地访问远程服务
> 2. 理论上可使用浏览器端 VS Code 界面，但 Gitpod 和 Codespaces 会将转发端口映射到不同域名（而非不同端口），导致 GWT 代码加载器异常。虽可通过自定义 HTTP 服务器实时修改 `circuitjs1.nocache.js` 中的 `serverUrl` 变量修复，但需将端口设置为“公开”以避免跨域重定向错误，建议优先使用本地 VS Code 连接远程容器

### 使用 Gradle 进行开发

通过 Gradle 构建应用的步骤如下：
```bash
# 1. 运行Gradle构建并输出详细信息：
gradle compileGwt --console verbose --info
# 2. 从构建文件创建网站目录：
gradle makeSite --console verbose --info
```

构建完成后，直接用浏览器打开 `site/circuitjs.html` 即可使用！

也可在 GitHub Codespaces 中执行上述步骤，创建 `site` 目录后，通过以下命令启动 Web 服务器：
```bash
cd site
python3 -m http.server
```

在“Ports”标签页中，hover 到“Forwarded Address”（转发地址）点击“Follow Link”（跟随链接），再点击 `circuitjs.html` 即可访问应用。

## Web 应用部署

1. 编译项目：
   - 按上述 Eclipse 开发指南执行“GWT Compile Project...”，或运行 `./dev.sh compile`
   - 编译输出文件将保存至 Eclipse 项目的“war”目录
2. 服务器部署：
   - 将“war”目录中除“WEB-INF”外的所有文件复制到 Web 服务器
   - 自定义 `circuitjs1.html` 文件头部，添加统计代码、网站图标（favicon）等
   - 编辑 `iframe.html` 文件，在应用右侧面板添加品牌标识等自定义内容
3. 可选配置：
   - `shortrelay.php`：服务器端脚本，用于转发 URL 缩短服务请求以避免纯客户端解决方案的跨域问题，可根据自身网站需求自定义；无需该功能可在编译前编辑 `circuitjs1.java` 文件禁用
   - Dropbox 功能：如需支持 Dropbox 加载/保存电路，需在 `circuitjs.html` 中添加 Dropbox API 密钥，未添加则相关功能自动禁用

应用全页版本的访问链接为：
`http://<你的服务器地址>/<应用路径>/circuitjs1.html`
（可修改 `circuitjs1.html` 文件名，但需同步更新 `shortrelay.php` 中的对应引用）

服务器文件目录结构参考：
```
-+ 应用首页所在目录（例："circuitjs"）
  +- circuitjs.html - 应用全页版本入口文件
  +- iframe.html - 右侧面板内嵌框架文件（见上文说明）
  +- shortrelay.php - URL缩短服务转发脚本（见上文说明）
  ++ circuitjs1（目录）
   +- GWT编译生成的各类文件
   +- circuits（目录，存放示例电路）
   +- setuplist.txt（示例电路目录索引文件）
```

## Docker/podman 容器部署

### 构建并运行 Circuitjs 容器

（如需使用 Docker，将以下命令中的 podman 替换为 docker 即可）

1. 构建 Docker 镜像：
```
podman build -f circuitjs1.Containerfile -t circuitjs1:latest
```

2. 运行 Docker 容器：
```
podman run --name=circuitjs1 --rm -d -p 8000:8000 circuitjs1:latest
```

应用访问地址：http://localhost:8000/circuitjs.html

### 容器化开发环境搭建

（如需使用 Docker，将以下命令中的 podman 替换为 docker 即可）

1. 构建开发环境镜像：
```
podman build -f dev-start.Containerfile -t circuitjs1-dev:latest
```

2. 运行开发容器：
```
podman run --rm -it -p 127.0.0.1:8000:8000/tcp -p 127.0.0.1:9876:9876/tcp circuitjs1-dev:latest
```

应用访问地址：http://localhost:8000/circuitjs.html

如需在容器运行时修改文件（支持 GWT 自动构建）：
```
podman run --rm -it -v $(pwd):/src:Z  -p 127.0.0.1:8000:8000/tcp -p 127.0.0.1:9876:9876/tcp  circuitjs1-dev:latest
```
该命令会将本地当前目录挂载到容器内的 `/src` 目录，本地文件修改将实时同步至容器

## 嵌入其他页面

1. 直接链接：可通过上文所述全页版本链接直接访问应用
2. 内嵌嵌入：使用 `<iframe>` 标签将全页版本嵌入其他页面，示例如下：
   ```html
   <iframe src="http://<你的服务器地址>/<应用路径>/circuitjs1.html" width="100%" height="800"></iframe>
   ```

### 启动参数配置

可通过 URL 查询参数自定义应用启动行为，支持以下参数：
```
.../circuitjs.html?cct=<字符串> // 从URL中加载电路（类似Java版本的#参数）
.../circuitjs.html?ctz=<字符串> // 从URL中的压缩数据加载电路
.../circuitjs.html?startCircuit=<文件名> // 从"Circuits"目录加载指定名称的电路
.../circuitjs.html?startCircuitLink=<URL> // 从指定URL加载电路（当前仅支持Dropbox共享文件或其他支持客户端跨域访问的URL）
.../circuitjs.html?euroResistors=true // 强制使用"欧式"电阻样式（未指定时根据浏览器语言偏好自动选择）
.../circuitjs.html?IECGates=true // 强制使用IEC标准逻辑门样式（未指定时根据浏览器语言偏好自动选择）
.../circuitjs.html?usResistors=true // 强制使用"美式"电阻样式（未指定时根据浏览器语言偏好自动选择）
.../circuitjs.html?whiteBackground=<true|false> // 设置白色背景（true/false）
.../circuitjs.html?conventionalCurrent=<true|false> // 设置传统电流方向（true/false）
.../circuitjs.html?running=<true|false> // 启动时是否自动运行仿真（默认true）
.../circuitjs.html?hideSidebar=<true|false> // 是否隐藏侧边栏（默认false）
.../circuitjs.html?hideMenu=<true|false> // 是否隐藏菜单（默认false）
.../circuitjs.html?editable=<true|false> // 是否允许编辑电路（默认true）
.../circuitjs.html?positiveColor=%2300ff00 // 修改正向电压颜色（格式：rrggbb，示例为绿色）
.../circuitjs.html?negativeColor=%23ff0000 // 修改反向电压颜色（示例为红色）
.../circuitjs.html?selectColor=%2300ffff // 修改选中元素颜色（示例为青色）
.../circuitjs.html?currentColor=%23ffff00 // 修改电流颜色（示例为黄色）
.../circuitjs.html?mouseWheelEdit=<true|false> // 是否允许通过鼠标滚轮修改参数值（默认true）
.../circuitjs.html?mouseMode=<项> // 设置初始鼠标模式，也可指定启动时执行的UI操作（如打开"关于"菜单、执行"本地文件导入"等）
.../circuitjs.html?hideInfoBox=<true|false> // 是否隐藏信息框（默认false）
```

模拟器还支持与自定义 JavaScript 代码交互，示例参考：[war/jsinterface.html](http://www.falstad.com/circuit/jsinterface.html)

## 构建 Electron 应用

[Electron](https://electronjs.org/) 可将 Web 应用打包为多平台本地可执行文件，本仓库包含构建 CircuitJS1 Electron 应用所需的额外文件。

Electron 应用的通用打包流程参考 [Electron 官方文档](https://electronjs.org/docs/tutorial/application-distribution)，以下是 CircuitJS1 的专属打包步骤：
1. 按上述方法通过 GWT 编译 Web 应用
2. 下载对应目标平台的 [Electron 预编译二进制包](https://github.com/electron/electron/releases)（推荐 9.3.2 版本）并解压
3. 将本仓库中的“app”目录复制到 Electron 二进制包的指定目录（参考 [Electron 目录结构要求](https://electronjs.org/docs/tutorial/application-distribution)）
4. 将包含编译后 CircuitJS1 应用的“war”目录复制到上述“app”目录中
5. 运行“Electron”可执行文件，将自动加载 CircuitJS1 应用

Electron 版本已知限制：
- “Export as URL”（导出为 URL）中的“Create short URL”（创建短链接）功能不可用（依赖服务器支持）

致谢：@Immortalin 为 CircuitJS1 适配 Electron 提供了初始实现

## 许可证

本程序是自由软件，你可以根据自由软件基金会发布的 GNU 通用公共许可证（GNU General Public License）的条款重新分发和/或修改它：
- 许可证版本：第 2 版或（可选）任何更新版本

本程序的发布旨在提供有用的功能，但不提供任何明示或暗示的担保，包括但不限于对适销性和特定用途适用性的担保。有关详细信息，请参阅 GNU 通用公共许可证。

你应该已收到随本程序一同分发的 GNU 通用公共许可证副本；如果没有，请致函：
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA（美国马萨诸塞州波士顿市富兰克林街 51 号 5 楼，自由软件基金会）