Skip to content

Commit a2c1011

Browse files
001ProMax001ProMax
committed
release
1 parent 2205d49 commit a2c1011

File tree

1,014 files changed

+101732
-3513
lines changed

Some content is hidden

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

1,014 files changed

+101732
-3513
lines changed

‎Scripting Documentation/accented_widget_styling/en.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
iOS 18 introduces a new widget rendering mode called **accented mode**, which tints the widget’s content using system-defined accent colors. To support this behavior in your widgets, the **Scripting** app provides three view modifiers:
2+
3+
* `widgetAccentable`
4+
* `widgetAccentedRenderingMode`
5+
* `widgetBackground`
6+
7+
These modifiers allow you to control which parts of your widget participate in the system’s accenting logic, enabling more expressive and adaptable designs.
8+
9+
---
10+
11+
## `widgetAccentable`
12+
13+
### Description
14+
15+
Marks a view and all of its subviews as part of the **accented group**. When a widget is displayed in **accented rendering mode**, the system applies a distinct tint color to the accented group and another to the default group. The colors are applied as if views were template images — the system ignores any explicit color and only uses the view’s alpha channel.
16+
17+
This modifier helps create layered visual effects, especially useful in tinted widgets where you want to differentiate between elements.
18+
19+
### Usage
20+
21+
```tsx
22+
<VStack>
23+
<Text
24+
widgetAccentable
25+
font="caption"
26+
>
27+
MON
28+
</Text>
29+
<Text font="title">
30+
6
31+
</Text>
32+
</VStack>
33+
```
34+
35+
In the above example:
36+
37+
* The first `Text` is added to the **accented group**, and will be tinted with the accent color.
38+
* The second `Text` belongs to the **default group**, and will be tinted with the default (typically lighter) color.
39+
40+
---
41+
42+
## `widgetAccentedRenderingMode` (for `Image` components)
43+
44+
### Description
45+
46+
Defines how an `Image` should be rendered when displayed in **accented widget mode**. This modifier allows you to fine-tune how image content responds to system tinting.
47+
48+
### Available Modes
49+
50+
* `'accented'`: Renders the image as part of the **accented group**, using the accent color.
51+
* `'accentedDesaturated'`: Converts the image’s luminance to alpha and applies the accent color.
52+
* `'desaturated'`: Converts the image’s luminance to alpha and applies the default group color.
53+
* `'fullColor'`: Preserves the image’s original colors with no tinting — available only on iOS.
54+
55+
### Usage
56+
57+
```tsx
58+
<Image
59+
filePath="/path/to/image.png"
60+
widgetAccentedRenderingMode="fullColor"
61+
/>
62+
```
63+
64+
This ensures the image will retain its full color and not be affected by system tints — useful for branding elements or complex images where tinting would degrade clarity.
65+
66+
---
67+
68+
## `widgetBackground`
69+
70+
### Description
71+
72+
The `widgetBackground` modifier allows you to define background colors or shapes in a way that automatically adapts to **accented mode**. When the widget is displayed in accented mode, the background is **automatically hidden** to avoid being forced into a white or unintended rendering by the system.
73+
74+
This modifier is especially important because iOS 18 **ignores background colors** in accented mode, unless transparency (`alpha`) is used. With `widgetBackground`, you can safely define decorative backgrounds without worrying about white overlays.
75+
76+
### Supported Formats
77+
78+
You can use the following formats:
79+
80+
#### Solid Color
81+
82+
```tsx
83+
<Text widgetBackground="systemGray5">
84+
Hello
85+
</Text>
86+
```
87+
88+
#### Dynamic Light/Dark Color
89+
90+
```tsx
91+
<Text
92+
widgetBackground={{
93+
light: "white",
94+
dark: "black"
95+
}}
96+
>
97+
Mode-aware Background
98+
</Text>
99+
```
100+
101+
#### Shape with Style
102+
103+
```tsx
104+
<Text
105+
widgetBackground={{
106+
style: "systemGray6",
107+
shape: {
108+
type: "rect",
109+
cornerRadius: 12,
110+
style: "continuous"
111+
}
112+
}}
113+
>
114+
Shaped Background
115+
</Text>
116+
```
117+
118+
### Notes
119+
120+
* Background is hidden in **accented mode**.
121+
* Background is fully rendered in **default or full-color modes**.
122+
* Works seamlessly with `widgetAccentable` and layering effects.
123+
124+
---
125+
126+
## Behavior Notes (iOS 18+ Specific)
127+
128+
* In **tinted mode**, **all colors (including background colors)** are ignored unless alpha is less than `1`. This means setting a solid background color will be rendered as white if not made semi-transparent.
129+
* Use `alpha` values to introduce visual hierarchy. For example, a fully opaque accentable element (`alpha = 1`) will be strongly tinted, while one with `alpha = 0.3` will appear more subtle.
130+
* **Do not rely on color values** directly for styling in accented widgets — use tint layering via the accent group instead.
131+
* **Use `widgetBackground`** instead of `background` when defining decorative backgrounds, to ensure proper behavior under accenting.
132+
133+
---
134+
135+
## Example
136+
137+
```tsx
138+
<VStack
139+
widgetBackground={{
140+
style: "systemGray6",
141+
shape: {
142+
type: "rect",
143+
cornerRadius: 12
144+
}
145+
}}
146+
spacing={4}
147+
>
148+
<Image
149+
filePath="/path/to/icons/calendar.png"
150+
widgetAccentedRenderingMode="accentedDesaturated"
151+
/>
152+
<Text widgetAccentable font="caption">
153+
MON
154+
</Text>
155+
<Text font="title">
156+
6
157+
</Text>
158+
</VStack>
159+
```
160+
161+
This layout:
162+
163+
* Applies a rounded background that is visible only in non-accented modes.
164+
* Places the icon and weekday label in the **accented group**.
165+
* Leaves the date number in the **default group**.
166+
* Maintains consistent visual separation, even with iOS's tinting behavior.
167+
168+
---
169+
170+
## Tips
171+
172+
* Use `widgetAccentable` to group multiple views into the accent layer — don’t apply it to the entire widget unless necessary.
173+
* For icons or logos, consider using `widgetAccentedRenderingMode="fullColor"` if the image must retain its original branding.
174+
* Use `widgetBackground` in place of `background` to ensure backgrounds disappear cleanly in accented mode.
175+
* Use semi-transparent fills (`alpha < 1`) for layered effects that survive tint flattening.
176+
177+
---
178+
179+
This setup ensures your widgets are fully optimized for iOS 18’s dynamic accenting system, while retaining control over visual composition and user experience.

