docs: update to v2.4.1

Author: 001ProMax

Scripting Documentation/doc.json

@@ -93,6 +93,32 @@
       }
     ]
   },
+  {
+    "title": {
+      "en": "Control Widget",
+      "zh": "控制中心的小组件"
+    },
+    "subtitle": {
+      "en": "Add custom Button or Toggle controls to the Control Center or Lock Screen",
+      "zh": "在控制中心或锁屏界面添加按钮（Button）或开关（Toggle）控件。"
+    },
+    "readme": "control_widget/"
+  },
+  {
+    "title": {
+      "en": "AppIntent",
+      "zh": "AppIntent"
+    },
+    "subtitle": {
+      "en": "This interface serves as the core mechanism for executing script logic behind controls in Widgets, Live Activities, and ControlWidgets.",
+      "zh": "AppIntent 为小组件，灵动岛和控制中心的控件提供了执行脚本逻辑的核心机制。"
+    },
+    "keywords": [
+      "AppIntentManager",
+      "AppIntentProtocol"
+    ],
+    "readme": "app_intents/"
+  },
   {
     "title": {
       "en": "Intent",
@@ -563,6 +589,17 @@
         },
         "readme": "views/link/"
       },
+      {
+        "title": {
+          "en": "SVG",
+          "zh": "SVG"
+        },
+        "subtitle": {
+          "en": "This view can be used to render SVG images.",
+          "zh": "这个视图可以用来渲染SVG图像。"
+        },
+        "readme": "views/svg/"
+      },
       {
         "title": {
           "en": "Menu",
@@ -2181,6 +2218,28 @@
           "zh": "该修饰符用于为视图层级提供翻译服务的上下文环境。"
         },
         "readme": "view_modifiers/translation_host/"
+      },
+      {
+        "title": {
+          "en": "layoutPriority",
+          "zh": "布局优先级"
+        },
+        "subtitle": {
+          "en": "This view modifier specifies a layout priority for a view.",
+          "zh": "该修饰符用于为视图指定布局优先级。"
+        },
+        "readme": "view_modifiers/layout_priority/"
+      },
+      {
+        "title": {
+          "en": "Chaining View Modifiers",
+          "zh": "可链式调用的修饰符"
+        },
+        "subtitle": {
+          "en": "This view modifier allows you to chain multiple modifiers together, supporting the same modifier being used multiple times in the same view.",
+          "zh": "该修饰符可用于连续调用多个修饰符，支持同一个修饰符在同一个视图中多次使用。"
+        },
+        "readme": "view_modifiers/modifiers/"
       }
     ]
   },
@@ -2211,6 +2270,17 @@
     ],
     "readme": "interactive_widget_and_liveactivity/"
   },
