Image

项目内的图片

从项目中导入图片文件。导入值是构建产物的 file:// 地址，需要用 URL 包装后传入：

import { Image, Modifier } from "onescript/views"
import sunset from "./assets/sunset.png"

<Image
  url={new URL(sunset)}
  resizable
  modifier={Modifier
    .scaledToFill()
    .frame({ height: 160 })
    .clipped()}
/>

项目内的图片在 App 和 Widget 中都可以显示，支持 PNG、JPEG、GIF 和 WebP；SVG 文件会被打包，但 Image 无法显示。可以显示任意本地 file:// 文件（包括分享给 Action 的文件），文件不存在或无法解码时会明确报错。同一个地址也可用于 fs，例如 await fs.promises.readFile(new URL(sunset))。

URL

公开 HTTP(S) 图片使用标准的 Node 兼容 URL 对象：

import { Image, Modifier } from "onescript/views"

const publicImageURL = new URL("https://example.com/public.png")

<Image
  url={publicImageURL}
  resizable
  modifier={Modifier
    .scaledToFit()
    .frame({ width: 120, height: 120 })}
/>

Request

图片需要 Cookie、Authorization 或其他请求头时，使用标准 Fetch API Request：

import { Image } from "onescript/views"

const privateImageRequest = new Request(
  "https://example.com/private.png",
  {
    method: "GET", // 省略时默认为 GET
    headers: {
      Cookie: `session=${sessionId}`,
      Authorization: `Bearer ${token}`,
    },
  },
)

<Image
  request={privateImageRequest}
  resizable
/>

请求接口通过 Body 返回图片时，可以传入其他 HTTP Method：

const generatedImageRequest = new Request(
  "https://example.com/images/render",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      width: 800,
      height: 600,
    }),
  },
)

<Image request={generatedImageRequest} />

Prop	Type	说明
`dataURL`	`string`	图片 Data URL，与 `url`、`request` 互斥。
`url`	`URL`	导入的 `file://` 图片或公开的 HTTP(S) 图片地址，与 `dataURL`、`request` 互斥。
`request`	`Request`	HTTP(S) 请求，与 `dataURL`、`url` 互斥。
`scale`	`number`	`url` 与 `request` 图片的正数缩放比例，默认 `1`。
`resizable`	`boolean`	允许图片调整尺寸。

dataURL、url 和 request 必须且只能提供一个。图片缩放使用有序的 scaledToFit 和 scaledToFill 修饰符。

网络图片在加载时显示系统进度指示器，失败后显示本地化错误文本。失败信息也会写入原生日志，请求头值不会进入日志。

OneScript 会传递 Request 的 URL、Method、请求头、Body、缓存策略和重定向策略。Request.credentials 与脚本 WKWebView、App 的 Cookie 存储保持隔离；身份认证需要 Cookie 时，通过 Request.headers 显式传入。同源重定向保留请求头，跨源重定向会移除 Authorization、Cookie 和 Proxy-Authorization。

App 视图在 iOS 17–26 使用 OneScript 兼容加载器，在 iOS 27 及以上使用 SwiftUI 原生异步图片加载器。Widget 会在创建时间线条目前下载并验证图片，请求失败会通过明确错误终止 Widget 执行。

SF Symbols 和 Pikaicons 使用 Symbol。图片数据或来源无效时会抛出明确错误。

项目内的图片

Data URL

URL

Request

本页目录