Clarify expandable bottom accessory behavior

Author: jinwandalaohu66

docs/docs/pages/appui-ref-navigation/index.html

@@ -501,7 +501,8 @@ <h2 id="可展开底部附件"><a class="heading-anchor" href="#可展开底部
 
 appui.run(body, state=state)</code></pre>
 </figure>
-<p>紧凑条会放在底部系统区域；iOS 26 使用原生 TabView bottom accessory 承载 <code>compact</code> 内容，<code>expanded</code> 内容单独呈现为完整面板，避免被压进 tab bar 区域。旧系统降级为底部 safe-area inset 加 sheet。不要再额外给同一个 <code>TabView</code> 挂底部 <code>safe_area_bar</code>，否则会和底部附件争同一块区域。</p>
+<p>紧凑条会放在底部系统区域；iOS 26 使用原生 TabView bottom accessory 承载 <code>compact</code> 内容，点击后由宿主在同一个根视图里展开 <code>expanded</code> 覆盖层，并支持下滑收起。它不是 <code>.sheet</code> / <code>.full_screen_cover</code>，所以适合做类似 Apple Music 迷你播放条展开成播放器的连续体验。旧系统降级为底部 safe-area inset 加 sheet。不要再额外给同一个 <code>TabView</code> 挂底部 <code>safe_area_bar</code>，否则会和底部附件争同一块区域。</p>
+<p>如果希望封面、标题等元素在紧凑条和展开页之间连续过渡，可以在 compact / expanded 两边给对应子视图设置相同的 <code>.matched_geometry_effect(ns_id=..., namespace=...)</code>，compact 侧通常作为 <code>is_source=True</code>，expanded 侧作为 <code>is_source=False</code>。这只是动画标记，不限制展开页的 UI 结构。</p>
 <h2 id="常用修饰符"><a class="heading-anchor" href="#常用修饰符">#</a>常用修饰符</h2>
 <div class="table-scroll"><table><thead><tr><th>API</th><th>签名</th><th>所属类型</th></tr></thead><tbody><tr><td><code>.navigation_title</code></td><td><code>.navigation_title(title: Union[str, &quot;View&quot;]) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.navigation_bar_title_display_mode</code></td><td><code>.navigation_bar_title_display_mode(mode: str) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.navigation_bar_back_button_hidden</code></td><td><code>.navigation_bar_back_button_hidden(value: bool = True) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.toolbar</code></td><td><code>.toolbar(items: Any) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.toolbar_background</code></td><td><code>.toolbar_background(visibility: str = &#x27;visible&#x27;, bars: str = &#x27;navigation_bar&#x27;) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.toolbar_color_scheme</code></td><td><code>.toolbar_color_scheme(scheme: str = &#x27;dark&#x27;, bars: str = &#x27;navigation_bar&#x27;) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.navigation_destination</code></td><td><code>.navigation_destination(is_presented: bool = False, content: Optional[&quot;View&quot;] = None, on_dismiss: Optional[Callable] = None, isPresented: Optional[bool] = None, onDismiss: Optional[Callable] = None) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.safe_area_bar</code></td><td><code>.safe_area_bar(edge: str = &#x27;bottom&#x27;, content: Optional[&quot;View&quot;] = None, alignment: str = &#x27;center&#x27;, spacing: Optional[float] = None, safeAreaEdge: Optional[str] = None) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.tab_view_bottom_accessory</code></td><td><code>.tab_view_bottom_accessory(content: Optional[&quot;View&quot;] = None, enabled: bool = True, is_enabled: Optional[bool] = None, isEnabled: Optional[bool] = None) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.expandable_bottom_accessory</code></td><td><code>.expandable_bottom_accessory(compact: Optional[Union[&quot;View&quot;, Callable[[], &quot;View&quot;]]] = None, expanded: Optional[Union[&quot;View&quot;, Callable[[], &quot;View&quot;]]] = None, is_presented: bool = False, on_dismiss: Optional[Callable] = None, enabled: bool = True, detents: Optional[str] = &#x27;large&#x27;, drag_indicator: Optional[str] = &#x27;visible&#x27;, interactive_dismiss_disabled: bool = False, isPresented: Optional[bool] = None, onDismiss: Optional[Callable] = None, is_enabled: Optional[bool] = None, isEnabled: Optional[bool] = None, dragIndicator: Optional[str] = None, interactiveDismissDisabled: Optional[bool] = None, on_expand: Optional[Callable] = None, onExpand: Optional[Callable] = None) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.tab_bar_minimize_behavior</code></td><td><code>.tab_bar_minimize_behavior(behavior: str = &#x27;automatic&#x27;) -&gt; Self</code></td><td><code>View</code></td></tr><tr><td><code>.tab_view_search_activation</code></td><td><code>.tab_view_search_activation(activation: str = &#x27;search_tab_selection&#x27;) -&gt; Self</code></td><td><code>View</code></td></tr></tbody></table></div>
 <h2 id="与相邻-api-的区别"><a class="heading-anchor" href="#与相邻-api-的区别">#</a>与相邻 API 的区别</h2>

docs/docs/pages/miniapp-appui-api-index/index.html

@@ -341,7 +341,7 @@ <h2 id="最小正确组合"><a class="heading-anchor" href="#最小正确组合"
 <h2 id="按任务查-api"><a class="heading-anchor" href="#按任务查-api">#</a>按任务查 API</h2>
 <div class="table-scroll"><table><thead><tr><th>任务</th><th>首选 API</th><th>继续阅读</th></tr></thead><tbody><tr><td>启动 MiniApp</td><td><code>appui.run</code></td><td><a href="../../pages/appui-ref-functions/">函数参考</a></td></tr><tr><td>控制呈现方式</td><td><code>appui.run(..., presentation=...)</code></td><td><a href="../../pages/appui-ref-functions/">函数参考</a></td></tr><tr><td>程序化弹层</td><td><code>presentation_present</code> / <code>presentation_dismiss</code></td><td><a href="../../pages/appui-ref-presentation/">呈现 API</a></td></tr><tr><td>保存普通界面状态</td><td><code>State</code></td><td><a href="../../pages/appui-guide-state/">状态管理</a></td></tr><tr><td>多字段一起更新</td><td><code>state.batch_update(...)</code></td><td><a href="../../pages/appui-guide-state/">状态管理</a></td></tr><tr><td>高频局部刷新</td><td><code>ReactiveState</code></td><td><a href="../../pages/appui-guide-performance/">性能与实时界面</a></td></tr><tr><td>派生数据</td><td><code>computed</code></td><td><a href="../../pages/appui-guide-state/">状态管理</a></td></tr><tr><td>状态变化后的副作用</td><td><code>effect</code></td><td><a href="../../pages/appui-guide-state/">状态管理</a></td></tr><tr><td>双向绑定</td><td><code>bind</code></td><td><a href="../../pages/appui-ref-functions/">函数参考</a></td></tr><tr><td>输入设置项</td><td><code>Form + Section</code></td><td><a href="../../pages/appui-guide-layout/">布局系统</a></td></tr><tr><td>动态列表</td><td><code>List + ForEach</code></td><td><a href="../../pages/appui-guide-layout/">布局系统</a></td></tr><tr><td>列表进详情</td><td><code>NavigationStack + NavigationLink</code></td><td><a href="../../pages/appui-guide-navigation/">导航与页面结构</a></td></tr><tr><td>程序化跳转</td><td><code>NavigationPath + destinations</code></td><td><a href="../../pages/appui-guide-navigation/">导航与页面结构</a></td></tr><tr><td>多主分区</td><td><code>TabView + Tab</code></td><td><a href="../../pages/appui-guide-navigation/">导航与页面结构</a></td></tr><tr><td>底部状态条展开面板</td><td><code>.expandable_bottom_accessory</code></td><td><a href="../../pages/appui-ref-navigation/#可展开底部附件">导航参考</a></td></tr><tr><td>导航栏按钮</td><td><code>ToolbarItem</code></td><td><a href="../../pages/appui-ref-navigation/">导航参考</a></td></tr><tr><td>临时弹层</td><td><code>.sheet</code> / <code>.popover</code></td><td><a href="../../pages/appui-ref-presentation/">呈现 API</a></td></tr><tr><td>确认和错误提示</td><td><code>.alert</code> / <code>.confirmation_dialog</code></td><td><a href="../../pages/appui-ref-presentation/">呈现 API</a></td></tr><tr><td>搜索和刷新</td><td><code>.searchable</code> / <code>.refreshable</code></td><td><a href="../../pages/appui-guide-interaction/">交互与回调</a></td></tr><tr><td>空状态</td><td><code>ContentUnavailableView</code></td><td><a href="../../pages/appui-ref-data/">数据展示</a></td></tr><tr><td>加载状态</td><td><code>ProgressView</code></td><td><a href="../../pages/appui-ref-data/">数据展示</a></td></tr><tr><td>输入控件</td><td><code>TextField</code>、<code>SecureField</code>、<code>TextEditor</code></td><td><a href="../../pages/appui-ref-controls/">控件 API</a></td></tr><tr><td>选择控件</td><td><code>Toggle</code>、<code>Picker</code>、<code>Slider</code>、<code>Stepper</code></td><td><a href="../../pages/appui-ref-controls/">控件 API</a></td></tr><tr><td>媒体和文件</td><td><code>PhotoPicker</code>、<code>CameraPicker</code>、<code>FileImporter</code></td><td><a href="../../pages/appui-ref-media/">媒体 API</a></td></tr><tr><td>地图、网页、视频</td><td><code>MapView</code>、<code>WebView</code>、<code>VideoPlayer</code></td><td><a href="../../pages/appui-ref-media/">媒体 API</a></td></tr><tr><td>图表和绘制</td><td><code>Chart</code>、<code>Canvas</code>、<code>DrawingContext</code>、<code>Path</code></td><td><a href="../../pages/appui-ref-charts/">图表 API</a></td></tr></tbody></table></div>
 <h2 id="行为契约"><a class="heading-anchor" href="#行为契约">#</a>行为契约</h2>
-<div class="table-scroll"><table><thead><tr><th>API</th><th>保证</th><th>注意</th></tr></thead><tbody><tr><td><code>appui.run(...)</code></td><td>启动当前 MiniApp 页面。</td><td>一个脚本只保留一个最终入口。</td></tr><tr><td><code>State</code></td><td>字段变化后页面重建。</td><td>多字段同时更新用 <code>batch_update(...)</code>。</td></tr><tr><td><code>Button(action=...)</code></td><td>点击后执行命名回调。</td><td>不要写 <code>action=save()</code>。</td></tr><tr><td><code>TextField(on_change=...)</code></td><td>输入变化时把新值交给回调。</td><td>回调要写回 <code>State</code>。</td></tr><tr><td><code>ForEach(..., key=...)</code></td><td>维护动态行身份。</td><td>key 必须来自稳定业务 id。</td></tr><tr><td><code>NavigationLink</code></td><td>打开目标详情页。</td><td>目标页用函数返回 View，避免把复杂逻辑塞进行内。</td></tr><tr><td><code>.expandable_bottom_accessory(...)</code></td><td>底部常驻 compact 视图点击后展开 expanded 视图。</td><td>适合播放、下载、录音、导航等持续任务；不要和底部 <code>safe_area_bar</code> 同挂一个 <code>TabView</code>。</td></tr><tr><td><code>.sheet(...)</code> / <code>.alert(...)</code></td><td>展示临时页面或提示。</td><td><code>is_presented</code> 要由状态控制。</td></tr><tr><td><code>PhotoPicker</code> / <code>FileImporter</code></td><td>触发系统选择流程。</td><td>处理用户取消、权限拒绝和空结果。</td></tr></tbody></table></div>
+<div class="table-scroll"><table><thead><tr><th>API</th><th>保证</th><th>注意</th></tr></thead><tbody><tr><td><code>appui.run(...)</code></td><td>启动当前 MiniApp 页面。</td><td>一个脚本只保留一个最终入口。</td></tr><tr><td><code>State</code></td><td>字段变化后页面重建。</td><td>多字段同时更新用 <code>batch_update(...)</code>。</td></tr><tr><td><code>Button(action=...)</code></td><td>点击后执行命名回调。</td><td>不要写 <code>action=save()</code>。</td></tr><tr><td><code>TextField(on_change=...)</code></td><td>输入变化时把新值交给回调。</td><td>回调要写回 <code>State</code>。</td></tr><tr><td><code>ForEach(..., key=...)</code></td><td>维护动态行身份。</td><td>key 必须来自稳定业务 id。</td></tr><tr><td><code>NavigationLink</code></td><td>打开目标详情页。</td><td>目标页用函数返回 View，避免把复杂逻辑塞进行内。</td></tr><tr><td><code>.expandable_bottom_accessory(...)</code></td><td>底部常驻 compact 视图点击后展开 expanded 视图。</td><td>iOS 26 是宿主根视图连续展开覆盖层，不是 sheet；适合播放、下载、录音、导航等持续任务。不要和底部 <code>safe_area_bar</code> 同挂一个 <code>TabView</code>。</td></tr><tr><td><code>.sheet(...)</code> / <code>.alert(...)</code></td><td>展示临时页面或提示。</td><td><code>is_presented</code> 要由状态控制。</td></tr><tr><td><code>PhotoPicker</code> / <code>FileImporter</code></td><td>触发系统选择流程。</td><td>处理用户取消、权限拒绝和空结果。</td></tr></tbody></table></div>
 <h2 id="选择顺序"><a class="heading-anchor" href="#选择顺序">#</a>选择顺序</h2>
 <ol><li>先选容器：<code>NavigationStack</code>、<code>TabView</code>、<code>List</code>、<code>Form</code>、<code>ScrollView</code>。</li><li>再选数据流：<code>State</code>、<code>ReactiveState</code>、<code>bind</code>、<code>computed</code>、<code>Timer</code>。</li><li>再选控件：输入、选择、按钮、工具栏、弹层。</li><li>再选状态反馈：空状态、加载、错误、保存成功、权限拒绝。</li><li>最后选视觉：字体、颜色、边距、背景、图表或媒体。</li></ol>
 <h2 id="失败路径"><a class="heading-anchor" href="#失败路径">#</a>失败路径</h2>