Skip to main content

R：资源路径调度器

R 类是一个静态工具类，负责锚定项目的根目录。它能自动识别当前运行环境（开发模式 vs 打包模式），并提供简便的接口来访问 res 目录下的 UI、图像和其他资源。

1. 导入模块​

# 导入资源管理类
from ascript.windows.system import R

2. 开发者常用接口 (工程资源)​

这些接口主要用于获取开发者自己编写的脚本工程中 res 文件夹下的文件路径。

🌐 获取 UI 路径 ui()​

获取工程中 res/ui/ 目录下的 HTML 或相关资源文件路径。

代码块：

# 获取 UI 文件路径
R.ui(path)

参数详解：

  • path (str): 相对于 res/ui/ 的文件名或子路径。

🖼️ 获取图像路径 img()​

获取工程中 res/img/ 目录下的图片文件路径，常用于图色识别。

代码块：

# 获取图片路径
R.img(path)

参数详解：

  • path (str): 相对于 res/img/ 的图片文件名。

📦 获取通用资源路径 res()​

获取工程 res/ 根目录下的任何文件路径。

代码块：

# 获取通用资源
R.res(path)

参数详解：

  • path (str): 相对于 res/ 的文件路径。

3. 内部资源接口 (AScript 核心资源)​

⚙️ 获取内置资源 internal()​

该方法供 AScript 框架内部调用，用于查找 AScript 包自身携带的内置网页、图标或配置文件。

代码块：

# 查找 AScript 内部文件
R.internal(*sub_paths)

参数详解：

  • *sub_paths (str): 变长参数，代表包内的层级结构。
    • 示例：R.internal("windows", "tools", "web", "index.html")

4. 环境适配原理​

R 类内部实现了复杂的路径自适应逻辑，解决了脚本在“打包成 EXE”后的路径偏移问题：

运行环境路径锚定策略
开发模式以 main.py 所在的物理文件夹作为根目录。
Nuitka 打包优先读取环境变量 NUITKA_ONEFILE_PARENT 获取解压临时目录。
PyInstaller 打包通过 sys._MEIPASS 获取单文件解压目录。
** site-packages**AScript 核心资源会锚定 ascript 库安装的物理位置。

💡 案例演示​

from ascript.windows.ui import WebWindow
from ascript.windows.system import R, FindImages

# 1. 加载工程中的 UI 界面
# 实际指向：工程目录/res/ui/login.html
win = WebWindow(R.ui("login.html"))

# 2. 进行图色识别时使用资源路径
# 实际指向：工程目录/res/img/start_btn.png
btn_path = R.img("start_btn.png")
pos = FindImages.find_all_template(btn_path)

# 3. 打印当前工程的根目录
print(f"项目运行在: {R.get_root()}")

⚠️ 调试小贴士​

如果文件存在但 R 方法返回了路径，控制台会输出如下警告：

⚠️ [R] 找不到路径: C:\YourProject\res\ui\missing.html
ℹ️ [R] 当前基准目录为: C:\YourProject

当你看到此类警告时，请检查：

  1. 文件名拼写（