@ray-js/robot-map-sdk 0.0.15-beta.5 → 0.0.15-beta.7

package/dist-docs/assets/chunks/{webworkerAll.S3LCCO8A.js → webworkerAll.CJ-vfJb5.js}

@@ -1,4 +1,4 @@
-import{ac as S,ae as I,af as B,aI as O,p as F,M as w,a4 as A,a0 as E,ak as m,T as y,aA as U,X as C,w as M,aj as Y,x as P}from"./index.CgkVFHcL.js";import"./framework.CBLqO2Q1.js";import"./mapValues.D2X8cRgC.js";import"./theme.DeJ2cHsN.js";var X=`in vec2 vTextureCoord;
+import{ac as S,ae as I,af as B,aI as O,p as F,M as w,a4 as A,a0 as E,ak as m,T as y,aA as U,X as C,w as M,aj as Y,x as P}from"./index.63u6ixbT.js";import"./framework.CBLqO2Q1.js";import"./mapValues.D2X8cRgC.js";import"./theme.CnUzYoyt.js";var X=`in vec2 vTextureCoord;
 out vec4 finalColor;
 uniform sampler2D uTexture;
 void main() {

package/dist-docs/assets/{guide_advanced-usage.md.Cpp8XDrz.js → guide_advanced-usage.md.JAqVYRlM.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,aq as h}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"进阶使用","description":"","frontmatter":{},"headers":[],"relativePath":"guide/advanced-usage.md","filePath":"guide/advanced-usage.md","lastUpdated":1778638153000}'),l={name:"guide/advanced-usage.md"};function p(k,s,t,e,E,r){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="进阶使用" tabindex="-1">进阶使用 <a class="header-anchor" href="#进阶使用" aria-label="Permalink to &quot;进阶使用&quot;">​</a></h1><p>Tuya Robot Map 的进阶使用，包含了我们认为的最佳实践。</p><h2 id="自适应缩放" tabindex="-1">自适应缩放 <a class="header-anchor" href="#自适应缩放" aria-label="Permalink to &quot;自适应缩放&quot;">​</a></h2><p>自适应缩放是地图 SDK 的核心功能之一，它会自动调整地图的缩放比例和位置，确保地图能够以合适的大小居中显示在视口中。</p><h3 id="什么是-scale" tabindex="-1">什么是 scale？ <a class="header-anchor" href="#什么是-scale" aria-label="Permalink to &quot;什么是 scale？&quot;">​</a></h3><p><code>scale</code> 表示地图的缩放比例。<strong><code>scale = 1</code> 表示地图按照真实像素尺寸显示</strong>。</p><p>例如，如果你的地图数据是 300×300 的尺寸：</p><ul><li><code>scale = 1</code> 时，地图会用 300×300 像素显示</li><li><code>scale = 2</code> 时，地图会放大到 600×600 像素</li><li><code>scale = 0.5</code> 时，地图会缩小到 150×150 像素</li></ul><h3 id="自适应缩放的触发时机" tabindex="-1">自适应缩放的触发时机 <a class="header-anchor" href="#自适应缩放的触发时机" aria-label="Permalink to &quot;自适应缩放的触发时机&quot;">​</a></h3><p>自适应缩放会在以下情况自动触发：</p><ol><li><strong>地图首次绘制</strong>：当地图第一次加载时</li><li><strong>地图 ID 变化</strong>：切换到不同的地图时</li><li><strong>地图状态变化</strong>：地图的 <code>status</code> 字段变化时（例如从建图中变为建图完成）</li><li><strong>地图原点变化</strong>：地图的 <code>origin</code> 坐标变化超过阈值时</li><li><strong>地图尺寸变化</strong>：地图的 <code>size</code> (宽度或高度) 变化超过阈值时</li><li><strong>地图旋转</strong>：通过 <code>runtime.mapRotation</code> 旋转地图后</li></ol><h3 id="自适应缩放的计算逻辑" tabindex="-1">自适应缩放的计算逻辑 <a class="header-anchor" href="#自适应缩放的计算逻辑" aria-label="Permalink to &quot;自适应缩放的计算逻辑&quot;">​</a></h3><p>当触发自适应缩放时，SDK 会按照以下步骤计算最终的缩放比例：</p><h4 id="_1-计算初始缩放比例" tabindex="-1">1. 计算初始缩放比例 <a class="header-anchor" href="#_1-计算初始缩放比例" aria-label="Permalink to &quot;1. 计算初始缩放比例&quot;">​</a></h4><p>SDK 会根据 <a href="/reference/config.html#map-autopaddinghorizontalpercent"><code>map.autoPaddingHorizontalPercent</code></a> 和 <a href="/reference/config.html#map-autopaddingverticalpercent"><code>map.autoPaddingVerticalPercent</code></a> 计算出一个初始的缩放比例，确保地图能够完整显示并保留指定的边距。</p><p>例如，如果视口宽度是 375px，<code>autoPaddingHorizontalPercent</code> 是 0.05（默认值），那么：</p><ul><li>水平方向的可用空间 = 375 × (1 - 0.05 × 2) = 337.5px</li><li>如果地图实际宽度是 300px，则计算出的 scale = 337.5 / 300 ≈ 1.125</li><li>如果地图实际宽度是 600px，则计算出的 scale = 337.5 / 600 ≈ 0.5625</li></ul><h4 id="_2-应用缩放比例限制" tabindex="-1">2. 应用缩放比例限制 <a class="header-anchor" href="#_2-应用缩放比例限制" aria-label="Permalink to &quot;2. 应用缩放比例限制&quot;">​</a></h4><p>计算出的初始缩放比例会受到 <a href="/reference/config.html#interaction-fitminscale"><code>interaction.fitMinScale</code></a> 和 <a href="/reference/config.html#interaction-fitmaxscale"><code>interaction.fitMaxScale</code></a> 的限制：</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>最终 scale = Math.max(fitMinScale, Math.min(初始 scale, fitMaxScale))</span></span></code></pre></div><h3 id="常见问题与解决方案" tabindex="-1">常见问题与解决方案 <a class="header-anchor" href="#常见问题与解决方案" aria-label="Permalink to &quot;常见问题与解决方案&quot;">​</a></h3><h4 id="问题-1-超大地图显示不全" tabindex="-1">问题 1：超大地图显示不全 <a class="header-anchor" href="#问题-1-超大地图显示不全" aria-label="Permalink to &quot;问题 1：超大地图显示不全&quot;">​</a></h4><p><strong>现象</strong>：地图很大，但只能看到部分内容，无法看到完整地图。</p><p><strong>原因</strong>：当地图尺寸超过视口时，SDK 计算出的缩放比例可能小于 1（需要缩小地图）。但是 <code>fitMinScale</code> 的默认值是 1，会限制地图不能缩小到小于原始尺寸，导致地图无法完整显示。</p><p><strong>解决方案</strong>：将 <code>fitMinScale</code> 设置为小于 1 的值，允许地图缩小。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RobotMap</span></span>
+import{_ as i,c as a,o as n,aq as h}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"进阶使用","description":"","frontmatter":{},"headers":[],"relativePath":"guide/advanced-usage.md","filePath":"guide/advanced-usage.md","lastUpdated":1778673065000}'),l={name:"guide/advanced-usage.md"};function p(k,s,t,e,E,r){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="进阶使用" tabindex="-1">进阶使用 <a class="header-anchor" href="#进阶使用" aria-label="Permalink to &quot;进阶使用&quot;">​</a></h1><p>Tuya Robot Map 的进阶使用，包含了我们认为的最佳实践。</p><h2 id="自适应缩放" tabindex="-1">自适应缩放 <a class="header-anchor" href="#自适应缩放" aria-label="Permalink to &quot;自适应缩放&quot;">​</a></h2><p>自适应缩放是地图 SDK 的核心功能之一，它会自动调整地图的缩放比例和位置，确保地图能够以合适的大小居中显示在视口中。</p><h3 id="什么是-scale" tabindex="-1">什么是 scale？ <a class="header-anchor" href="#什么是-scale" aria-label="Permalink to &quot;什么是 scale？&quot;">​</a></h3><p><code>scale</code> 表示地图的缩放比例。<strong><code>scale = 1</code> 表示地图按照真实像素尺寸显示</strong>。</p><p>例如，如果你的地图数据是 300×300 的尺寸：</p><ul><li><code>scale = 1</code> 时，地图会用 300×300 像素显示</li><li><code>scale = 2</code> 时，地图会放大到 600×600 像素</li><li><code>scale = 0.5</code> 时，地图会缩小到 150×150 像素</li></ul><h3 id="自适应缩放的触发时机" tabindex="-1">自适应缩放的触发时机 <a class="header-anchor" href="#自适应缩放的触发时机" aria-label="Permalink to &quot;自适应缩放的触发时机&quot;">​</a></h3><p>自适应缩放会在以下情况自动触发：</p><ol><li><strong>地图首次绘制</strong>：当地图第一次加载时</li><li><strong>地图 ID 变化</strong>：切换到不同的地图时</li><li><strong>地图状态变化</strong>：地图的 <code>status</code> 字段变化时（例如从建图中变为建图完成）</li><li><strong>地图原点变化</strong>：地图的 <code>origin</code> 坐标变化超过阈值时</li><li><strong>地图尺寸变化</strong>：地图的 <code>size</code> (宽度或高度) 变化超过阈值时</li><li><strong>地图旋转</strong>：通过 <code>runtime.mapRotation</code> 旋转地图后</li></ol><h3 id="自适应缩放的计算逻辑" tabindex="-1">自适应缩放的计算逻辑 <a class="header-anchor" href="#自适应缩放的计算逻辑" aria-label="Permalink to &quot;自适应缩放的计算逻辑&quot;">​</a></h3><p>当触发自适应缩放时，SDK 会按照以下步骤计算最终的缩放比例：</p><h4 id="_1-计算初始缩放比例" tabindex="-1">1. 计算初始缩放比例 <a class="header-anchor" href="#_1-计算初始缩放比例" aria-label="Permalink to &quot;1. 计算初始缩放比例&quot;">​</a></h4><p>SDK 会根据 <a href="/reference/config.html#map-autopaddinghorizontalpercent"><code>map.autoPaddingHorizontalPercent</code></a> 和 <a href="/reference/config.html#map-autopaddingverticalpercent"><code>map.autoPaddingVerticalPercent</code></a> 计算出一个初始的缩放比例，确保地图能够完整显示并保留指定的边距。</p><p>例如，如果视口宽度是 375px，<code>autoPaddingHorizontalPercent</code> 是 0.05（默认值），那么：</p><ul><li>水平方向的可用空间 = 375 × (1 - 0.05 × 2) = 337.5px</li><li>如果地图实际宽度是 300px，则计算出的 scale = 337.5 / 300 ≈ 1.125</li><li>如果地图实际宽度是 600px，则计算出的 scale = 337.5 / 600 ≈ 0.5625</li></ul><h4 id="_2-应用缩放比例限制" tabindex="-1">2. 应用缩放比例限制 <a class="header-anchor" href="#_2-应用缩放比例限制" aria-label="Permalink to &quot;2. 应用缩放比例限制&quot;">​</a></h4><p>计算出的初始缩放比例会受到 <a href="/reference/config.html#interaction-fitminscale"><code>interaction.fitMinScale</code></a> 和 <a href="/reference/config.html#interaction-fitmaxscale"><code>interaction.fitMaxScale</code></a> 的限制：</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>最终 scale = Math.max(fitMinScale, Math.min(初始 scale, fitMaxScale))</span></span></code></pre></div><h3 id="常见问题与解决方案" tabindex="-1">常见问题与解决方案 <a class="header-anchor" href="#常见问题与解决方案" aria-label="Permalink to &quot;常见问题与解决方案&quot;">​</a></h3><h4 id="问题-1-超大地图显示不全" tabindex="-1">问题 1：超大地图显示不全 <a class="header-anchor" href="#问题-1-超大地图显示不全" aria-label="Permalink to &quot;问题 1：超大地图显示不全&quot;">​</a></h4><p><strong>现象</strong>：地图很大，但只能看到部分内容，无法看到完整地图。</p><p><strong>原因</strong>：当地图尺寸超过视口时，SDK 计算出的缩放比例可能小于 1（需要缩小地图）。但是 <code>fitMinScale</code> 的默认值是 1，会限制地图不能缩小到小于原始尺寸，导致地图无法完整显示。</p><p><strong>解决方案</strong>：将 <code>fitMinScale</code> 设置为小于 1 的值，允许地图缩小。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RobotMap</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{{</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    interaction: {</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      // 允许地图缩小到原始尺寸的 50%</span></span>
@@ -933,7 +933,23 @@ import{_ as i,c as a,o as n,aq as h}from"./chunks/framework.CBLqO2Q1.js";const g
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      // ... 其他属性</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    /&gt;</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  )</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="编辑地毯" tabindex="-1">编辑地毯 <a class="header-anchor" href="#编辑地毯" aria-label="Permalink to &quot;编辑地毯&quot;">​</a></h3><p>通过 <code>runtime.editingCarpetIds</code> 控制哪些地毯处于编辑状态。编辑模式下，地毯会显示删除、旋转和缩放控制按钮，用户可以通过手势进行拖拽移动。<code>controls.carpet.rotateMode</code> 用于切换点击旋转 90 度和按住拖动连续旋转；<code>controls.carpet.scaleMode</code> 用于切换自由缩放和等比缩放。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> MapPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="在视口中心创建地毯" tabindex="-1">在视口中心创建地毯 <a class="header-anchor" href="#在视口中心创建地毯" aria-label="Permalink to &quot;在视口中心创建地毯&quot;">​</a></h3><p>你可以通过 <code>getCustomCarpetPointsByViewportCenter()</code> 生成一组四点坐标， 再由业务层自己补 <code>id</code>、<code>type</code> 和 <code>shape</code>。同一组 <code>points</code> 既可以用于 矩形地毯，也可以用于圆形或椭圆形地毯。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> handleAddCarpet</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">shape</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;rectangle&#39;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;round&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> points</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mapApi.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getCustomCarpetPointsByViewportCenter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    width: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    height: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1.2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    offsetX: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  })</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  setCustomCarpets</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">((</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">prev</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    ...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prev,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`carpet-\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">length</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> +</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      type: selectedMaterialType,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      shape,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      points,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ])</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p><code>shape: &#39;custom&#39;</code> 仍然需要业务层自行提供多边形顶点，这个 helper 不会 生成自定义轮廓。</p><h3 id="编辑地毯" tabindex="-1">编辑地毯 <a class="header-anchor" href="#编辑地毯" aria-label="Permalink to &quot;编辑地毯&quot;">​</a></h3><p>通过 <code>runtime.editingCarpetIds</code> 控制哪些地毯处于编辑状态。编辑模式下，地毯会显示删除、旋转和缩放控制按钮，用户可以通过手势进行拖拽移动。<code>controls.carpet.rotateMode</code> 用于切换点击旋转 90 度和按住拖动连续旋转；<code>controls.carpet.scaleMode</code> 用于切换自由缩放和等比缩放。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> MapPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">customCarpets</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">setCustomCarpets</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> useState</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">CustomCarpetParam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]&gt;([</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // ...</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ])</span></span>
@@ -1135,4 +1151,4 @@ import{_ as i,c as a,o as n,aq as h}from"./chunks/framework.CBLqO2Q1.js";const g
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (mapApi) {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    mapApi.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">forceEndGesture</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">提示</p><p>地图 SDK 内部已针对双指缩放时的快速松手做了防抖缓冲处理，搭配上述方案可获得最佳手势体验。</p></div>`,238)])])}const y=i(l,[["render",p]]);export{g as __pageData,y as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">提示</p><p>地图 SDK 内部已针对双指缩放时的快速松手做了防抖缓冲处理，搭配上述方案可获得最佳手势体验。</p></div>`,242)])])}const y=i(l,[["render",p]]);export{g as __pageData,y as default};

