# 爵士 UI 开发 ## 何时使用此技能 * 构建显示 Jazz 数据或与 Jazz 数据交互的用户界面 * 设置身份验证提供者和上下文 * 调试 UI 中的反应性、数据加载或同步问题 * 优化数据订阅性能 * 在用户界面中处理媒体（图像、文件） ## 不要将此技能用于 * 定义数据模式（使用“jazz-schema-design”） * 复杂的权限逻辑或共享工作流程（使用“jazz-permissions-security”） * 测试问题（使用“jazz-testing”） ## 代理的关键启发当用户询问渲染数据、处理用户输入、管理身份验证状态或特定于框架的集成（React、Svelte 等）时，请使用此技能。如果问题是“数据未显示”但权限正确，请在此处查找加载和订阅模式。 ## 框架指南选择适合您的特定框架的指南： * **React** : [React 参考]() * **React Native (Bare)** ：以及 React 指南，另请参阅 [React Native 参考]() * **React Native (Expo)** ：以及 React 指南，另请参阅[React Native (Expo) 参考]() * **Svelte** ：[Svelte 参考]() * **Vanilla JS** ：[Vanilla JS 参考]() ## 通用 CoValue API 这些 API 可在所有 CoValue 实例上使用，无论框架如何。 ### 核心属性所有 CoValue（CoMap、CoList 等）都直接在实例上具有以下属性： * `$isLoaded` (`boolean`)：如果 CoValue 已完全加载并准备好读取，则返回 `true`。 * `.toJSON()`：返回 CoValue 的纯 JavaScript 对象表示形式。 **仅将此用于调试**，而不用于渲染。 ### `.$jazz` 命名空间每个 CoValue 实例都有一个包含元数据和实用方法的“.$jazz”属性。 #### 元数据 * `.$jazz.id` (`ID`)：CoValue 的全局唯一 ID（例如，`co_zXy...`）。 * `.$jazz.owner` (`Group`)：拥有此 CoValue 的组。访问控制由该组中的成员身份决定。 * `.$jazz.createdAt` (`number`)：创建时间戳（自纪元以来的毫秒数）。 * `.$jazz.createdBy` (`ID | undefined`)：创建帐户的 ID。 * `.$jazz.lastUpdatedAt` (`number`)：上次更新时间戳（自纪元以来的毫秒数）。 #### 装载和检验 * `.$jazz.loadingState` (`"loading" | "loaded" | "unavailable" | "unauthorized"`): 当前加载状态。 * `.$jazz.ensureLoaded({resolve: { ... } })`：等待加载嵌套引用。返回带有 **new** 实例的承诺，其中请求的字段保证可用。 constDetailedPost=awaitpost.$jazz.ensureLoaded({ 解决：{ 评论：{ 每个$：{ 作者：真实 } } } }); * `.$jazz.refs`（仅限 CoMap/CoRecord）：将嵌套 CoValue 作为引用（带有 ID）访问，而不加载它们。 * `.$jazz.has(key)` （仅限 CoMap/CoRecord）：检查键是否存在。 #### 订阅和同步 * `.$jazz.subscribe(callback)`：手动订阅更改。返回取消订阅函数。 **优先选择特定于框架的钩子（例如`useCoState`）。** * `.$jazz.waitForSync()`：承诺在更改同步到对等点时解析。对于关键保存或注销流程很有用。 #### 版本控制 * `.$jazz.isBranched` (`boolean`)：CoValue 当前是否位于本地分支中。 * `.$jazz.branchName` (`string`)：当前分支的名称。 * `.$jazz.unstable_merge()`：将分支合并回主历史记录中。 ## 使用数据类型 ### CoMap / CoRecord * **读取** ：像标准 JS 对象一样访问属性（例如，`user.name`）。 * **写**： * `.$jazz.set(key, value)` * `.$jazz.delete(key)` * `.$jazz.applyDiff(diff)` ### CoList * **读取** ：通过索引访问（`list[0]`），迭代（`map`、`forEach`）。 * **写**： * `.$jazz.push(item)` * `.$jazz.unshift(item)` * `.$jazz.splice(...)` * `.$jazz.remove(索引或谓词)` ### CoText（CoPlainText / CoRichText） * **阅读** : `toString()` 或直接在模板中使用。 * **写**： * `insertAfter(索引, 文本)` * `deleteRange({ 从, 到 })` * `.$jazz.applyDiff(newText)` ### 联合供稿 * **Read** ：迭代 `feed.all` （返回每个会话的提要）。 * **写入** : `.$jazz.push(item)` （仅追加）。 // 订阅所有帐户的所有条目 const allEntries = Object.values(feed.perAccount).flatMap(accountFeed => Array.from(accountFeed.all)); // 推送一个新条目 feed.$jazz.push({ 消息: "Hello", 时间戳: Date.now() }); ### 歧视联盟 * **读取** ：检查鉴别器属性（例如`type`）以缩小类型。 * **Write** ：用所需变体的新对象覆盖属性。 const 列表 = co.list(MyUnion); 常量项=列表[0]； if (item.type === "文本") { console.log(item.value); // 项目缩小为 TextVariant } else if (item.type === "image") { console.log(item.image.$jazz.id); // item 缩小为 ImageVariant } ### 文件流 * **读取** ：使用 `toBlob()` 或消耗块。 * **写入** ：使用 createFromBlob(blobOrFile) 或 start(metadata) -> push(chunk) -> end()`。 ### 图像定义 * **读取** ：使用 `` 组件（特定于框架）或 `loadImageBySize`。 * **写入** ：使用 `jazz-tools/media` 中的 `createImage` 函数 <图像 imageId={productImage.$jazz.id} 宽度={300} /> ## 故障排除 ###“数据未出现”或“值未定义” 1. **检查`$isLoaded`**：确保在渲染之前检查`if (coValue.$isLoaded)`。 2. **深度加载**：如果嵌套数据丢失，请在钩子中使用`resolve`（例如`useCoState(..., {resolve: { items: true } })`）。 3. **Provider Check** ：确保组件包装在适当的 `` 中。 ###“无限重新渲染循环” 1. **选择器稳定性** ：确保 `useCoState` 中的 `select` 函数稳定或返回稳定的引用。 2. **昂贵的选择器**：将计算移至“useMemo”，而不是在“select”函数内进行。 3. **Equality Function** ：如果所选数据在语义上没有改变，则使用 `equalityFn` 来防止不必要的更新。 ###“反应未触发” 1. **直接突变** ：确保您使用 `.$jazz.set()` 或 `.$jazz.push()` 而不是直接属性分配（例如 `obj.key = val` 将不会同步）。 2. **深度更新**：请记住，更新嵌套标量不会触发父 CoValue 中的更改，除非替换父属性。

爵士UI开发

包含技能