首页 / Cesium / API 文档

Resource

先看结论

统一的资源描述对象。URL、查询参数、请求头、模板变量都挂在它上面，再交给各数据源或静态请求方法使用。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-29 · 引用本文

new Cesium.Resource(options)

构造参数

参数	说明
`url`	必填，字符串或另一个 `Resource`。传字符串时其余字段按默认处理
`queryParameters`	追加到查询串的对象，同名键会覆盖原有值
`templateValues`	替换 URL 里的 `{key}` 占位符
`headers`	请求头键值对，常用于携带令牌
`proxy`	代理对象，需实现 `getURLResource`
`request`	自定义 `Request`，控制优先级、重试与超时
`retryCallback`	失败重试前的回调，返回 true 才重试
`retryAttempts`	重试次数

属性与方法

成员	说明
`url`	基础 URL，可直接改写
`queryParameters`	查询参数对象
`templateValues`	模板变量对象
`headers`	请求头对象
`getDerivedResource(options)`	派生新资源，继承当前配置并叠加传入项
`getUrlComponent(query, proxy)`	拼出最终 URL；两个参数都是布尔开关
`setQueryParameters(params)`	整体替换查询参数
`appendQueryParameters(params)`	合并查询参数
`setTemplateValues(values)`	整体替换模板变量
`clone(result)`	复制一份

静态请求方法

方法	返回
`Resource.fetchJson(options)`	Promise<Object>
`Resource.fetchText(options)`	Promise<String>
`Resource.fetchArrayBuffer(options)`	Promise<ArrayBuffer>
`Resource.fetchBlob(options)`	Promise<Blob>
`Resource.fetchImage(options)`	Promise<ImageBitmap> 或 HTMLImageElement
`Resource.fetch(options)`	Promise<Object>，返回 `data` 与 `headers`

这些方法的 options 既可以是 URL 字符串，也可以是 { url, headers, queryParameters } 形式的对象。

带鉴权的请求

var resource = new Cesium.Resource({
  url: 'https://api.example.com/tiles/{z}/{x}/{y}.json',
  headers: {
    Authorization: 'Bearer ' + token
  },
  queryParameters: {
    key: 'demo'
  },
  templateValues: {
    token: 'abc'
  }
});

Cesium.Resource.fetchJson(resource).then(function (json) {
  console.log(json.tilejson);
}).catch(function (error) {
  console.error('请求失败', error);
});

// 派生资源，只改查询参数，其余配置沿用
var next = resource.getDerivedResource({
  queryParameters: { page: 2 }
});
console.log(next.getUrlComponent(true, false));

模板变量与查询参数的区别

templateValues 替换的是路径里的 {z}、{x} 这类占位符，替换结果进入路径；queryParameters 拼在 ? 之后。影像服务的 {z}/{x}/{y} 用前者，密钥、版本号这类附加项用后者。

跨域要服务端配合。带上自定义 headers 会触发预检请求，服务端必须返回对应的 Access-Control-Allow-Headers。图片类资源还要设置 crossOrigin，否则纹理上传会因画布污染失败。

引用本文

经纬志（2026）。《Resource》。https://www.jingweizhi.com/cesium/api/resource.html（访问日期 2026-11-03）。