+  {
+    "title": {
+      "en": "Custom Keyboard",
+      "zh": "自定义键盘"
+    },
+    "subtitle": {
+      "en": "Create custom keyboards with unique layouts and functionalities.",
+      "zh": "创建具有独特布局和功能的自定义键盘。"
+    },
+    "readme": "custom_keyboard/"
+  },
   {
     "title": {
       "en": "Assistant",
@@ -2243,7 +2313,9 @@
       "zh": "你可以通过该接口访问当前脚本的运行信息、终止脚本并返回结果、在脚本之间调用、以及生成 URL Scheme 以打开或运行脚本。"
     },
     "readme": "script/",
-    "keywords": ["URL Scheme"]
+    "keywords": [
+      "URL Scheme"
+    ]
   },
   {
     "title": {
@@ -2258,7 +2330,7 @@
       {
         "title": {
           "en": "Data",
-          "zh": "数据"
+          "zh": "二进制数据（Data）"
         },
         "subtitle": {
           "en": "This class represents binary data and provides methods to convert between various formats.",
@@ -3235,7 +3307,9 @@
           "en": "This interface allows you to send messages using the device's messaging capabilities, such as SMS or iMessage.",
           "zh": "该接口允许您使用设备的消息功能发送信息，例如短信或 iMessage。"
         },
-        "keywords": ["MessageUI"],
+        "keywords": [
+          "MessageUI"
+        ],
         "readme": "message_ui/"
       },
       {
@@ -3276,6 +3350,73 @@
           "zh": "该接口提供语言翻译功能，允许您在不同语言之间翻译文本。"
         },
         "readme": "translation/"
+      },
+      {
+        "title": {
+          "en": "Bluetooth",
+          "zh": "蓝牙"
+        },
+        "subtitle": {
+          "en": "This interface provides classes to scan, connect, and exchange data with Bluetooth devices.",
+          "zh": "提供蓝牙相关的API，允许你扫描、连接和与蓝牙设备交换数据。"
+        },
+        "children": [
+          {
+            "title": {
+              "en": "BluetoothCentralManager",
+              "zh": "蓝牙中央设备管理器"
+            },
+            "subtitle": {
+              "en": "This interface allows you to scan for, connect to, and interact with nearby Bluetooth peripherals.",
+              "zh": "该接口允许你扫描、连接和与附近的蓝牙外设进行交互。"
+            },
+            "readme": "bluetooth/central_manager/"
+          },
+          {
+            "title": {
+              "en": "BluetoothPeripheral",
+              "zh": "蓝牙外设"
+            },
+            "subtitle": {
+              "en": "This interface provides properties and methods for interacting with the device, including connecting, discovering services and characteristics, reading/writing values, and subscribing to notifications.",
+              "zh": "表示一个 BLE 外围设备对象，支持读取设备信息、连接状态、发现服务与特征值、读取写入数据、订阅通知等。"
+            },
+            "readme": "bluetooth/peripheral/"
+          },
+          {
+            "title": {
+              "en": "BluetoothService",
+              "zh": "蓝牙服务"
+            },
+            "subtitle": {
+              "en": "This interface represents a Bluetooth Low Energy (BLE) service. A service is a logical grouping of related characteristics and possibly other included services.",
+              "zh": "表示一个 BLE（低功耗蓝牙）服务。服务是外围设备中功能的逻辑分组，包含一个或多个特征值（`Characteristic`），也可以包含对其他服务的引用（包含服务）。"
+            },
+            "readme": "bluetooth/service/"
+          },
+          {
+            "title": {
+              "en": "BluetoothCharacteristic",
+              "zh": "蓝牙服务特征值"
+            },
+            "subtitle": {
+              "en": "This interface represents a Bluetooth Low Energy (BLE) service. A service is a logical grouping of related characteristics and possibly other included services.",
+              "zh": "表示蓝牙服务（`BluetoothService`）中的一个特征值，是 BLE 设备数据交互的核心单元。"
+            },
+            "readme": "bluetooth/characteristic/"
+          },
+          {
+            "title": {
+              "en": "BluetoothPeripheralManager",
+              "zh": "蓝牙外设管理器"
+            },
+            "subtitle": {
+              "en": "This interface allows you to create a Bluetooth peripheral that can advertise services and characteristics, and accept connections from central devices.",
+              "zh": "该接口允许你创建一个蓝牙外设，可以广播服务和特征，并接受来自中央设备的连接。"
+            },
+            "readme": "bluetooth/peripheral_manager/"
+          }
+        ]
       }
     ]
   }

Scripting Documentation/location/en.md

@@ -1,4 +1,4 @@
-The global `Location` API provides access to the device’s geographic location, including one-time location retrieval, reverse geocoding, user-driven location selection via map, and accuracy control. It also supports permission checking for widgets that need location updates.
+The global `Location` API provides access to the device’s geographic location, including one-time location retrieval, reverse geocoding, user-driven location selection via map, accuracy control, and permission checking for widgets.
 
 ---
 
@@ -51,23 +51,32 @@ await Location.setAccuracy("hundredMeters")
 
 ---
 
-### `Location.requestCurrent(): Promise<LocationInfo | null>`
+### `Location.requestCurrent(options?: { forceRequest?: boolean }): Promise<LocationInfo | null>`
 
 Requests the user's current location once. May trigger a permission prompt if not previously granted.
 