‎Scripting Documentation/accented_widget_styling/zh.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
iOS 18 引入了一种新的小组件渲染模式，称为 **accented 模式（强调色模式）**，它会使用系统定义的强调色对小组件的内容进行统一染色。为支持该行为，**Scripting** app 提供了三个视图修饰符：
2+
3+
* `widgetAccentable`
4+
* `widgetAccentedRenderingMode`
5+
* `widgetBackground`
6+
7+
这些修饰符让你可以精确控制小组件中哪些部分参与系统的染色逻辑，从而创建更具层次感和适配性的界面。
8+
9+
---
10+
11+
## `widgetAccentable`
12+
13+
### 说明
14+
15+
将视图及其所有子视图标记为 **accented group（强调组）** 的一部分。当小组件处于 **accented 渲染模式** 时，系统会分别为强调组与默认组应用不同的色调。染色过程仿照模板图像的方式 —— 系统会忽略你设置的颜色，仅使用视图的 alpha（透明度）进行渲染。
16+
17+
这个修饰符有助于在 tinted 小组件中实现清晰的层次分离效果。
18+
19+
### 用法示例
20+
21+
```tsx
22+
<VStack>
23+
<Text
24+
widgetAccentable
25+
font="caption"
26+
>
27+
MON
28+
</Text>
29+
<Text font="title">
30+
6
31+
</Text>
32+
</VStack>
33+
```
34+
35+
说明：
36+
37+
* 第一个 `Text` 使用了 `widgetAccentable`，将被系统染色为强调色；
38+
* 第二个 `Text` 属于默认组，通常被染为较浅的颜色。
39+
40+
---
41+
42+
## `widgetAccentedRenderingMode`（用于 `Image` 组件）
43+
44+
### 说明
45+
46+
控制 `Image` 在 **accented 模式** 下的渲染方式。可用于调整图像在染色模式下的外观处理。
47+
48+
### 可用模式
49+
50+
* `'accented'`：将图像加入强调组，使用强调色渲染。
51+
* `'accentedDesaturated'`：将图像亮度转为 alpha 后使用强调色染色。
52+
* `'desaturated'`：将图像亮度转为 alpha 后使用默认组色调染色。
53+
* `'fullColor'`：保留图像原始颜色，不进行染色（仅适用于 iOS 系统图像）。
54+
55+
### 用法示例
56+
57+
```tsx
58+
<Image
59+
filePath="/path/to/image.png"
60+
widgetAccentedRenderingMode="fullColor"
61+
/>
62+
```
63+
64+
该设置可确保图像保留完整颜色，适合用于品牌 Logo 或需要保持清晰度的图像内容。
65+
66+
---
67+
68+
## `widgetBackground`
69+
70+
### 说明
71+
72+
`widgetBackground` 修饰符用于在小组件中设置背景样式，**并自动适配 iOS 18 的 accented 模式**。当小组件处于 accented 模式时，该背景会**自动隐藏**，避免被系统强制染色为白色。
73+
74+
iOS 18 会忽略背景颜色，除非设置透明度（alpha）。使用 `widgetBackground` 可以放心地定义装饰性背景，而不必担心其在染色模式下显示异常。
75+
76+
### 支持格式
77+
78+
#### 纯色背景
79+
80+
```tsx
81+
<Text widgetBackground="systemGray5">
82+
Hello
83+
</Text>
84+
```
85+
86+
#### 浅色/深色模式适配背景
87+
88+
```tsx
89+
<Text
90+
widgetBackground={{
91+
light: "white",
92+
dark: "black"
93+
}}
94+
>
95+
模式感知背景
96+
</Text>
97+
```
98+
99+
#### 带形状的背景
100+
101+
```tsx
102+
<Text
103+
widgetBackground={{
104+
style: "systemGray6",
105+
shape: {
106+
type: "rect",
107+
cornerRadius: 12,
108+
style: "continuous"
109+
}
110+
}}
111+
>
112+
圆角背景
113+
</Text>
114+
```
115+
116+
> 提示：可用形状包括 `'rect'`、`'circle'`、`'capsule'`、`'ellipse'`、`'buttonBorder'`、`'containerRelative'`，也支持自定义圆角矩形。
117+
118+
### 特性说明
119+
120+
* 在 **accented 模式** 下，背景会被自动隐藏；
121+
* 在 **默认或全彩模式** 下，背景正常显示；
122+
* 与 `widgetAccentable` 配合使用，可实现分层布局，保持视觉清晰度。
123+
124+
---
125+
126+
## 系统行为说明（适用于 iOS 18+）
127+
128+
* 在 **accented 模式** 中，**所有颜色（包括背景）都会被忽略**，除非设置了 `alpha < 1`。例如纯色背景会被渲染为白色。
129+
* 通过 **设置 alpha 值** 可实现视觉层级，例如 `alpha = 1` 会获得强烈染色效果，而 `alpha = 0.3` 更加柔和。
130+
* **不要依赖具体颜色值** 来控制样式，在 accented 模式下颜色会被系统统一替换，应通过分组和透明度控制样式。
131+
* **推荐使用 `widgetBackground` 代替 `background`**，以确保背景在 accented 模式下能够被正确隐藏。
132+
133+
---
134+
135+
## 示例
136+
137+
```tsx
138+
<VStack
139+
widgetBackground={{
140+
style: "systemGray6",
141+
shape: {
142+
type: "rect",
143+
cornerRadius: 12
144+
}
145+
}}
146+
spacing={4}
147+
>
148+
<Image
149+
filePath="/path/to/icons/calendar.png"
150+
widgetAccentedRenderingMode="accentedDesaturated"
151+
/>
152+
<Text widgetAccentable font="caption">
153+
MON
154+
</Text>
155+
<Text font="title">
156+
6
157+
</Text>
158+
</VStack>
159+
```
160+
161+
该布局：
162+
163+
* 设置了一个圆角灰色背景，仅在非 accented 模式下显示；
164+
* 图标和星期标签加入了 **强调组**；
165+
* 日期数字保留在 **默认组**；
166+
* 即便系统进行染色，也能保持清晰的分层效果。
167+
168+
---
169+
170+
## 使用技巧
171+
172+
* 使用 `widgetAccentable` 精确标记需要染色的内容，避免误将整个小组件标记为强调组；
173+
* 对于品牌图标等需要保留原色的图像，使用 `widgetAccentedRenderingMode="fullColor"`；
174+
* 使用 `widgetBackground` 替代 `background`，以确保背景能在强调模式下正确处理；
175+
* 为背景或视图设置透明度（如 `alpha < 1`）可保留层次感，避免全部被染为纯白。

0 commit comments

Comments
 (0)