Skip to content

docs: make README.md the primary English doc; add Chinese README.zh-CN.md with full API coverage #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 1 commit into
base: master
Choose a base branch
from
+271 −20
Draft

docs: make README.md the primary English doc; add Chinese README.zh-CN.md with full API coverage #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 122 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,47 +1,149 @@
# XFEExtension.NetCore.InputSimulator

## 简介
[![NuGet Version](https://img.shields.io/nuget/v/XFEExtension.NetCore.InputSimulator.svg)](https://www.nuget.org/packages/XFEExtension.NetCore.InputSimulator/)
[![NuGet Downloads](https://img.shields.io/nuget/dt/XFEExtension.NetCore.InputSimulator.svg)](https://www.nuget.org/packages/XFEExtension.NetCore.InputSimulator/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![.NET](https://img.shields.io/badge/.NET-8.0-purple.svg)](https://dotnet.microsoft.com/download/dotnet/8.0)

InputSimulator是一个简单的模拟键盘输入的包，其中包含了模拟键盘按键输入和鼠标输入
**English** | [简体中文](README.zh-CN.md)

## 用法
## Introduction

### 模拟键盘输入
XFEExtension.NetCore.InputSimulator is a lightweight library for simulating user input on Windows. It supports keyboard key simulation, mouse control, and clipboard read/write operations.

## Installation

Install via NuGet Package Manager:

```
Install-Package XFEExtension.NetCore.InputSimulator
```

Or via .NET CLI:

```
dotnet add package XFEExtension.NetCore.InputSimulator
```

## Usage

### Keyboard Simulation

```csharp
using XFEExtension.NetCore.InputSimulator;

InputSimulator.PressKey('X');//按下X按键
InputSimulator.InputKeys("XFE");//顺序按下 X、F、E 按键
InputSimulator.KeyDown('A'); // Hold down the A key
InputSimulator.KeyUp('A'); // Release the A key
InputSimulator.PressKey('X'); // Press and release the X key
InputSimulator.InputKeys("XFE"); // Press X, F, E keys in sequence

// Async: hold a key for the specified duration (ms) then release
await InputSimulator.PressKeyAsync('A', holdTime: 500);

// Async: press a sequence of keys with per-key hold time and inter-key delay
await InputSimulator.InputKeysAsync("XFE", holdTime: 100, delay: 50);
```

### 模拟鼠标移动
### Mouse Movement

```csharp
using XFEExtension.NetCore.InputSimulator;

InputSimulator.Move(100, 100);//使得鼠标从当前位置相对移动 100 x 100 个像素（相对于鼠标指针的当前位置）
InputSimulator.LocateTo(1900, 202);//使得鼠标移动至绝对坐标 1900,202 的位置处（相对于整个屏幕的位置）
InputSimulator.LocateTo(new Point(0, 0));//使得鼠标移动至绝对坐标（0, 0）的位置处（相对于整个屏幕的位置）
InputSimulator.LocateTo(ScreenPosition.TopLeft);//使得鼠标移动至屏幕的左上角，即（0, 0）的位置处（相对于整个屏幕的位置）
// Relative movement: move the mouse 100 pixels in both X and Y from its current position
InputSimulator.MouseMove(100, 100);

// Absolute positioning
InputSimulator.LocateTo(1900, 202);
InputSimulator.LocateTo(new Point(0, 0));

Comment on lines +56 to +58
// Move to a predefined screen position (TopLeft / Top / TopRight / Left / Center / Right / BottomLeft / Bottom / BottomRight)
InputSimulator.LocateTo(ScreenPosition.TopLeft);
InputSimulator.LocateTo(ScreenPosition.Center);
```

### 模拟鼠标点击
### Mouse Click

```csharp
using XFEExtension.NetCore.InputSimulator;

InputSimulator.MouseClick(MouseButton.Left);//模拟鼠标左键点击
InputSimulator.MouseWhellRoll(-800);//模拟鼠标滚轮下滑800像素
InputSimulator.MouseClick(MouseButton.Left); // Simulate a left mouse button click
InputSimulator.MouseClick(MouseButton.Right); // Simulate a right mouse button click
InputSimulator.MouseClick(MouseButton.Middle); // Simulate a middle mouse button click

// Async: hold the mouse button for the specified duration (ms) then release
await InputSimulator.MouseClickAsync(MouseButton.Left, holdTime: 1000);

// Simulate mouse wheel scroll (negative = scroll down, positive = scroll up)
InputSimulator.MouseWhellRoll(-800);
```

### 获取信息
### System Information

```csharp
using XFEExtension.NetCore.InputSimulator;

var screenSize = GetScreenSize();//获取屏幕的宽和高（像素）
var mousePoint = GetMousePosition();//获取鼠标的位置
var percentage = GetMousePointRelatively();//获取鼠标相对于屏幕的比值（范围是0-1的double型百分比）
var isLeftMouseDown = GetMouseDown(MouseButton.Left);//获取鼠标左键是否被按下
```
Point screenSize = InputSimulator.GetScreenSize(); // Screen resolution (width x height)
Point mousePos = InputSimulator.GetMousePosition(); // Current mouse cursor position
(double X, double Y) rel = InputSimulator.GetMousePointRelatively(); // Mouse position as a ratio of screen size (0.0–1.0)
Comment on lines +85 to +87
bool isDown = InputSimulator.GetMouseDown(MouseButton.Left); // Check whether the left mouse button is held down
double scale = InputSimulator.GetScalingFactorForWindow(hWnd); // DPI scaling factor for a given window handle
```

### Clipboard

```csharp
using XFEExtension.NetCore.InputSimulator;

// Write text to the clipboard
Clipboard.SetClipboardContent("Hello, XFE!");

// Read content from the clipboard
object? content = Clipboard.GetClipboardContent();

// Use a custom clipboard format (default is CF_UNICODETEXT)
Clipboard.SetClipboardContent("Hello", ClipboardFormat.CF_TEXT);
```

## API Reference

### `InputSimulator` Static Class

| Method | Description |
|--------|-------------|
| `KeyDown(char key)` | Hold down the specified key |
| `KeyUp(char key)` | Release the specified key |
| `PressKey(char key)` | Press and immediately release the specified key |
| `PressKeyAsync(char key, int holdTime)` | Hold the key for the given duration then release (async) |
| `InputKeys(string keys)` | Press each character in the string in sequence |
| `InputKeysAsync(string keys, int holdTime, int delay)` | Press each key with configurable hold time and delay (async) |
| `MouseMove(int x, int y)` | Move the mouse relative to its current position |
| `LocateTo(int x, int y)` | Move the mouse to an absolute screen coordinate |
| `LocateTo(Point point)` | Move the mouse to the specified `Point` |
| `LocateTo(ScreenPosition pos)` | Move the mouse to a predefined screen position |
| `MouseClick(MouseButton button)` | Simulate a mouse button click |
| `MouseClickAsync(MouseButton button, int holdTime)` | Hold a mouse button for the given duration then release (async) |
| `MouseWhellRoll(int length)` | Simulate mouse wheel scrolling |
| `GetMouseDown(MouseButton button)` | Check whether the specified mouse button is currently pressed |
| `GetScreenSize()` | Get the screen resolution |
| `GetMousePosition()` | Get the current mouse cursor position |
| `GetMousePointRelatively()` | Get the mouse position as a ratio of the screen dimensions |
| `GetScalingFactorForWindow(nint hWnd)` | Get the DPI scaling factor for the specified window |

### `Clipboard` Static Class

| Method | Description |
|--------|-------------|
| `SetClipboardContent(string text, uint format)` | Write text to the clipboard |
| `GetClipboardContent(uint format)` | Read content from the clipboard |
Comment on lines +136 to +137

### `ScreenPosition` Enum

`TopLeft` · `Top` · `TopRight` · `Left` · `Center` · `Right` · `BottomLeft` · `Bottom` · `BottomRight`

### `MouseButton` Enum

`Left` · `Right` · `Middle`

## License

This project is licensed under the [MIT License](LICENSE).
149 changes: 149 additions & 0 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
# XFEExtension.NetCore.InputSimulator

[![NuGet 版本](https://img.shields.io/nuget/v/XFEExtension.NetCore.InputSimulator.svg)](https://www.nuget.org/packages/XFEExtension.NetCore.InputSimulator/)
[![NuGet 下载量](https://img.shields.io/nuget/dt/XFEExtension.NetCore.InputSimulator.svg)](https://www.nuget.org/packages/XFEExtension.NetCore.InputSimulator/)
[![许可证: MIT](https://img.shields.io/badge/许可证-MIT-yellow.svg)](LICENSE)
[![.NET](https://img.shields.io/badge/.NET-8.0-purple.svg)](https://dotnet.microsoft.com/download/dotnet/8.0)

[English](README.md) | **简体中文**

## 简介

InputSimulator 是一个简单的模拟用户输入的包，支持模拟键盘按键输入、鼠标操作以及剪切板读写。

## 安装

通过 NuGet 包管理器安装：

```
Install-Package XFEExtension.NetCore.InputSimulator
```

或通过 .NET CLI：

```
dotnet add package XFEExtension.NetCore.InputSimulator
```

## 用法

### 模拟键盘输入

```csharp
using XFEExtension.NetCore.InputSimulator;

InputSimulator.KeyDown('A'); // 按住 A 键
InputSimulator.KeyUp('A'); // 松开 A 键
InputSimulator.PressKey('X'); // 按下并松开 X 键
InputSimulator.InputKeys("XFE"); // 顺序按下 X、F、E 键

// 异步方法：按住按键指定时间（毫秒）后松开
await InputSimulator.PressKeyAsync('A', holdTime: 500);

// 异步方法：以指定的按住时间和间隔延迟输入一组按键
await InputSimulator.InputKeysAsync("XFE", holdTime: 100, delay: 50);
```

### 模拟鼠标移动

```csharp
using XFEExtension.NetCore.InputSimulator;

// 相对移动：从当前位置偏移 100, 100 像素
InputSimulator.MouseMove(100, 100);

// 绝对定位
InputSimulator.LocateTo(1900, 202);
InputSimulator.LocateTo(new Point(0, 0));

Comment on lines +56 to +58
// 定位到屏幕预设位置（TopLeft / Top / TopRight / Left / Center / Right / BottomLeft / Bottom / BottomRight）
InputSimulator.LocateTo(ScreenPosition.TopLeft);
InputSimulator.LocateTo(ScreenPosition.Center);
```

### 模拟鼠标点击

```csharp
using XFEExtension.NetCore.InputSimulator;

InputSimulator.MouseClick(MouseButton.Left); // 模拟鼠标左键单击
InputSimulator.MouseClick(MouseButton.Right); // 模拟鼠标右键单击
InputSimulator.MouseClick(MouseButton.Middle); // 模拟鼠标中键单击

// 异步方法：按住鼠标按键指定时间（毫秒）后松开
await InputSimulator.MouseClickAsync(MouseButton.Left, holdTime: 1000);

// 模拟鼠标滚轮滚动（负值向下，正值向上）
InputSimulator.MouseWhellRoll(-800);
```

### 获取系统信息

```csharp
using XFEExtension.NetCore.InputSimulator;

Point screenSize = InputSimulator.GetScreenSize(); // 获取屏幕分辨率（宽 x 高）
Point mousePos = InputSimulator.GetMousePosition(); // 获取鼠标当前坐标
(double X, double Y) rel = InputSimulator.GetMousePointRelatively(); // 获取鼠标位置占屏幕比例（0~1）
Comment on lines +85 to +87
bool isDown = InputSimulator.GetMouseDown(MouseButton.Left); // 检测鼠标左键是否按下
double scale = InputSimulator.GetScalingFactorForWindow(hWnd); // 获取指定窗口的 DPI 缩放倍率
```

### 剪切板操作

```csharp
using XFEExtension.NetCore.InputSimulator;

// 写入文本到剪切板
Clipboard.SetClipboardContent("Hello, XFE!");

// 读取剪切板内容
object? content = Clipboard.GetClipboardContent();

// 使用自定义格式（默认为 CF_UNICODETEXT）
Clipboard.SetClipboardContent("Hello", ClipboardFormat.CF_TEXT);
```

## API 参考

### `InputSimulator` 静态类

| 方法 | 说明 |
|------|------|
| `KeyDown(char key)` | 按住指定按键 |
| `KeyUp(char key)` | 松开指定按键 |
| `PressKey(char key)` | 按下并立即松开指定按键 |
| `PressKeyAsync(char key, int holdTime)` | 按住指定按键一段时间后松开（异步） |
| `InputKeys(string keys)` | 依次按下字符串中的每个按键 |
| `InputKeysAsync(string keys, int holdTime, int delay)` | 依次按下每个按键，支持按住时长和间隔延迟（异步） |
| `MouseMove(int x, int y)` | 相对于当前位置移动鼠标 |
| `LocateTo(int x, int y)` | 将鼠标移至绝对坐标 |
| `LocateTo(Point point)` | 将鼠标移至指定 Point |
| `LocateTo(ScreenPosition pos)` | 将鼠标移至预设屏幕位置 |
| `MouseClick(MouseButton button)` | 模拟鼠标单击 |
| `MouseClickAsync(MouseButton button, int holdTime)` | 模拟鼠标长按后松开（异步） |
| `MouseWhellRoll(int length)` | 模拟鼠标滚轮滚动 |
| `GetMouseDown(MouseButton button)` | 检测指定鼠标按键是否被按下 |
| `GetScreenSize()` | 获取屏幕分辨率 |
| `GetMousePosition()` | 获取鼠标当前位置 |
| `GetMousePointRelatively()` | 获取鼠标相对屏幕的位置比例 |
| `GetScalingFactorForWindow(nint hWnd)` | 获取窗口 DPI 缩放倍率 |

### `Clipboard` 静态类

| 方法 | 说明 |
|------|------|
| `SetClipboardContent(string text, uint format)` | 将文本写入剪切板 |
| `GetClipboardContent(uint format)` | 从剪切板读取内容 |
Comment on lines +136 to +137

### `ScreenPosition` 枚举

`TopLeft` · `Top` · `TopRight` · `Left` · `Center` · `Right` · `BottomLeft` · `Bottom` · `BottomRight`

### `MouseButton` 枚举

`Left` · `Right` · `Middle`

## 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。