Skip to content

Commit 34ebe85

Browse files
001ProMax001ProMax
committed
Updates
0 parents  commit 34ebe85

File tree

2,690 files changed

+440627
-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.

2,690 files changed

+440627
-0
lines changed

‎.gitignore‎

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

‎404.html‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head><meta charset="utf-8">
4+
<meta name="viewport" content="width=device-width, initial-scale=1">
5+
<title>404 - Scripting</title>
6+
<script>{;const saved = localStorage.getItem('rspress-theme-appearance');const preferDark = window.matchMedia('(prefers-color-scheme: dark)').matches;const isDark = !saved || saved === 'auto' ? preferDark : saved === 'dark';document.documentElement.classList.toggle('dark', isDark);document.documentElement.classList.toggle('rp-dark', isDark);document.documentElement.style.colorScheme = isDark ? 'dark' : 'light';}</script>
7+
<link href="/static/css/styles.053d335d.css" rel="stylesheet">
8+
<script defer src="/static/js/styles.340079cb.js"></script>
9+
<script defer src="/static/js/lib-react.5edd1b77.js"></script>
10+
<script defer src="/static/js/lib-router.db7238c9.js"></script>
11+
<script defer src="/static/js/78699.ab32cbfe.js"></script>
12+
<script defer src="/static/js/index.a0628583.js"></script>
13+
<meta http-equiv="X-UA-Compatible" content="IE=edge">
14+
<meta name="generator" content="Rspress v2.0.0-rc.7">
15+
<link rel="icon" href="/icon.png">
16+
<meta property="og:type" content="website">
17+
<meta property="og:title" content="404 - Scripting">
18+
<meta name="description" content="Static Site Generator"></head>
19+
20+
<body>
21+
<div id="__rspress_root"><link rel="preload" as="image" href="/logo.png"/><header class="rp-nav"><div class="rp-nav__left"><div class="rp-nav__title"><a href="/" class="rp-nav__title__link rp-link"><div class="rp-nav__title__logo"><img src="/logo.png" alt="logo" id="logo" class="rspress-logo rp-nav__title__logo-image"/></div><span>Scripting</span></a></div></div><div class="rp-nav__right"><button class="rp-search-button"><div class="rp-search-button__content"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="none" viewBox="0 0 20 21" class="rp-search-button__icon"><path fill="currentColor" d="M8.333 1.913A6.667 6.667 0 0 1 15 8.58c0 1.54-.525 2.957-1.402 4.085l4.49 4.492a.834.834 0 0 1-1.177 1.178l-4.491-4.49a6.64 6.64 0 0 1-4.087 1.402 6.667 6.667 0 0 1 0-13.334m0 1.667a5 5 0 1 0 0 10 5 5 0 0 0 0-10"></path></svg><span class="rp-search-button__word">Search</span></div><div class="rp-search-button__hotkey" style="opacity:0"><span></span><span>K</span></div></button><div class="rp-search-button--mobile"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="none" viewBox="0 0 20 21"><path fill="currentColor" d="M8.333 1.913A6.667 6.667 0 0 1 15 8.58c0 1.54-.525 2.957-1.402 4.085l4.49 4.492a.834.834 0 0 1-1.177 1.178l-4.491-4.49a6.64 6.64 0 0 1-4.087 1.402 6.667 6.667 0 0 1 0-13.334m0 1.667a5 5 0 1 0 0 10 5 5 0 0 0 0-10"></path></svg></div><ul class="rp-nav-menu rp-nav-menu--right"><li class="rp-nav-menu__item rspress-nav-menu-item"><a href="/doc/Quick Start.html" class="rp-nav-menu__item__container rp-link">Documentation</a></li><li class="rp-nav-menu__item rspress-nav-menu-item"><a href="/privacy/policy.html" class="rp-nav-menu__item__container rp-link">Privacy</a></li><li class="rp-nav-menu__item"><div class="rp-nav-menu__item__container">Version<svg width="1em" height="1em" viewBox="0 0 32 32" class="rp-nav-menu__item__icon"><path fill="currentColor" d="M16 22 6 12l1.4-1.4 8.6 8.6 8.6-8.6L26 12z"></path></svg></div><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--center"><li class="rp-hover-group__item" style="padding-left:8px" data-depth="0"><a href="https://scriptingapp.github.io" target="_blank" rel="noopener noreferrer" class="rp-hover-group__item__link rp-link" aria-label="TestFlight">TestFlight</a></li></ul></li></ul><div class="rp-nav__others"><div class="rp-nav-menu__divider"></div><li class="rp-nav-menu__item"><div class="rp-nav-menu__item__container">English<svg width="1em" height="1em" viewBox="0 0 32 32" class="rp-nav-menu__item__icon"><path fill="currentColor" d="M16 22 6 12l1.4-1.4 8.6 8.6 8.6-8.6L26 12z"></path></svg></div><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--center"><li class="rp-hover-group__item rp-hover-group__item--active" style="padding-left:8px" data-depth="0"><a href="/" class="rp-hover-group__item__link rp-link" aria-label="English">English</a></li><li class="rp-hover-group__item" style="padding-left:8px" data-depth="0"><a href="/zh/index.html" class="rp-hover-group__item__link rp-link" aria-label="简体中文">简体中文</a></li></ul></li><div class="rp-switch-appearance"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="currentColor" viewBox="0 0 24 24" class="rp-switch-appearance__icon rp-switch-appearance__icon--sun"><path fill="currentColor" d="m7.001 15.848-1.226 1.226a.58.58 0 0 0 0 .818.58.58 0 0 0 .818 0l1.226-1.226a.58.58 0 0 0 0-.818.58.58 0 0 0-.818 0m-.352-8.735a.584.584 0 0 0 .825-.825L6.237 5.051a.584.584 0 0 0-.825.825zM5.011 11.07h-1.75a.584.584 0 0 0 0 1.167h1.75c.324 0 .584-.26.584-.583a.585.585 0 0 0-.584-.584m7.003-5.835c.324 0 .584-.26.584-.584V2.9a.58.58 0 0 0-.584-.584.58.58 0 0 0-.583.583V4.65c0 .323.262.584.583.584m5.616 1.621 1.226-1.225a.58.58 0 0 0 0-.818.58.58 0 0 0-.818 0l-1.226 1.225a.58.58 0 0 0 0 .818.576.576 0 0 0 .818 0m3.138 4.214h-1.75a.58.58 0 0 0-.584.584c0 .324.26.584.583.584h1.751a.584.584 0 1 0 0-1.167m-3.389 5.124a.584.584 0 0 0-.825.825l1.238 1.238a.584.584 0 0 0 .825-.826zm-5.365-9.795a5.256 5.256 0 0 0-5.257 5.258 5.256 5.256 0 0 0 5.257 5.257 5.256 5.256 0 0 0 5.257-5.257 5.256 5.256 0 0 0-5.257-5.258m0 11.675a.58.58 0 0 0-.583.583v1.751a.582.582 0 1 0 1.167 0v-1.75a.584.584 0 0 0-.584-.584"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="19" height="19" fill="currentColor" viewBox="0 0 19 19" class="rp-switch-appearance__icon rp-switch-appearance__icon--moon"><path fill="currentColor" d="M9.166 0a9.2 9.2 0 0 1 1.857.188.834.834 0 0 1 .042 1.623 4.47 4.47 0 1 0 5.457 5.457l.048-.135a.834.834 0 0 1 1.575.177q.186.902.188 1.856A9.168 9.168 0 1 1 9.166 0"></path></svg></div><div class="rp-social-links"><a href="https://github.com/ScriptingApp" target="_blank" rel="noopener noreferrer" class="rp-social-links__item"><div class="rp-social-links__icon"><div class="rp-social-links__icon"><svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg></div></div></a><a href="https://x.com/thomfang" target="_blank" rel="noopener noreferrer" class="rp-social-links__item"><div class="rp-social-links__icon"><div class="rp-social-links__icon"><svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 24 24"><path fill="currentColor" d="M18.901 1.153h3.68l-8.04 9.19L24 22.846h-7.406l-5.8-7.584l-6.638 7.584H.474l8.6-9.83L0 1.154h7.594l5.243 6.932ZM17.61 20.644h2.039L6.486 3.24H4.298Z"/></svg></div></div></a><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--right"></ul></div></div><button aria-label="mobile hamburger" class="rp-nav-hamburger rp-nav-hamburger__sm"><svg xmlns="http://www.w3.org/2000/svg" width="21" height="21" fill="none" viewBox="0 0 21 21"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.667" d="M3.645 5.225h13.333M3.645 10.225h13.333M3.645 15.225h13.333"></path></svg></button><button aria-label="mobile hamburger" class="rp-nav-hamburger rp-nav-hamburger__md"><svg xmlns="http://www.w3.org/2000/svg" width="21" height="21" fill="none" viewBox="0 0 21 21"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.667" d="M3.645 5.225h13.333M3.645 10.225h13.333M3.645 15.225h13.333"></path></svg><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--right"><div class="rp-nav-menu__others-mobile__container"><div class="rp-nav-hamburger__md__hover-group"><div class="rp-nav-screen-appearance"><div class="rp-nav-screen-appearance__left">Theme</div><div class="rp-nav-screen-appearance__right"></div></div><div class="rp-nav-screen-langs"><div class="rp-nav-screen-langs__left">Languages</div><div class="rp-nav-screen-langs__right">English<svg width="1em" height="1em" viewBox="0 0 32 32" class="rp-nav-screen-langs__icon "><path fill="currentColor" d="M16 22 6 12l1.4-1.4 8.6 8.6 8.6-8.6L26 12z"></path></svg></div></div><div class="rp-nav-screen-langs-group" style="display:grid;grid-template-rows:0fr;transition:grid-template-rows 0.2s ease-out"><div class="rp-nav-screen-langs-group__inner"><span class="rp-nav-screen-langs-group__item rp-nav-screen-langs-group__item--active" aria-current="page" aria-disabled="true">English</span><a href="/zh/index.html" class="rp-nav-screen-langs-group__item rp-link">简体中文</a></div></div><div class="rp-nav-screen-divider"></div><div class="rp-social-links"><a href="https://github.com/ScriptingApp" target="_blank" rel="noopener noreferrer" class="rp-social-links__item"><div class="rp-social-links__icon"><div class="rp-social-links__icon"><svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg></div></div></a><a href="https://x.com/thomfang" target="_blank" rel="noopener noreferrer" class="rp-social-links__item"><div class="rp-social-links__icon"><div class="rp-social-links__icon"><svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 24 24"><path fill="currentColor" d="M18.901 1.153h3.68l-8.04 9.19L24 22.846h-7.406l-5.8-7.584l-6.638 7.584H.474l8.6-9.83L0 1.154h7.594l5.243 6.932ZM17.61 20.644h2.039L6.486 3.24H4.298Z"/></svg></div></div></a><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--right"></ul></div></div></div></ul></button></div></header><div class="rp-not-found"><p class="rp-not-found__error-code">404</p><h1 class="rp-not-found__title">PAGE NOT FOUND</h1><div class="rp-not-found__divider"></div><div class="rp-not-found__action"><a href="/" class="rp-not-found__home-link rp-link" aria-label="go to home">Take me home</a></div></div></div>
22+
<div id="__rspress_modal_container"></div>
23+
</body>
24+
</html>

‎doc/AppIntent.html‎

Lines changed: 126 additions & 0 deletions
Large diffs are not rendered by default.

‎doc/AppIntent.md‎

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

0 commit comments

Comments
 (0)