package/dist-docs/assets/{guide_advanced-usage.md.Cpp8XDrz.lean.js → guide_advanced-usage.md.JAqVYRlM.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,aq as h}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"进阶使用","description":"","frontmatter":{},"headers":[],"relativePath":"guide/advanced-usage.md","filePath":"guide/advanced-usage.md","lastUpdated":1778638153000}'),l={name:"guide/advanced-usage.md"};function p(k,s,t,e,E,r){return n(),a("div",null,[...s[0]||(s[0]=[h("",238)])])}const y=i(l,[["render",p]]);export{g as __pageData,y as default};
+import{_ as i,c as a,o as n,aq as h}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"进阶使用","description":"","frontmatter":{},"headers":[],"relativePath":"guide/advanced-usage.md","filePath":"guide/advanced-usage.md","lastUpdated":1778673065000}'),l={name:"guide/advanced-usage.md"};function p(k,s,t,e,E,r){return n(),a("div",null,[...s[0]||(s[0]=[h("",242)])])}const y=i(l,[["render",p]]);export{g as __pageData,y as default};

package/dist-docs/assets/{guide_getting-started.md.s2PQDUaI.js → guide_getting-started.md.BZorxbvR.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,aq as h}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"快速开始","description":"","frontmatter":{},"headers":[],"relativePath":"guide/getting-started.md","filePath":"guide/getting-started.md","lastUpdated":1770804529000}'),p={name:"guide/getting-started.md"};function l(k,s,t,e,E,r){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="快速开始" tabindex="-1">快速开始 <a class="header-anchor" href="#快速开始" aria-label="Permalink to &quot;快速开始&quot;">​</a></h1><p>Tuya Robot Map 提供了开箱即用的 React 组件，专为扫地机器人应用设计。</p><h2 id="安装" tabindex="-1">安装 <a class="header-anchor" href="#安装" aria-label="Permalink to &quot;安装&quot;">​</a></h2><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-hQlne" id="tab-h_gBUmD" checked><label data-title="yarn" for="tab-h_gBUmD">yarn</label><input type="radio" name="group-hQlne" id="tab-1A0O03h"><label data-title="npm" for="tab-1A0O03h">npm</label></div><div class="blocks"><div class="language-bash vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">yarn</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @ray-js/robot-map</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @ray-js/robot-map</span></span></code></pre></div></div></div><h2 id="数据传入" tabindex="-1">数据传入 <a class="header-anchor" href="#数据传入" aria-label="Permalink to &quot;数据传入&quot;">​</a></h2><p>仅需传入几个基本的数据props，即可完成地图的呈现。</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-Z2L9_" id="tab-6sfiWTA" checked><label data-title="点阵协议地图数据" for="tab-6sfiWTA">点阵协议地图数据</label><input type="radio" name="group-Z2L9_" id="tab-KE8-VI5"><label data-title="结构化协议地图数据" for="tab-KE8-VI5">结构化协议地图数据</label></div><div class="blocks"><div class="language-tsx vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> React, { useMemo } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;react&#39;</span></span>
+import{_ as i,c as a,o as n,aq as h}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"快速开始","description":"","frontmatter":{},"headers":[],"relativePath":"guide/getting-started.md","filePath":"guide/getting-started.md","lastUpdated":1770804529000}'),p={name:"guide/getting-started.md"};function l(k,s,t,e,E,r){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="快速开始" tabindex="-1">快速开始 <a class="header-anchor" href="#快速开始" aria-label="Permalink to &quot;快速开始&quot;">​</a></h1><p>Tuya Robot Map 提供了开箱即用的 React 组件，专为扫地机器人应用设计。</p><h2 id="安装" tabindex="-1">安装 <a class="header-anchor" href="#安装" aria-label="Permalink to &quot;安装&quot;">​</a></h2><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-Lc_To" id="tab-H1hgh7c" checked><label data-title="yarn" for="tab-H1hgh7c">yarn</label><input type="radio" name="group-Lc_To" id="tab-usu0AhI"><label data-title="npm" for="tab-usu0AhI">npm</label></div><div class="blocks"><div class="language-bash vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">yarn</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @ray-js/robot-map</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @ray-js/robot-map</span></span></code></pre></div></div></div><h2 id="数据传入" tabindex="-1">数据传入 <a class="header-anchor" href="#数据传入" aria-label="Permalink to &quot;数据传入&quot;">​</a></h2><p>仅需传入几个基本的数据props，即可完成地图的呈现。</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-0H8rw" id="tab-Po_3kWN" checked><label data-title="点阵协议地图数据" for="tab-Po_3kWN">点阵协议地图数据</label><input type="radio" name="group-0H8rw" id="tab-jtpGpdU"><label data-title="结构化协议地图数据" for="tab-jtpGpdU">结构化协议地图数据</label></div><div class="blocks"><div class="language-tsx vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> React, { useMemo } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;react&#39;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { RobotMap } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;@ray-js/robot-map&#39;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { decodeRoomProperties } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;@ray-js/robot-map&#39;</span></span>
 <span class="line"></span>