+By default, if a cached location is available, it will be returned immediately. If no cached location exists, a new request will be made. To force a new location retrieval even if a cached value exists, pass `{ forceRequest: true }`.
+
+#### Parameters
+
+| Option         | Type      | Required | Description                                                     |
+| -------------- | --------- | -------- | --------------------------------------------------------------- |
+| `forceRequest` | `boolean` | No       | If `true`, bypasses the cache and always requests new location. |
+
 ```ts
-const location = await Location.requestCurrent()
+const location = await Location.requestCurrent({ forceRequest: true })
 if (location) {
   console.log("Latitude:", location.latitude)
   console.log("Longitude:", location.longitude)
+  console.log("Timestamp:", location.timestamp)
 }
 ```
 
 ---
 
 ### `Location.pickFromMap(): Promise<LocationInfo | null>`
 
-Opens the built-in map interface to allow the user to pick a location manually.
+Opens the built-in map interface to allow the user to manually select a location.
 
 ```ts
 const selected = await Location.pickFromMap()
@@ -110,7 +119,7 @@ if (placemarks?.length) {
 
 ### `LocationAccuracy`
 
-Specifies the accuracy of the location data:
+Specifies the desired accuracy of location data:
 
 ```ts
 type LocationAccuracy =
@@ -125,20 +134,30 @@ type LocationAccuracy =
 
 ### `LocationInfo`
 
-Represents a geographic coordinate:
+Represents a geographic coordinate with timestamp:
 
 ```ts
 type LocationInfo = {
+  /**
+   * The latitude in degrees.
+   */
   latitude: number
+  /**
+   * The longitude in degrees.
+   */
   longitude: number
+  /**
+   * Timestamp of when the location was recorded, in milliseconds since epoch.
+   */
+  timestamp: number
 }
 ```
 
 ---
 
 ### `LocationPlacemark`
 
-Represents a human-readable description of a geographic coordinate, typically returned by reverse geocoding. It contains structured location details, such as street, city, region, country, and points of interest.
+Represents a human-readable description of a geographic coordinate, typically returned by reverse geocoding. Includes structured location details such as city, country, and street.
 
 ```ts
 type LocationPlacemark = {
@@ -161,30 +180,32 @@ type LocationPlacemark = {
 }
 ```
 
