Skip to content

Commit e81e338

Browse files
001ProMax001ProMax
committed
v2.4.6
0 parents  commit e81e338

File tree

982 files changed

+157426
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

982 files changed

+157426
-0
lines changed

‎.gitignore‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Local
2+
.DS_Store
3+
*.local
4+
*.log*
5+
6+
# Dist
7+
node_modules
8+
dist/
9+
doc_build/
10+
11+
# IDE
12+
.vscode/*
13+
!.vscode/extensions.json
14+
.idea
15+
16+
Scripting Documentation
17+
Scripting Documentation.zip
18+
19+
doc_build.zip
20+
doc_build_fun/
21+
doc_build_fun.zip

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Scripting 官方文档项目
2+
3+
## 项目简介
4+
5+
通过 `Scripting Documentation` (Scripting App 默认脚本) 生成网页文档
6+
7+
## 快速开始
8+
9+
1. 将 `Scripting Documentation` (Scripting App 默认脚本) 放入项目根目录并解压
10+
11+
2. 运行文档生成命令：
12+
13+
```bash
14+
bun run generate:docs
15+
```
16+
17+
3. 运行构建命令：
18+
19+
```bash
20+
bun run build
21+
```

‎bun.lock‎

Lines changed: 678 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/en/_nav.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[
2+
{
3+
"text": "docs",
4+
"link": "/doc/Quick%20Start",
5+
"activeMatch": "/doc/"
6+
},
7+
{
8+
"text": "privacy",
9+
"link": "/privacy/policy",
10+
"activeMatch": "/privacy/"
11+
},
12+
{
13+
"text": "Version",
14+
"items": [
15+
{
16+
"text": "TestFlight",
17+
"link": "https://scriptingapp.github.io"
18+
}
19+
]
20+
}
21+
]

‎docs/en/doc/AppIntent.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: AppIntent
3+
4+
---
5+
6+
`AppIntentManager` is used to **register and manage AppIntents** in the **Scripting** app. It serves as the core mechanism for executing script logic behind controls in **Widgets**, **Live Activities**, and **ControlWidgets**.
7+
8+
All `AppIntent`s **must** be defined in the `app_intents.tsx` file. When an intent is executed, the script runs in the `"app_intents"` environment (`Script.env === "app_intents"`).
9+
10+
Once registered, these intents can be triggered by **Button** and **Toggle** controls within Widgets, Live Activities, or ControlWidgets, allowing users to define interactive behavior via script.
11+
12+
---
13+
14+
## 1. Type Definitions
15+
16+
### `AppIntent<T>`
17+
18+
Represents a concrete intent instance with parameters and metadata.
19+
20+
| Property | Type | Description |
21+
| ---------- | ------------------- | -------------------------------------------------------------------------- |
22+
| `script` | `string` | The internal script path. Automatically generated by the system. |
23+
| `name` | `string` | The name of the AppIntent. Must be unique. |
24+
| `protocol` | `AppIntentProtocol` | The protocol the intent conforms to (e.g., general, audio, Live Activity). |
25+
| `params` | `T` | The parameters to be passed when the intent is executed. |
26+
27+
---
28+
29+
### `AppIntentFactory<T>`
30+
31+
A **factory function** that creates an `AppIntent` instance with specified parameters.
32+
33+
```ts
34+
type AppIntentFactory<T> = (params: T) => AppIntent<T>
35+
```
36+
37+
---
38+
39+
### `AppIntentPerform<T>`
40+
41+
A function that handles intent execution logic asynchronously.
42+
43+
```ts
44+
type AppIntentPerform<T> = (params: T) => Promise<void>
45+
```
46+
47+
---
48+
49+
### `AppIntentProtocol`
50+
51+
An enumeration that defines the behavior type of the intent.
52+
53+
| Enum Value | Description |
54+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
55+
| `AppIntent` (0) | A general-purpose AppIntent for typical operations. |
56+
| `AudioPlaybackIntent` (1) | An intent that plays, pauses, or otherwise modifies audio playback. |
57+
| `AudioRecordingIntent` (2) | *(iOS 18.0+)* An intent that starts, stops, or modifies audio recording. **Note**: On iOS/iPadOS, when using the `AudioRecordingIntent` protocol, you must start a **Live Activity** at the beginning of the recording and keep it active for the entire session. If you don't, the recording will be automatically stopped. |
58+
| `LiveActivityIntent` (3) | An intent that starts, pauses, or modifies a Live Activity. |
59+
60+
---
61+
62+
## 2. `AppIntentManager` Class
63+
64+
### `AppIntentManager.register<T>(options): AppIntentFactory<T>`
65+
66+
Registers a new `AppIntent` by specifying its name, protocol, and perform logic. When a control (e.g., Button or Toggle) triggers the intent, the associated `perform` function is called.
67+
68+
```ts
69+
static register<T = undefined>(options: {
70+
name: string;
71+
protocol: AppIntentProtocol;
72+
perform: AppIntentPerform<T>;
73+
}): AppIntentFactory<T>
74+
```
75+
76+
#### Parameters:
77+
78+
| Property | Type | Description |
79+
| ---------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
80+
| `name` | `string` | A unique identifier for the AppIntent. |
81+
| `protocol` | `AppIntentProtocol` | The protocol this intent implements. |
82+
| `perform` | `AppIntentPerform<T>` | The asynchronous function executed when the intent is triggered. The `params` argument is passed from the control. |
83+
84+
#### Returns:
85+
86+
* **`AppIntentFactory<T>`**: A factory function that creates an `AppIntent` instance with the specified parameters.
87+
88+
#### Example:
89+
90+
```tsx
91+
// app_intents.tsx
92+
export const ToggleDoorIntent = AppIntentManager.register({
93+
name: "ToggleDoorIntent",
94+
protocol: AppIntentProtocol.AppIntent,
95+
perform: async ({ id, newState }: { id: string; newState: boolean }) => {
96+
// Custom logic: toggle the door state
97+
await setDoorState(id, newState)
98+
// Notify UI to refresh toggle state
99+
ControlWidget.reloadToggles()
100+
}
101+
})
102+
```
103+
104+
In a control view file (e.g., `control_widget_toggle.tsx`):
105+
106+
```tsx
107+
ControlWidget.present(
108+
<ControlWidgetToggle
109+
intent={ToggleDoorIntent({ id: "door1", newState: !currentState })}
110+
label={{
111+
title: "Door 1",
112+
systemImage: currentState ? "door.garage.opened" : "door.garage.closed"
113+
}}
114+
activeValueLabel={{ title: "The door is opened" }}
115+
inactiveValueLabel={{ title: "The door is closed" }}
116+
/>
117+
)
118+
```
119+
120+
In a widget file (`widget.tsx`):
121+
122+
```tsx
123+
<Toggle
124+
title="Door 1"
125+
value={currentState}
126+
intent={ToggleDoorIntent({ id: "door1", newState: !currentState })}
127+
/>
128+
```
129+
130+
---
131+
132+
## 3. Execution Environment
133+
134+
All AppIntents registered via `AppIntentManager` are executed in the `"app_intents"` environment.
135+
This allows safe use of APIs suitable for background execution, such as:
136+
137+
* Fetching data from the network
138+
* Controlling Live Activities
139+
* Triggering control view refreshes
140+
141+
---
142+
143+
## 4. Best Practices
144+
145+
1. **Centralized Definitions**: All AppIntents **must** be defined in `app_intents.tsx` for discoverability and maintainability.
146+
2. **Strong Typing**: Define explicit parameter types `T` for both `perform` and control usage to benefit from type checking and autocomplete.
147+
3. **Choose the Right Protocol**:
148+
149+
* General operation → `AppIntent`
150+
* Audio playback → `AudioPlaybackIntent`
151+
* Audio recording → `AudioRecordingIntent` *(requires iOS 18+, with Live Activity)*
152+
* Live Activity control → `LiveActivityIntent`
153+
4. **Trigger UI Updates**: If the intent modifies a UI state (e.g., toggle), call:
154+
155+
* `ControlWidget.reloadButtons()`
156+
* `ControlWidget.reloadToggles()`
157+
* `Widget.reloadAll()`
158+
depending on where the control is hosted.

0 commit comments

Comments
 (0)