package/dist-docs/assets/{reference_methods.md.BvtVJ2dG.js → reference_methods.md.CxMQMj53.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,aq as t}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"地图方法","description":"","frontmatter":{},"headers":[],"relativePath":"reference/methods.md","filePath":"reference/methods.md","lastUpdated":1773644264000}'),p={name:"reference/methods.md"};function e(h,s,l,k,r,d){return n(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="地图方法" tabindex="-1">地图方法 <a class="header-anchor" href="#地图方法" aria-label="Permalink to &quot;地图方法&quot;">​</a></h1><p>了解 RobotMap 提供的 API 方法。</p><h2 id="使用示例" tabindex="-1">使用示例 <a class="header-anchor" href="#使用示例" aria-label="Permalink to &quot;使用示例&quot;">​</a></h2><p>通过 <code>onMapReady</code> 回调获得 <code>MapApi</code> 实例，该实例包含所有可调用的地图方法。这些方法让你可以主动控制地图行为、查询数据和执行各种操作。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { MapApi } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;@ray-js/robot-map&#39;</span></span>
+import{_ as i,c as a,o as n,aq as t}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"地图方法","description":"","frontmatter":{},"headers":[],"relativePath":"reference/methods.md","filePath":"reference/methods.md","lastUpdated":1779070238000}'),e={name:"reference/methods.md"};function p(h,s,l,k,r,d){return n(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="地图方法" tabindex="-1">地图方法 <a class="header-anchor" href="#地图方法" aria-label="Permalink to &quot;地图方法&quot;">​</a></h1><p>了解 RobotMap 提供的 API 方法。</p><h2 id="使用示例" tabindex="-1">使用示例 <a class="header-anchor" href="#使用示例" aria-label="Permalink to &quot;使用示例&quot;">​</a></h2><p>通过 <code>onMapReady</code> 回调获得 <code>MapApi</code> 实例，该实例包含所有可调用的地图方法。这些方法让你可以主动控制地图行为、查询数据和执行各种操作。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { MapApi } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;@ray-js/robot-map&#39;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> MapPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() {</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> mapApi</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> useRef</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MapApi</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
@@ -62,7 +62,12 @@ import{_ as i,c as a,o as n,aq as t}from"./chunks/framework.CBLqO2Q1.js";const g
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  furnitureType</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  offsetX</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  offsetY</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Point</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]&gt;</span></span></code></pre></div><p><strong>参数</strong>:</p><ul><li><code>options</code> - 配置选项</li><li><code>options.furnitureType</code>: <code>number</code> - 家具类型编号，匹配 <code>config.furniture.assets</code> 中的 <code>type</code>。默认使用第一个素材的类型</li><li><code>options.offsetX</code>: <code>number</code> - X方向像素偏移，支持负数，默认为 0</li><li><code>options.offsetY</code>: <code>number</code> - Y方向像素偏移，支持负数，默认为 0</li></ul><p><strong>返回值</strong>: <a href="/reference/types.html#point"><code>Promise&lt;Point[]&gt;</code></a></p><h2 id="getfurnitures" tabindex="-1">getFurnitures() <a class="header-anchor" href="#getfurnitures" aria-label="Permalink to &quot;getFurnitures()&quot;">​</a></h2><p>获取当前地图上所有家具数据。</p><p><strong>类型</strong>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> getFurnitures</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">FurnitureParam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]&gt;</span></span></code></pre></div><p><strong>返回值</strong>: <a href="/reference/types.html#furnitureparam"><code>Promise&lt;FurnitureParam[]&gt;</code></a></p><h2 id="getspotpointbyviewportcenter" tabindex="-1">getSpotPointByViewportCenter() <a class="header-anchor" href="#getspotpointbyviewportcenter" aria-label="Permalink to &quot;getSpotPointByViewportCenter()&quot;">​</a></h2><p>基于视口中心生成定点清扫的点坐标。</p><p><strong>类型</strong>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> getSpotPointByViewportCenter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">options</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Point</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]&gt;</span></span></code></pre></div><p><strong>参数</strong>:</p><ul><li><code>options</code> - 配置选项</li><li><code>options.furnitureType</code>: <code>number</code> - 家具类型编号，匹配 <code>config.furniture.assets</code> 中的 <code>type</code>。默认使用第一个素材的类型</li><li><code>options.offsetX</code>: <code>number</code> - X方向像素偏移，支持负数，默认为 0</li><li><code>options.offsetY</code>: <code>number</code> - Y方向像素偏移，支持负数，默认为 0</li></ul><p><strong>返回值</strong>: <a href="/reference/types.html#point"><code>Promise&lt;Point[]&gt;</code></a></p><h2 id="getcustomcarpetpointsbyviewportcenter" tabindex="-1">getCustomCarpetPointsByViewportCenter() <a class="header-anchor" href="#getcustomcarpetpointsbyviewportcenter" aria-label="Permalink to &quot;getCustomCarpetPointsByViewportCenter()&quot;">​</a></h2><p>基于视口中心生成自定义地毯可用的四个顶点坐标。返回的点集既可用于 <code>shape: &#39;rectangle&#39;</code>，也可用于 <code>shape: &#39;round&#39;</code>。默认宽高和尺寸约束 来自 <code>controls.carpet.minSize</code> / <code>controls.carpet.maxSize</code>。</p><p><strong>类型</strong>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> getCustomCarpetPointsByViewportCenter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">options</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  width</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  height</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  offsetX</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  offsetY</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Point</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]</span></span></code></pre></div><p><strong>参数</strong>:</p><ul><li><code>options</code> - 配置选项</li><li><code>options.width</code>: <code>number</code> - 地毯宽度，单位米。未传且只传了 <code>height</code> 时跟随 <code>height</code></li><li><code>options.height</code>: <code>number</code> - 地毯高度，单位米。未传且只传了 <code>width</code> 时跟随 <code>width</code></li><li><code>options.offsetX</code>: <code>number</code> - X方向像素偏移，支持负数，默认为 <code>0</code></li><li><code>options.offsetY</code>: <code>number</code> - Y方向像素偏移，支持负数，默认为 <code>0</code></li></ul><p><strong>返回值</strong>: <a href="/reference/types.html#point"><code>Point[]</code></a></p><h2 id="getfurnitures" tabindex="-1">getFurnitures() <a class="header-anchor" href="#getfurnitures" aria-label="Permalink to &quot;getFurnitures()&quot;">​</a></h2><p>获取当前地图上所有家具数据。</p><p><strong>类型</strong>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> getFurnitures</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">FurnitureParam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]&gt;</span></span></code></pre></div><p><strong>返回值</strong>: <a href="/reference/types.html#furnitureparam"><code>Promise&lt;FurnitureParam[]&gt;</code></a></p><h2 id="getspotpointbyviewportcenter" tabindex="-1">getSpotPointByViewportCenter() <a class="header-anchor" href="#getspotpointbyviewportcenter" aria-label="Permalink to &quot;getSpotPointByViewportCenter()&quot;">​</a></h2><p>基于视口中心生成定点清扫的点坐标。</p><p><strong>类型</strong>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> getSpotPointByViewportCenter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">options</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  offsetX</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  offsetY</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Point</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><p><strong>参数</strong>:</p><ul><li><code>options</code> - 配置选项</li><li><code>options.size</code>: <code>number</code> - 区域大小，单位米，默认使用配置中的最小尺寸</li><li><code>options.offsetX</code>: <code>number</code> - X方向像素偏移，支持负数，默认为 0</li><li><code>options.offsetY</code>: <code>number</code> - Y方向像素偏移，支持负数，默认为 0</li></ul><p><strong>返回值</strong>: <a href="/reference/types.html#point"><code>Promise&lt;Point[]&gt;</code></a></p><h2 id="isnearchargerorrobot" tabindex="-1">isNearChargerOrRobot() <a class="header-anchor" href="#isnearchargerorrobot" aria-label="Permalink to &quot;isNearChargerOrRobot()&quot;">​</a></h2><p>判断一个点、墙体或区域是否与充电桩或机器人距离小于阈值。</p><p><strong>类型</strong>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> isNearChargerOrRobot</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
@@ -176,7 +181,8 @@ import{_ as i,c as a,o as n,aq as t}from"./chunks/framework.CBLqO2Q1.js";const g
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    virtualWalls</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> VirtualWallParam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    detectedObjects</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> DetectedObjectParam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    furnitures</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> FurnitureParam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    carpets</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> CustomCarpetParam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  runtime</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> DeepPartialRuntimeConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  options</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">backgroundColor</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ColorSource</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><p><strong>参数</strong>:</p><ul><li><code>data</code> - 地图数据对象</li><li><code>data.map</code>: <code>string</code> - 地图字符串数据 (支持结构化协议和栅格协议)</li><li><code>data.path</code>: <code>string</code> - 可选的路径数据</li><li><code>data.roomProperties</code>: <code>RoomProperty[]</code> - 可选的房间属性数据</li><li><code>data.customElements</code>: <code>CustomElementParam[]</code> - 可选的自定义元素数据</li><li><code>data.forbiddenSweepZones</code>: <code>ZoneParam[]</code> - 可选的禁扫区域数据</li><li><code>data.forbiddenMopZones</code>: <code>ZoneParam[]</code> - 可选的禁拖区域数据</li><li><code>data.virtualWalls</code>: <code>VirtualWallParam[]</code> - 可选的虚拟墙数据</li><li><code>data.detectedObjects</code>: <code>DetectedObjectParam[]</code> - 可选的检测物体数据</li><li><code>data.furnitures</code>: <a href="/reference/types.html#furnitureparam"><code>FurnitureParam[]</code></a> - 可选的家具数据</li><li><code>runtime</code> - 可选的运行时配置 (DeepPartialRuntimeConfig)</li><li><code>options</code> - 截图配置选项</li><li><code>options.backgroundColor</code>: <code>ColorSource</code> - 指定生成截图时的背景颜色。若不指定，将默认使用 <code>config.global.backgroundColor</code>。</li></ul><p><strong>返回值</strong>: <a href="/reference/types.html#string"><code>Promise&lt;string&gt;</code></a> - Base64 格式的图片数据 (Data URL)。</p><h2 id="forceendgesture" tabindex="-1">forceEndGesture() <a class="header-anchor" href="#forceendgesture" aria-label="Permalink to &quot;forceEndGesture()&quot;">​</a></h2><p>强制结束当前正在进行的手势交互。</p><p><strong>类型</strong>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> forceEndGesture</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><p><strong>返回值</strong>: <code>Promise&lt;void&gt;</code></p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>该方法主要用于解决小程序异层渲染导致的 <code>touchend</code> 事件丢失问题。如果小程序侧通过原生手势监听到松手，但 SDK 由于层级劫持未收到事件，可调用此方法手动终止 SDK 内部的手势状态。这会触发当前的控制元素（如禁区）执行最终的位置更新并抛出 <code>onUpdateXxx</code> 回调。</p></div>`,214)])])}const E=i(p,[["render",e]]);export{g as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><p><strong>参数</strong>:</p><ul><li><code>data</code> - 地图数据对象</li><li><code>data.map</code>: <code>string</code> - 地图字符串数据 (支持结构化协议和栅格协议)</li><li><code>data.path</code>: <code>string</code> - 可选的路径数据</li><li><code>data.roomProperties</code>: <code>RoomProperty[]</code> - 可选的房间属性数据</li><li><code>data.customElements</code>: <code>CustomElementParam[]</code> - 可选的自定义元素数据</li><li><code>data.forbiddenSweepZones</code>: <code>ZoneParam[]</code> - 可选的禁扫区域数据</li><li><code>data.forbiddenMopZones</code>: <code>ZoneParam[]</code> - 可选的禁拖区域数据</li><li><code>data.virtualWalls</code>: <code>VirtualWallParam[]</code> - 可选的虚拟墙数据</li><li><code>data.detectedObjects</code>: <code>DetectedObjectParam[]</code> - 可选的检测物体数据</li><li><code>data.furnitures</code>: <a href="/reference/types.html#furnitureparam"><code>FurnitureParam[]</code></a> - 可选的家具数据</li><li><code>data.carpets</code>: <a href="/reference/types.html#customcarpetparam"><code>CustomCarpetParam[]</code></a> - 可选的自定义地毯数据</li><li><code>runtime</code> - 可选的运行时配置 (DeepPartialRuntimeConfig)</li><li><code>options</code> - 截图配置选项</li><li><code>options.backgroundColor</code>: <code>ColorSource</code> - 指定生成截图时的背景颜色。若不指定，将默认使用 <code>config.global.backgroundColor</code>。</li></ul><p><strong>返回值</strong>: <a href="/reference/types.html#string"><code>Promise&lt;string&gt;</code></a> - Base64 格式的图片数据 (Data URL)。</p><h2 id="forceendgesture" tabindex="-1">forceEndGesture() <a class="header-anchor" href="#forceendgesture" aria-label="Permalink to &quot;forceEndGesture()&quot;">​</a></h2><p>强制结束当前正在进行的手势交互。</p><p><strong>类型</strong>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> forceEndGesture</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><p><strong>返回值</strong>: <code>Promise&lt;void&gt;</code></p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>该方法主要用于解决小程序异层渲染导致的 <code>touchend</code> 事件丢失问题。如果小程序侧通过原生手势监听到松手，但 SDK 由于层级劫持未收到事件，可调用此方法手动终止 SDK 内部的手势状态。这会触发当前的控制元素（如禁区）执行最终的位置更新并抛出 <code>onUpdateXxx</code> 回调。</p></div>`,221)])])}const E=i(e,[["render",p]]);export{g as __pageData,E as default};

