@realsee/five
Version:
Realsee Renderer SDK
79 lines (73 loc) • 20 kB
HTML
<html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/request-proxy | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/request-proxy</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="request-proxy-请求代理" class="tsd-anchor-link">Request Proxy (请求代理)<a href="#request-proxy-请求代理" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
<ul>
<li><strong>Summary</strong>: <code>requestProxy</code> 是 Five 初始化时的关键参数，用于在发起网络请求前对 URL 进行拦截和修改，常用于鉴权、资源重定向或 CDN 域名替换。</li>
<li><strong>Schema</strong>: <code>(url: string) => string | Promise<string></code></li>
<li><strong>Concepts</strong>: 请求拦截、资源重定向、鉴权签名。</li>
<li><strong>Configuration</strong>: <code>FiveInitArgs.requestProxy</code>。</li>
<li><strong>Examples</strong>: CDN 替换、私有化部署鉴权、调试模式。</li>
</ul>
<h2 id="schema" class="tsd-anchor-link">Schema<a href="#schema" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<blockquote>
<p><strong>Definition</strong>: <a href="../../five/application/fiveInitArgs.d.ts">FiveInitArgs</a></p>
</blockquote>
<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/**</span><br/><span class="hl-8"> * 请求代理函数</span><br/><span class="hl-8"> * </span><span class="hl-3">@description</span><span class="hl-8"> 在 Five 内部发起任何网络请求（如加载图片、模型、配置）之前调用。</span><br/><span class="hl-8"> * </span><span class="hl-3">@param</span><span class="hl-8"> </span><span class="hl-6">url</span><span class="hl-8"> - 原始请求 URL</span><br/><span class="hl-8"> * </span><span class="hl-3">@returns</span><span class="hl-8"> 修改后的 URL (string) 或异步返回修改后的 URL (Promise<string>)</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-5">requestProxy</span><span class="hl-1">?: (</span><span class="hl-6">url</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">) </span><span class="hl-3">=></span><span class="hl-1"> </span><span class="hl-7">string</span><span class="hl-1"> | </span><span class="hl-7">Promise</span><span class="hl-1"><</span><span class="hl-7">string</span><span class="hl-1">>;</span><br/><span class="hl-1">}</span>
</code><button type="button">Copy</button></pre>
<h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="拦截时机" class="tsd-anchor-link">拦截时机<a href="#拦截时机" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>Five 内部加载资源（全景图瓦片、3D 模型、纹理贴图等）时，会通过统一的 Fetcher 层发起请求。<code>requestProxy</code> 钩子函数会在每次请求发起<strong>前</strong>被触发。</p>
<h3 id="核心用途" class="tsd-anchor-link">核心用途<a href="#核心用途" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<ol>
<li><strong>域名替换 (CDN Domain Sharding)</strong>: 将资源请求分散到多个 CDN 域名以突破浏览器并发限制。</li>
<li><strong>鉴权签名 (Authentication)</strong>: 针对私有化部署或受保护资源，在 URL 后追加鉴权 Token (如 SAS Token)。</li>
<li><strong>资源重定向 (Redirection)</strong>: 在开发环境下将线上资源重定向到本地或测试环境。</li>
<li><strong>协议适配</strong>: 强制将 <code>http</code> 协议升级为 <code>https</code>。</li>
</ol>
<h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p><code>requestProxy</code> 是 <code>Five</code> 构造函数的配置项之一。</p>
<table>
<thead>
<tr>
<th style="text-align:left">参数</th>
<th style="text-align:left">类型</th>
<th style="text-align:left">默认值</th>
<th style="text-align:left">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>requestProxy</code></td>
<td style="text-align:left"><code>(url: string) => string | Promise<string></code></td>
<td style="text-align:left"><code>undefined</code></td>
<td style="text-align:left">代理函数，返回修改后的 URL。支持同步或异步返回。</td>
</tr>
</tbody>
</table>
<h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="1-基础用法：cdn-域名替换" class="tsd-anchor-link">1. 基础用法：CDN 域名替换<a href="#1-基础用法：cdn-域名替换" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>将图片资源请求分散到不同的 CDN 节点，加速加载。</p>
<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">requestProxy</span><span class="hl-6">:</span><span class="hl-1"> (</span><span class="hl-6">url</span><span class="hl-1">) </span><span class="hl-3">=></span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 简单的字符串替换示例</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">url</span><span class="hl-1">.</span><span class="hl-5">replace</span><span class="hl-1">(</span><span class="hl-9">'//vrlab-public.ljcdn.com/'</span><span class="hl-1">, </span><span class="hl-9">'//vr-public.realsee-cdn.cn/'</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>
<h3 id="2-进阶用法：异步鉴权-async-auth" class="tsd-anchor-link">2. 进阶用法：异步鉴权 (Async Auth)<a href="#2-进阶用法：异步鉴权-async-auth" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>对于需要动态获取 Token 的场景，可以使用 <code>Promise</code> 异步返回 URL。</p>
<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">requestProxy</span><span class="hl-6">:</span><span class="hl-1"> </span><span class="hl-3">async</span><span class="hl-1"> (</span><span class="hl-6">url</span><span class="hl-1">) </span><span class="hl-3">=></span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 仅对私有桶资源进行签名</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">url</span><span class="hl-1">.</span><span class="hl-5">includes</span><span class="hl-1">(</span><span class="hl-9">'private-bucket'</span><span class="hl-1">)) {</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">token</span><span class="hl-1"> = </span><span class="hl-10">await</span><span class="hl-1"> </span><span class="hl-5">fetchToken</span><span class="hl-1">(); </span><span class="hl-8">// 假设 fetchToken 是一个获取鉴权的异步函数</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">separator</span><span class="hl-1"> = </span><span class="hl-6">url</span><span class="hl-1">.</span><span class="hl-5">includes</span><span class="hl-1">(</span><span class="hl-9">'?'</span><span class="hl-1">) ? </span><span class="hl-9">'&'</span><span class="hl-1"> : </span><span class="hl-9">'?'</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">url</span><span class="hl-3">}${</span><span class="hl-6">separator</span><span class="hl-3">}</span><span class="hl-9">token=</span><span class="hl-3">${</span><span class="hl-6">token</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">url</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>
<h3 id="3-开发调试：本地资源代理" class="tsd-anchor-link">3. 开发调试：本地资源代理<a href="#3-开发调试：本地资源代理" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>在开发阶段，将特定资源重定向到本地文件。</p>
<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">proxyMap</span><span class="hl-1">: </span><span class="hl-7">Record</span><span class="hl-1"><</span><span class="hl-7">string</span><span class="hl-1">, </span><span class="hl-7">string</span><span class="hl-1">> = {};</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">requestProxy</span><span class="hl-6">:</span><span class="hl-1"> (</span><span class="hl-6">url</span><span class="hl-1">) </span><span class="hl-3">=></span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 如果该 URL 在映射表中存在（例如通过 <input type="file"> 加载的本地 Blob URL），则使用映射值</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">proxyMap</span><span class="hl-1">[</span><span class="hl-6">url</span><span class="hl-1">]) {</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`[Proxy] Redirecting </span><span class="hl-3">${</span><span class="hl-6">url</span><span class="hl-3">}</span><span class="hl-9"> -> </span><span class="hl-3">${</span><span class="hl-6">proxyMap</span><span class="hl-12">[</span><span class="hl-6">url</span><span class="hl-12">]</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">proxyMap</span><span class="hl-1">[</span><span class="hl-6">url</span><span class="hl-1">];</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">url</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>
<h2 id="common-pitfalls" class="tsd-anchor-link">Common Pitfalls<a href="#common-pitfalls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ol>
<li><strong>死循环风险</strong>: 不要在 <code>requestProxy</code> 内部再次发起会导致 <code>requestProxy</code> 触发的 Five 资源请求，否则可能导致递归调用。</li>
<li><strong>性能损耗</strong>: <code>requestProxy</code> 会在<strong>所有</strong>资源请求前触发（包括成百上千个瓦片请求）。请确保该函数执行效率极高，避免进行耗时的同步操作。如果是异步操作，应做好缓存。</li>
<li><strong>URL 格式</strong>: 确保返回的 URL 格式正确。如果原 URL 包含 Query 参数，拼接 Token 时要注意判断是使用 <code>?</code> 还是 <code>&</code>。</li>
<li><strong>缓存一致性</strong>: 如果修改了 URL（例如加了 Token），可能会影响浏览器的缓存命中策略。</li>
</ol>
<h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li><a href="features_parameter.html">Parameter</a>: Five 初始化参数总览。</li>
<li><a href="features_load-external-model.html">Load External Model</a>: 加载外部模型时也会触发 requestProxy。</li>
</ul>
<hr>
<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">请求代理</span><span class="hl-1">, </span><span class="hl-2">鉴权</span><span class="hl-1">, </span><span class="hl-2">域名替换</span><span class="hl-1">, </span><span class="hl-2">私有化</span><span class="hl-1">, </span><span class="hl-2">请求拦截</span><span class="hl-1">, </span><span class="hl-2">configuration</span><span class="hl-1">, </span><span class="hl-2">network</span><span class="hl-1">, </span><span class="hl-2">proxy</span><span class="hl-1">, </span><span class="hl-2">authentication</span><span class="hl-1">, </span><span class="hl-2">CDN</span><span class="hl-1">, </span><span class="hl-2">token</span><span class="hl-1">, </span><span class="hl-2">url-rewrite</span><span class="hl-1">, </span><span class="hl-2">cors</span><span class="hl-1">]</span>
</code><button type="button">Copy</button></pre>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#request-proxy-请求代理"><span>Request <wbr/>Proxy (请求代理)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#拦截时机"><span>拦截时机</span></a></li><li><a href="#核心用途"><span>核心用途</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-基础用法：cdn-域名替换"><span>1. 基础用法：<wbr/>CDN 域名替换</span></a></li><li><a href="#2-进阶用法：异步鉴权-async-auth"><span>2. 进阶用法：异步鉴权 (<wbr/>Async <wbr/>Auth)</span></a></li><li><a href="#3-开发调试：本地资源代理"><span>3. 开发调试：本地资源代理</span></a></li></ul></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</span></a></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>