-### Field Descriptions
-
-| Field                   | Type           | Description                                                                                  |
-| ----------------------- | -------------- | -------------------------------------------------------------------------------------------- |
-| `location`              | `LocationInfo` | The latitude and longitude of the placemark (usually the same as the reverse geocode input). |
-| `region`                | `string`       | A general regional name, such as a province or state.                                        |
-| `timeZone`              | `string`       | The time zone identifier (e.g., `"Asia/Shanghai"`).                                          |
-| `name`                  | `string`       | A generic name for the place, such as a building or landmark.                                |
-| `thoroughfare`          | `string`       | The street name, such as `"Main Street"` or `"Zhongguancun Ave"`.                            |
-| `subThoroughfare`       | `string`       | Additional street-level info, such as building number `"123"` or unit info.                  |
-| `locality`              | `string`       | The city or town name.                                                                       |
-| `subLocality`           | `string`       | A sub-area of the city or town, such as a neighborhood or district.                          |
-| `administrativeArea`    | `string`       | The state, province, or similar administrative region.                                       |
-| `subAdministrativeArea` | `string`       | A further subdivision within the administrative area, such as a county or district.          |
-| `postalCode`            | `string`       | The postal or ZIP code.                                                                      |
-| `isoCountryCode`        | `string`       | The ISO 3166-1 alpha-2 country code (e.g., `"US"`, `"CN"`).                                  |
-| `country`               | `string`       | The full name of the country or region.                                                      |
-| `inlandWater`           | `string`       | The name of a nearby inland body of water (lake, river), if applicable.                      |
-| `ocean`                 | `string`       | The name of a nearby ocean, if applicable.                                                   |
-| `areasOfInterest`       | `string[]`     | An array of nearby points of interest or landmarks (e.g., `"Times Square"`).                 |
+#### Field Descriptions
+
+| Field                   | Type           | Description                                                                     |
+| ----------------------- | -------------- | ------------------------------------------------------------------------------- |
+| `location`              | `LocationInfo` | The coordinates of the placemark (typically the same as reverse geocode input). |
+| `region`                | `string`       | General region or province/state.                                               |
+| `timeZone`              | `string`       | Time zone identifier (e.g., `"Asia/Shanghai"`).                                 |
+| `name`                  | `string`       | Generic name such as building, landmark, or area.                               |
+| `thoroughfare`          | `string`       | Street name (e.g., `"Main St"`, `"Zhongguancun Ave"`).                          |
+| `subThoroughfare`       | `string`       | Street-level detail like building number or unit.                               |
+| `locality`              | `string`       | City or town.                                                                   |
+| `subLocality`           | `string`       | Subdivision of the locality (e.g., neighborhood or district).                   |
+| `administrativeArea`    | `string`       | Province, state, or equivalent administrative area.                             |
+| `subAdministrativeArea` | `string`       | Further subdivision like county or district.                                    |
+| `postalCode`            | `string`       | ZIP or postal code.                                                             |
+| `isoCountryCode`        | `string`       | ISO 3166-1 alpha-2 country code (e.g., `"US"`, `"CN"`).                         |
+| `country`               | `string`       | Full name of the country or region.                                             |
+| `inlandWater`           | `string`       | Name of nearby inland water (river/lake), if applicable.                        |
+| `ocean`                 | `string`       | Name of nearby ocean, if applicable.                                            |
+| `areasOfInterest`       | `string[]`     | List of nearby points of interest or landmarks (e.g., `"Times Square"`).        |
 
 ---
 
-#### Example Usage
+## Example Usage
+
+### Reverse Geocode
 
 ```ts
 const placemarks = await Location.reverseGeocode({
@@ -206,9 +227,7 @@ if (placemarks?.length) {
 
 ---
 
-#### Suggested Address Formatter
-
-You can use the following function to construct a compact, readable address string:
+### Address Formatter (Helper)
 
 ```ts
 function formatAddress(p: LocationPlacemark): string {
@@ -225,18 +244,20 @@ function formatAddress(p: LocationPlacemark): string {
 
 ---
 
-#### Practical Use Cases
+## Best Practices & Use Cases
 
-* Use `areasOfInterest` and `name` to display user-friendly labels (e.g., “Empire State Building”).
-* Use `postalCode`, `locality`, and `administrativeArea` for auto-filling forms or location tagging.
-* Use `timeZone` for generating time-sensitive notifications or scheduling events in the user’s local time.
-* Combine `thoroughfare` and `subThoroughfare` for a complete street address.
+* Use `areasOfInterest` and `name` to display user-friendly place names.
+* Use `postalCode`, `locality`, and `administrativeArea` for autofill and geotagging.
+* Use `timestamp` to determine freshness of location data.
+* Use `timeZone` for localizing time-based features.
+* Set location accuracy before calling `requestCurrent` for optimal precision.
+* Always check widget permissions via `isAuthorizedForWidgetUpdates()`.
 
 ---
 
 ## Notes
 
-* Reverse geocoding may return multiple placemarks; typically, the first one is the most relevant.
-* `null` is returned if the location or geocoding fails.
-* You should call `setAccuracy` before `requestCurrent` to control precision based on your use case.
-* When used in widgets, permissions may be limited; use `isAuthorizedForWidgetUpdates` to verify access.
+* Reverse geocoding may return multiple results. Use the first placemark for best relevance.
+* If location retrieval fails, `null` is returned.
+* When `forceRequest` is false or omitted, cached location may be used for faster results.
+* In widgets, location access may be restricted. Always verify permissions explicitly.