package/dist-docs/assets/reference_methods.md.CxMQMj53.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as n,aq as t}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"地图方法","description":"","frontmatter":{},"headers":[],"relativePath":"reference/methods.md","filePath":"reference/methods.md","lastUpdated":1779070238000}'),e={name:"reference/methods.md"};function p(h,s,l,k,r,d){return n(),a("div",null,[...s[0]||(s[0]=[t("",221)])])}const E=i(e,[["render",p]]);export{g as __pageData,E as default};

package/dist-docs/guide/advanced-usage.html

@@ -9,11 +9,11 @@
     <link rel="preload stylesheet" href="/assets/style.hiWmcVfN.css" as="style">
     <link rel="preload stylesheet" href="/vp-icons.css" as="style">
     
-    <script type="module" src="/assets/app.bnP_bf_l.js"></script>
+    <script type="module" src="/assets/app.aFlmc9Oy.js"></script>
     <link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
-    <link rel="modulepreload" href="/assets/chunks/theme.DeJ2cHsN.js">
+    <link rel="modulepreload" href="/assets/chunks/theme.CnUzYoyt.js">
     <link rel="modulepreload" href="/assets/chunks/framework.CBLqO2Q1.js">
-    <link rel="modulepreload" href="/assets/guide_advanced-usage.md.Cpp8XDrz.lean.js">
+    <link rel="modulepreload" href="/assets/guide_advanced-usage.md.JAqVYRlM.lean.js">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
     <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
   </head>
@@ -953,7 +953,23 @@
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      // ... 其他属性</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    /&gt;</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  )</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="编辑地毯" tabindex="-1">编辑地毯 <a class="header-anchor" href="#编辑地毯" aria-label="Permalink to &quot;编辑地毯&quot;">​</a></h3><p>通过 <code>runtime.editingCarpetIds</code> 控制哪些地毯处于编辑状态。编辑模式下，地毯会显示删除、旋转和缩放控制按钮，用户可以通过手势进行拖拽移动。<code>controls.carpet.rotateMode</code> 用于切换点击旋转 90 度和按住拖动连续旋转；<code>controls.carpet.scaleMode</code> 用于切换自由缩放和等比缩放。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> MapPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="在视口中心创建地毯" tabindex="-1">在视口中心创建地毯 <a class="header-anchor" href="#在视口中心创建地毯" aria-label="Permalink to &quot;在视口中心创建地毯&quot;">​</a></h3><p>你可以通过 <code>getCustomCarpetPointsByViewportCenter()</code> 生成一组四点坐标， 再由业务层自己补 <code>id</code>、<code>type</code> 和 <code>shape</code>。同一组 <code>points</code> 既可以用于 矩形地毯，也可以用于圆形或椭圆形地毯。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> handleAddCarpet</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">shape</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;rectangle&#39;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;round&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> points</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mapApi.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getCustomCarpetPointsByViewportCenter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    width: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    height: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1.2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    offsetX: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  })</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  setCustomCarpets</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">((</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">prev</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    ...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prev,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`carpet-${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">length</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> +</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      type: selectedMaterialType,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      shape,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      points,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ])</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p><code>shape: &#39;custom&#39;</code> 仍然需要业务层自行提供多边形顶点，这个 helper 不会 生成自定义轮廓。</p><h3 id="编辑地毯" tabindex="-1">编辑地毯 <a class="header-anchor" href="#编辑地毯" aria-label="Permalink to &quot;编辑地毯&quot;">​</a></h3><p>通过 <code>runtime.editingCarpetIds</code> 控制哪些地毯处于编辑状态。编辑模式下，地毯会显示删除、旋转和缩放控制按钮，用户可以通过手势进行拖拽移动。<code>controls.carpet.rotateMode</code> 用于切换点击旋转 90 度和按住拖动连续旋转；<code>controls.carpet.scaleMode</code> 用于切换自由缩放和等比缩放。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> MapPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">customCarpets</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">setCustomCarpets</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> useState</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">CustomCarpetParam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]&gt;([</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // ...</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ])</span></span>
@@ -1155,8 +1171,8 @@
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (mapApi) {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    mapApi.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">forceEndGesture</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">提示</p><p>地图 SDK 内部已针对双指缩放时的快速松手做了防抖缓冲处理，搭配上述方案可获得最佳手势体验。</p></div></div></div></main><footer class="VPDocFooter" data-v-39a288b8 data-v-e257564d><!--[--><!--]--><div class="edit-info" data-v-e257564d><!----><div class="last-updated" data-v-e257564d><p class="VPLastUpdated" data-v-e257564d data-v-e98dd255>最后更新于: <time datetime="2026-05-13T02:09:13.000Z" data-v-e98dd255></time></p></div></div><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-e257564d><span class="visually-hidden" id="doc-footer-aria-label" data-v-e257564d>Pager</span><div class="pager" data-v-e257564d><a class="VPLink link pager-link prev" href="/guide/getting-started.html" data-v-e257564d><!--[--><span class="desc" data-v-e257564d>Previous page</span><span class="title" data-v-e257564d>快速开始</span><!--]--></a></div><div class="pager" data-v-e257564d><!----></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"guide_advanced-usage.md\":\"Cpp8XDrz\",\"guide_concepts.md\":\"CJ87tk-r\",\"guide_getting-started.md\":\"s2PQDUaI\",\"guide_mcp.md\":\"CabCiX8Z\",\"index.md\":\"wTsFvv0N\",\"plans_2026-03-04-detected-objects-visibility-design.md\":\"Dqboot5W\",\"plans_2026-03-04-show-detected-objects-implementation-plan.md\":\"CDWwQtWj\",\"plans_2026-03-10-simulator-debug-design.md\":\"BZibn7uw\",\"plans_2026-03-10-simulator-events-console-design.md\":\"BVmEzCbR\",\"plans_2026-03-10-simulator-events-console-implementation-plan.md\":\"S2f1zs9-\",\"plans_2026-03-10-simulator-runtime-controls-design.md\":\"mqeNaYgg\",\"plans_2026-03-10-simulator-runtime-controls-implementation-plan.md\":\"BXG1UWFt\",\"plans_2026-03-10-testing-rollout-next-steps-plan.md\":\"CGR6uZic\",\"plans_2026-03-11-simulator-logger-dump-implementation-plan.md\":\"Ck5BGdoX\",\"reference_callbacks.md\":\"FoJwSjMy\",\"reference_config.md\":\"DfWCSVSm\",\"reference_data.md\":\"B_XpUFrn\",\"reference_methods.md\":\"BvtVJ2dG\",\"reference_runtime.md\":\"BBP2J_yR\",\"reference_types.md\":\"CfnUIfkB\",\"reference_utils.md\":\"Dy6XKVWh\",\"simulator_index.md\":\"CF95Y_c9\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Tuya Robot Map\",\"description\":\"涂鸦扫地机地图组件\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"siteTitle\":\"Tuya Robot Map\",\"outline\":{\"level\":[2,6],\"label\":\"页面导航\"},\"nav\":[{\"text\":\"首页\",\"link\":\"/\"},{\"text\":\"指南\",\"link\":\"/guide/concepts\",\"activeMatch\":\"^/guide/\"},{\"text\":\"参考\",\"link\":\"/reference/data\",\"activeMatch\":\"^/reference/\"},{\"text\":\"模拟调试\",\"link\":\"/simulator/\",\"activeMatch\":\"^/simulator/\"}],\"sidebar\":{\"/guide/\":[{\"text\":\"指南\",\"items\":[{\"text\":\"基本概念\",\"link\":\"/guide/concepts\"},{\"text\":\"快速开始\",\"link\":\"/guide/getting-started\"},{\"text\":\"进阶使用\",\"link\":\"/guide/advanced-usage\"}]}],\"/reference/\":[{\"text\":\"组件Props\",\"items\":[{\"text\":\"数据\",\"link\":\"/reference/data\"},{\"text\":\"配置\",\"link\":\"/reference/config\"},{\"text\":\"运行时\",\"link\":\"/reference/runtime\"},{\"text\":\"地图事件回调\",\"link\":\"/reference/callbacks\"}]},{\"text\":\"方法\",\"items\":[{\"text\":\"地图方法\",\"link\":\"/reference/methods\"},{\"text\":\"工具方法\",\"link\":\"/reference/utils\"}]},{\"text\":\"类型定义\",\"items\":[{\"text\":\"类型定义\",\"link\":\"/reference/types\"}]}],\"/simulator/\":[{\"text\":\"模拟调试\",\"items\":[{\"text\":\"实时模拟调试\",\"link\":\"/simulator/\"}]}]},\"search\":{\"provider\":\"local\"},\"lastUpdated\":{\"text\":\"最后更新于\",\"formatOptions\":{\"dateStyle\":\"short\",\"timeStyle\":\"short\"}}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">提示</p><p>地图 SDK 内部已针对双指缩放时的快速松手做了防抖缓冲处理，搭配上述方案可获得最佳手势体验。</p></div></div></div></main><footer class="VPDocFooter" data-v-39a288b8 data-v-e257564d><!--[--><!--]--><div class="edit-info" data-v-e257564d><!----><div class="last-updated" data-v-e257564d><p class="VPLastUpdated" data-v-e257564d data-v-e98dd255>最后更新于: <time datetime="2026-05-13T11:51:05.000Z" data-v-e98dd255></time></p></div></div><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-e257564d><span class="visually-hidden" id="doc-footer-aria-label" data-v-e257564d>Pager</span><div class="pager" data-v-e257564d><a class="VPLink link pager-link prev" href="/guide/getting-started.html" data-v-e257564d><!--[--><span class="desc" data-v-e257564d>Previous page</span><span class="title" data-v-e257564d>快速开始</span><!--]--></a></div><div class="pager" data-v-e257564d><!----></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"guide_advanced-usage.md\":\"JAqVYRlM\",\"guide_concepts.md\":\"CJ87tk-r\",\"guide_getting-started.md\":\"BZorxbvR\",\"guide_mcp.md\":\"CabCiX8Z\",\"index.md\":\"wTsFvv0N\",\"plans_2026-03-04-detected-objects-visibility-design.md\":\"Dqboot5W\",\"plans_2026-03-04-show-detected-objects-implementation-plan.md\":\"CDWwQtWj\",\"plans_2026-03-10-simulator-debug-design.md\":\"BZibn7uw\",\"plans_2026-03-10-simulator-events-console-design.md\":\"BVmEzCbR\",\"plans_2026-03-10-simulator-events-console-implementation-plan.md\":\"S2f1zs9-\",\"plans_2026-03-10-simulator-runtime-controls-design.md\":\"mqeNaYgg\",\"plans_2026-03-10-simulator-runtime-controls-implementation-plan.md\":\"BXG1UWFt\",\"plans_2026-03-10-testing-rollout-next-steps-plan.md\":\"CGR6uZic\",\"plans_2026-03-11-simulator-logger-dump-implementation-plan.md\":\"Ck5BGdoX\",\"reference_callbacks.md\":\"FoJwSjMy\",\"reference_config.md\":\"DfWCSVSm\",\"reference_data.md\":\"B_XpUFrn\",\"reference_methods.md\":\"CxMQMj53\",\"reference_runtime.md\":\"BBP2J_yR\",\"reference_types.md\":\"CfnUIfkB\",\"reference_utils.md\":\"Dy6XKVWh\",\"simulator_index.md\":\"CF95Y_c9\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Tuya Robot Map\",\"description\":\"涂鸦扫地机地图组件\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"siteTitle\":\"Tuya Robot Map\",\"outline\":{\"level\":[2,6],\"label\":\"页面导航\"},\"nav\":[{\"text\":\"首页\",\"link\":\"/\"},{\"text\":\"指南\",\"link\":\"/guide/concepts\",\"activeMatch\":\"^/guide/\"},{\"text\":\"参考\",\"link\":\"/reference/data\",\"activeMatch\":\"^/reference/\"},{\"text\":\"模拟调试\",\"link\":\"/simulator/\",\"activeMatch\":\"^/simulator/\"}],\"sidebar\":{\"/guide/\":[{\"text\":\"指南\",\"items\":[{\"text\":\"基本概念\",\"link\":\"/guide/concepts\"},{\"text\":\"快速开始\",\"link\":\"/guide/getting-started\"},{\"text\":\"进阶使用\",\"link\":\"/guide/advanced-usage\"}]}],\"/reference/\":[{\"text\":\"组件Props\",\"items\":[{\"text\":\"数据\",\"link\":\"/reference/data\"},{\"text\":\"配置\",\"link\":\"/reference/config\"},{\"text\":\"运行时\",\"link\":\"/reference/runtime\"},{\"text\":\"地图事件回调\",\"link\":\"/reference/callbacks\"}]},{\"text\":\"方法\",\"items\":[{\"text\":\"地图方法\",\"link\":\"/reference/methods\"},{\"text\":\"工具方法\",\"link\":\"/reference/utils\"}]},{\"text\":\"类型定义\",\"items\":[{\"text\":\"类型定义\",\"link\":\"/reference/types\"}]}],\"/simulator/\":[{\"text\":\"模拟调试\",\"items\":[{\"text\":\"实时模拟调试\",\"link\":\"/simulator/\"}]}]},\"search\":{\"provider\":\"local\"},\"lastUpdated\":{\"text\":\"最后更新于\",\"formatOptions\":{\"dateStyle\":\"short\",\"timeStyle\":\"short\"}}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>

package/dist-docs/guide/concepts.html

@@ -9,9 +9,9 @@
     <link rel="preload stylesheet" href="/assets/style.hiWmcVfN.css" as="style">
     <link rel="preload stylesheet" href="/vp-icons.css" as="style">
     
-    <script type="module" src="/assets/app.bnP_bf_l.js"></script>
+    <script type="module" src="/assets/app.aFlmc9Oy.js"></script>
     <link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
-    <link rel="modulepreload" href="/assets/chunks/theme.DeJ2cHsN.js">
+    <link rel="modulepreload" href="/assets/chunks/theme.CnUzYoyt.js">
     <link rel="modulepreload" href="/assets/chunks/framework.CBLqO2Q1.js">
     <link rel="modulepreload" href="/assets/guide_concepts.md.CJ87tk-r.lean.js">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
@@ -21,7 +21,7 @@
     <div id="app"><div class="Layout" data-v-5d98c3a5><!--[--><!--]--><!--[--><span tabindex="-1" data-v-0b0ada53></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-0b0ada53>Skip to content</a><!--]--><!----><header class="VPNav" data-v-5d98c3a5 data-v-ae24b3ad><div class="VPNavBar" data-v-ae24b3ad data-v-6aa21345><div class="wrapper" data-v-6aa21345><div class="container" data-v-6aa21345><div class="title" data-v-6aa21345><div class="VPNavBarTitle has-sidebar" data-v-6aa21345 data-v-1168a8e4><a class="title" href="/" data-v-1168a8e4><!--[--><!--]--><!----><span data-v-1168a8e4>Tuya Robot Map</span><!--[--><!--]--></a></div></div><div class="content" data-v-6aa21345><div class="content-body" data-v-6aa21345><!--[--><!--]--><div class="VPNavBarSearch search" data-v-6aa21345><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-6aa21345 data-v-dc692963><span id="main-nav-aria-label" class="visually-hidden" data-v-dc692963> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/" tabindex="0" data-v-dc692963 data-v-e56f3d57><!--[--><span data-v-e56f3d57>首页</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink active" href="/guide/concepts.html" tabindex="0" data-v-dc692963 data-v-e56f3d57><!--[--><span data-v-e56f3d57>指南</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/reference/data.html" tabindex="0" data-v-dc692963 data-v-e56f3d57><!--[--><span data-v-e56f3d57>参考</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/simulator/" tabindex="0" data-v-dc692963 data-v-e56f3d57><!--[--><span data-v-e56f3d57>模拟调试</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-6aa21345 data-v-6c893767><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6c893767 data-v-5337faa4 data-v-1d5665e3><span class="check" data-v-1d5665e3><span class="icon" data-v-1d5665e3><!--[--><span class="vpi-sun sun" data-v-5337faa4></span><span class="vpi-moon moon" data-v-5337faa4></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-6aa21345 data-v-bb2aa2f0 data-v-cf11d7a2><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-cf11d7a2><span class="vpi-more-horizontal icon" data-v-cf11d7a2></span></button><div class="menu" data-v-cf11d7a2><div class="VPMenu" data-v-cf11d7a2 data-v-b98bc113><!----><!--[--><!--[--><!----><div class="group" data-v-bb2aa2f0><div class="item appearance" data-v-bb2aa2f0><p class="label" data-v-bb2aa2f0>Appearance</p><div class="appearance-action" data-v-bb2aa2f0><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-bb2aa2f0 data-v-5337faa4 data-v-1d5665e3><span class="check" data-v-1d5665e3><span class="icon" data-v-1d5665e3><!--[--><span class="vpi-sun sun" data-v-5337faa4></span><span class="vpi-moon moon" data-v-5337faa4></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-6aa21345 data-v-e5dd9c1c><span class="container" data-v-e5dd9c1c><span class="top" data-v-e5dd9c1c></span><span class="middle" data-v-e5dd9c1c></span><span class="bottom" data-v-e5dd9c1c></span></span></button></div></div></div></div><div class="divider" data-v-6aa21345><div class="divider-line" data-v-6aa21345></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-5d98c3a5 data-v-a6f0e41e><div class="container" data-v-a6f0e41e><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-a6f0e41e><span class="vpi-align-left menu-icon" data-v-a6f0e41e></span><span class="menu-text" data-v-a6f0e41e>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-a6f0e41e data-v-8a42e2b4><button data-v-8a42e2b4>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-5d98c3a5 data-v-319d5ca6><div class="curtain" data-v-319d5ca6></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-319d5ca6><span class="visually-hidden" id="sidebar-aria-label" data-v-319d5ca6> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-c40bc020><section class="VPSidebarItem level-0 has-active" data-v-c40bc020 data-v-b3fd67f8><div class="item" role="button" tabindex="0" data-v-b3fd67f8><div class="indicator" data-v-b3fd67f8></div><h2 class="text" data-v-b3fd67f8>指南</h2><!----></div><div class="items" data-v-b3fd67f8><!--[--><div class="VPSidebarItem level-1 is-link" data-v-b3fd67f8 data-v-b3fd67f8><div class="item" data-v-b3fd67f8><div class="indicator" data-v-b3fd67f8></div><a class="VPLink link link" href="/guide/concepts.html" data-v-b3fd67f8><!--[--><p class="text" data-v-b3fd67f8>基本概念</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-b3fd67f8 data-v-b3fd67f8><div class="item" data-v-b3fd67f8><div class="indicator" data-v-b3fd67f8></div><a class="VPLink link link" href="/guide/getting-started.html" data-v-b3fd67f8><!--[--><p class="text" data-v-b3fd67f8>快速开始</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-b3fd67f8 data-v-b3fd67f8><div class="item" data-v-b3fd67f8><div class="indicator" data-v-b3fd67f8></div><a class="VPLink link link" href="/guide/advanced-usage.html" data-v-b3fd67f8><!--[--><p class="text" data-v-b3fd67f8>进阶使用</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-5d98c3a5 data-v-1428d186><div class="VPDoc has-sidebar has-aside" data-v-1428d186 data-v-39a288b8><!--[--><!--]--><div class="container" data-v-39a288b8><div class="aside" data-v-39a288b8><div class="aside-curtain" data-v-39a288b8></div><div class="aside-container" data-v-39a288b8><div class="aside-content" data-v-39a288b8><div class="VPDocAside" data-v-39a288b8 data-v-3f215769><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-3f215769 data-v-a5bbad30><div class="content" data-v-a5bbad30><div class="outline-marker" data-v-a5bbad30></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-a5bbad30>页面导航</div><ul class="VPDocOutlineItem root" data-v-a5bbad30 data-v-b933a997><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-3f215769></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-39a288b8><div class="content-container" data-v-39a288b8><!--[--><!--]--><main class="main" data-v-39a288b8><div style="position:relative;" class="vp-doc _guide_concepts" data-v-39a288b8><div><h1 id="基本概念" tabindex="-1">基本概念 <a class="header-anchor" href="#基本概念" aria-label="Permalink to &quot;基本概念&quot;">​</a></h1><p>了解 Tuya Robot Map 的核心概念。</p><h2 id="核心组件" tabindex="-1">核心组件 <a class="header-anchor" href="#核心组件" aria-label="Permalink to &quot;核心组件&quot;">​</a></h2><p>后续文档中，我们会使用 <code>RobotMap</code> 组件作为示例，你可以根据实际需求选择使用 <code>RobotMap</code> 或 <code>RjsRobotMap</code> 组件。</p><h3 id="robotmap-组件" tabindex="-1">RobotMap 组件 <a class="header-anchor" href="#robotmap-组件" aria-label="Permalink to &quot;RobotMap 组件&quot;">​</a></h3><p>React 地图组件，提供完整的地图渲染和交互功能：</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RobotMap</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> /&gt;</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><ul><li><p><code>RobotMap</code> 组件是基于 <a href="https://developer.tuya.com/cn/miniapp/develop/ray/component/open/web-view" target="_blank" rel="noreferrer">WebView</a> 开发的，开发前请详细阅读<a href="https://developer.tuya.com/cn/miniapp/develop/miniapp/component/native-component/native-component" target="_blank" rel="noreferrer">原生组件说明</a>。</p></li><li><p><code>RobotMap</code> 默认铺满全屏，适用于<strong>首页实时地图</strong>等场景，一个页面只能有一个 <code>RobotMap</code> 组件。</p></li><li><p>需要在小程序<code>global.config.ts</code>中配置<code>webviewRoot</code>让小程序能够正确加载<code>RobotMap</code>的资源。</p></li></ul><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;webviewRoot&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;node_modules/@ray-js/robot-map-sdk/dist-app&quot;</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div></div><h3 id="rjsrobotmap-组件" tabindex="-1">RjsRobotMap 组件 <a class="header-anchor" href="#rjsrobotmap-组件" aria-label="Permalink to &quot;RjsRobotMap 组件&quot;">​</a></h3><p>基于Rjs开发的地图组件，它拥有和 <code>RobotMap</code> 组件相同的Props。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RjsRobotMap</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> /&gt;</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p><code>RjsRobotMap</code> 基于 <a href="https://developer.tuya.com/cn/miniapp/develop/ray/framework/render" target="_blank" rel="noreferrer">Rjs</a> 开发，它没有原生组件的限制，一个页面可以有多个 <code>RjsRobotMap</code> 组件。适用于<strong>多地图</strong>、<strong>弹窗里的地图</strong> 等场景。</p></div><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>引入 <code>RjsRobotMap</code> 对页面加载速度有一定影响。如无必要场景，我们建议始终使用 <code>RobotMap</code> 组件。</p></div><h2 id="坐标系统" tabindex="-1">坐标系统 <a class="header-anchor" href="#坐标系统" aria-label="Permalink to &quot;坐标系统&quot;">​</a></h2><h3 id="地图原点坐标" tabindex="-1">地图原点坐标 <a class="header-anchor" href="#地图原点坐标" aria-label="Permalink to &quot;地图原点坐标&quot;">​</a></h3><p>地图原点是扫地机器人运行过程中确定的参考点，地图上的元素都是基于这个原点计算的相对位置。</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>地图原点本身是相对于地图左上角来定位的。例如在一张100 x 100(宽 x 高)的 地图中，如果原点坐标是(20, 80)，表示原点位于相对于地图左上角(20, 80)的位置。</p></div><h3 id="地图坐标系" tabindex="-1">地图坐标系 <a class="header-anchor" href="#地图坐标系" aria-label="Permalink to &quot;地图坐标系&quot;">​</a></h3><p>地图坐标系是本 SDK 实际使用的坐标系，用于在地图上渲染和显示各种元素。地图坐标系以地图原点为中心(0, 0)：</p><ul><li>X轴：向右为正方向</li><li>Y轴：向下为正方向</li></ul><h4 id="与机器坐标系的不同" tabindex="-1">与机器坐标系的不同 <a class="header-anchor" href="#与机器坐标系的不同" aria-label="Permalink to &quot;与机器坐标系的不同&quot;">​</a></h4><p>需要注意的是，本 SDK 使用的地图坐标系与扫地机器人设备本身使用的机器坐标系在 Y 轴方向上相反：</p><ul><li><p><strong>机器坐标系</strong>（设备使用的坐标系）：</p><ul><li>X轴：向右为正方向</li><li>Y轴：向上为正方向</li></ul></li><li><p><strong>地图坐标系</strong>（本 SDK 使用的坐标系）：</p><ul><li>X轴：向右为正方向（与机器坐标系一致）</li><li>Y轴：向下为正方向（与机器坐标系相反）</li></ul></li></ul><p>SDK 采用标准的屏幕坐标系（Screen Coordinate System）进行渲染，因此 Y 轴方向与机器坐标系相反。在 SDK 中，如果原点在(0, 0)，坐标为(1, 1)的点会渲染在原点的右下方。</p><p>例如，以下元素的坐标均使用地图坐标系：</p><ul><li>充电桩</li><li>清扫路径 (含机器人位置)</li><li>虚拟墙</li><li>禁区</li><li>清扫区域</li><li>分割线</li><li>其他自定义元素</li><li>...</li></ul><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>本文档中，如果未特别说明，涉及到的坐标均指地图坐标系（X向右，Y向下）。</p></div></div></div></main><footer class="VPDocFooter" data-v-39a288b8 data-v-e257564d><!--[--><!--]--><div class="edit-info" data-v-e257564d><!----><div class="last-updated" data-v-e257564d><p class="VPLastUpdated" data-v-e257564d data-v-e98dd255>最后更新于: <time datetime="2025-12-30T11:04:05.000Z" data-v-e98dd255></time></p></div></div><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-e257564d><span class="visually-hidden" id="doc-footer-aria-label" data-v-e257564d>Pager</span><div class="pager" data-v-e257564d><!----></div><div class="pager" data-v-e257564d><a class="VPLink link pager-link next" href="/guide/getting-started.html" data-v-e257564d><!--[--><span class="desc" data-v-e257564d>Next page</span><span class="title" data-v-e257564d>快速开始</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"guide_advanced-usage.md\":\"Cpp8XDrz\",\"guide_concepts.md\":\"CJ87tk-r\",\"guide_getting-started.md\":\"s2PQDUaI\",\"guide_mcp.md\":\"CabCiX8Z\",\"index.md\":\"wTsFvv0N\",\"plans_2026-03-04-detected-objects-visibility-design.md\":\"Dqboot5W\",\"plans_2026-03-04-show-detected-objects-implementation-plan.md\":\"CDWwQtWj\",\"plans_2026-03-10-simulator-debug-design.md\":\"BZibn7uw\",\"plans_2026-03-10-simulator-events-console-design.md\":\"BVmEzCbR\",\"plans_2026-03-10-simulator-events-console-implementation-plan.md\":\"S2f1zs9-\",\"plans_2026-03-10-simulator-runtime-controls-design.md\":\"mqeNaYgg\",\"plans_2026-03-10-simulator-runtime-controls-implementation-plan.md\":\"BXG1UWFt\",\"plans_2026-03-10-testing-rollout-next-steps-plan.md\":\"CGR6uZic\",\"plans_2026-03-11-simulator-logger-dump-implementation-plan.md\":\"Ck5BGdoX\",\"reference_callbacks.md\":\"FoJwSjMy\",\"reference_config.md\":\"DfWCSVSm\",\"reference_data.md\":\"B_XpUFrn\",\"reference_methods.md\":\"BvtVJ2dG\",\"reference_runtime.md\":\"BBP2J_yR\",\"reference_types.md\":\"CfnUIfkB\",\"reference_utils.md\":\"Dy6XKVWh\",\"simulator_index.md\":\"CF95Y_c9\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Tuya Robot Map\",\"description\":\"涂鸦扫地机地图组件\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"siteTitle\":\"Tuya Robot Map\",\"outline\":{\"level\":[2,6],\"label\":\"页面导航\"},\"nav\":[{\"text\":\"首页\",\"link\":\"/\"},{\"text\":\"指南\",\"link\":\"/guide/concepts\",\"activeMatch\":\"^/guide/\"},{\"text\":\"参考\",\"link\":\"/reference/data\",\"activeMatch\":\"^/reference/\"},{\"text\":\"模拟调试\",\"link\":\"/simulator/\",\"activeMatch\":\"^/simulator/\"}],\"sidebar\":{\"/guide/\":[{\"text\":\"指南\",\"items\":[{\"text\":\"基本概念\",\"link\":\"/guide/concepts\"},{\"text\":\"快速开始\",\"link\":\"/guide/getting-started\"},{\"text\":\"进阶使用\",\"link\":\"/guide/advanced-usage\"}]}],\"/reference/\":[{\"text\":\"组件Props\",\"items\":[{\"text\":\"数据\",\"link\":\"/reference/data\"},{\"text\":\"配置\",\"link\":\"/reference/config\"},{\"text\":\"运行时\",\"link\":\"/reference/runtime\"},{\"text\":\"地图事件回调\",\"link\":\"/reference/callbacks\"}]},{\"text\":\"方法\",\"items\":[{\"text\":\"地图方法\",\"link\":\"/reference/methods\"},{\"text\":\"工具方法\",\"link\":\"/reference/utils\"}]},{\"text\":\"类型定义\",\"items\":[{\"text\":\"类型定义\",\"link\":\"/reference/types\"}]}],\"/simulator/\":[{\"text\":\"模拟调试\",\"items\":[{\"text\":\"实时模拟调试\",\"link\":\"/simulator/\"}]}]},\"search\":{\"provider\":\"local\"},\"lastUpdated\":{\"text\":\"最后更新于\",\"formatOptions\":{\"dateStyle\":\"short\",\"timeStyle\":\"short\"}}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"guide_advanced-usage.md\":\"JAqVYRlM\",\"guide_concepts.md\":\"CJ87tk-r\",\"guide_getting-started.md\":\"BZorxbvR\",\"guide_mcp.md\":\"CabCiX8Z\",\"index.md\":\"wTsFvv0N\",\"plans_2026-03-04-detected-objects-visibility-design.md\":\"Dqboot5W\",\"plans_2026-03-04-show-detected-objects-implementation-plan.md\":\"CDWwQtWj\",\"plans_2026-03-10-simulator-debug-design.md\":\"BZibn7uw\",\"plans_2026-03-10-simulator-events-console-design.md\":\"BVmEzCbR\",\"plans_2026-03-10-simulator-events-console-implementation-plan.md\":\"S2f1zs9-\",\"plans_2026-03-10-simulator-runtime-controls-design.md\":\"mqeNaYgg\",\"plans_2026-03-10-simulator-runtime-controls-implementation-plan.md\":\"BXG1UWFt\",\"plans_2026-03-10-testing-rollout-next-steps-plan.md\":\"CGR6uZic\",\"plans_2026-03-11-simulator-logger-dump-implementation-plan.md\":\"Ck5BGdoX\",\"reference_callbacks.md\":\"FoJwSjMy\",\"reference_config.md\":\"DfWCSVSm\",\"reference_data.md\":\"B_XpUFrn\",\"reference_methods.md\":\"CxMQMj53\",\"reference_runtime.md\":\"BBP2J_yR\",\"reference_types.md\":\"CfnUIfkB\",\"reference_utils.md\":\"Dy6XKVWh\",\"simulator_index.md\":\"CF95Y_c9\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Tuya Robot Map\",\"description\":\"涂鸦扫地机地图组件\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"siteTitle\":\"Tuya Robot Map\",\"outline\":{\"level\":[2,6],\"label\":\"页面导航\"},\"nav\":[{\"text\":\"首页\",\"link\":\"/\"},{\"text\":\"指南\",\"link\":\"/guide/concepts\",\"activeMatch\":\"^/guide/\"},{\"text\":\"参考\",\"link\":\"/reference/data\",\"activeMatch\":\"^/reference/\"},{\"text\":\"模拟调试\",\"link\":\"/simulator/\",\"activeMatch\":\"^/simulator/\"}],\"sidebar\":{\"/guide/\":[{\"text\":\"指南\",\"items\":[{\"text\":\"基本概念\",\"link\":\"/guide/concepts\"},{\"text\":\"快速开始\",\"link\":\"/guide/getting-started\"},{\"text\":\"进阶使用\",\"link\":\"/guide/advanced-usage\"}]}],\"/reference/\":[{\"text\":\"组件Props\",\"items\":[{\"text\":\"数据\",\"link\":\"/reference/data\"},{\"text\":\"配置\",\"link\":\"/reference/config\"},{\"text\":\"运行时\",\"link\":\"/reference/runtime\"},{\"text\":\"地图事件回调\",\"link\":\"/reference/callbacks\"}]},{\"text\":\"方法\",\"items\":[{\"text\":\"地图方法\",\"link\":\"/reference/methods\"},{\"text\":\"工具方法\",\"link\":\"/reference/utils\"}]},{\"text\":\"类型定义\",\"items\":[{\"text\":\"类型定义\",\"link\":\"/reference/types\"}]}],\"/simulator/\":[{\"text\":\"模拟调试\",\"items\":[{\"text\":\"实时模拟调试\",\"link\":\"/simulator/\"}]}]},\"search\":{\"provider\":\"local\"},\"lastUpdated\":{\"text\":\"最后更新于\",\"formatOptions\":{\"dateStyle\":\"short\",\"timeStyle\":\"short\"}}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>