tldraw 工作区Workspaces完整指南文件、成员、权限与团队协作管理【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw导读tldraw 在线版dotcom通过「工作区」把文件组织与多人协作统一起来——每个工作区都有自己的文件列表、成员与设置。本文基于 用户手册 系统讲解工作区的创建、切换、成员管理、文件管理与权限模型并结合本仓库的源码packages/dotcom-shared、apps/dotcom/client说明这些界面操作背后的数据模型与权限落点帮助你理解「工作区成员」与「文件分享」两套系统的边界避免协作中的权限误解。一、工作区的基本概念每个工作区Workspace都拥有独立的文件列表、成员members与设置settings用于帮你组织文件并和他人协作。每个账号都自带一个私有 Home 工作区通常叫My workspace可以重命名也可显示为你自定义的名字。它是你存放个人文件的默认空间。除了 Home 工作区你还可以创建**团队工作区team workspace**用于共享协作。无论 Home 还是团队工作区其本质都是一条group数据记录Home 工作区的group.id与用户 id 相同且创建该用户时系统会为其写入一条 owner 角色的group_user记录——这一点在工程评审文档 workspaces-feature.md 与数据库 schema tlaSchema.ts 中均有体现。必须记住的关键规则你的 Home 工作区是私有的。你可以重命名它但不能邀请他人加入、退出、删除它也无法管理它的成员。团队工作区中可以有owners所有者和members成员两种角色。任何工作区成员都能打开并编辑该工作区内的文件。任何工作区成员都能创建文件、移动文件、删除**该工作区拥有workspace-owned**的文件以及复制或重置工作区邀请链接。Owners 可以重命名工作区、管理成员、变更角色以及删除工作区。一个工作区必须始终至少有一位 owner。最后一位 owner 不能退出、不能被移除也不能被降级为 member。文件分享与工作区成员资格是两套独立系统把某人移出工作区并不会自动让已分享的文件链接失效。工程视角上述「谁能做什么」在源码中并没有散落各处而是集中在 roles.ts 的单一角色表里见下文“权限模型深度解析”一节成员与所有者能力的差异由manageWorkspace一个能力统一区分。二、创建、切换与重命名工作区创建团队工作区创建你的第一个团队工作区点击侧边栏的New workspace。如果你已经有工作区请点击侧边栏顶部的工作区切换器workspace switcher再点击New workspace。输入一个工作区名称。点击Create workspace。tldraw 会创建该工作区、把你设为 owner、在工作区中生成一个欢迎文件welcome file并自动打开这个文件。创建 FAQ谁能创建工作区任何登录后能看到工作区控件的用户都可以。谁能看到新创建的工作区一开始只有你自己能看到。其他人需要通过工作区邀请链接加入。我获得什么角色你是该工作区的 owner。源码佐证创建工作区对应createWorkspacemutator它会写入一条group含随机的inviteSecret和一条group_user记录创建者角色固定为owner并用 tldraw 的分数索引fractional indexing把新工作区排到工作区列表顶部见 mutators.ts。欢迎文件由客户端后续播种保证用户始终落在可编辑的画布上。切换工作区点击侧边栏顶部的工作区切换器。选择要打开的工作区。tldraw 会打开该工作区的置顶文件top file——置顶pinned文件排在最前。如果该工作区还没有任何文件tldraw 会自动创建一个空白文件并打开它。切换 FAQ为什么活动工作区变了活动工作区是由你当前打开的文件决定的如果你打开了另一个工作区的文件该工作区就会变成活动工作区。从源码看活动工作区并不是单独存储的状态而是由当前文件 URL 推导而来见useActiveWorkspaceId相关实现与 workspaces-feature.md。为什么我最后回到了 My workspace如果你正在查看的文件无法通过你拥有的任一工作区成员关系看到侧边栏会回退显示你的 Home 工作区此时你仍可能通过分享链接以访客身份查看该文件。重命名工作区切换到该工作区。点击侧边栏的Workspace settings。编辑Name字段。编辑完成后新名称会自动保存。重命名 FAQ谁能重命名团队工作区只有 owners。我能重命名 My workspace 吗可以Home 工作区允许重命名。新名称会同步给其他成员吗会。当 owner 重命名团队工作区后所有成员都会看到新名称。源码佐证重命名对应updateWorkspacemutator。注释特意指出Home 工作区可以被重命名与其它 Home 专属限制不同因此该 mutator没有用assertNotHomeWorkspace拦截但会断言操作者具备manageWorkspace能力否则抛出forbidden并截断超长名称见 mutators.ts。工作区名称变更后其拥有文件上的 owner 展示字段也会由数据库触发器同步更新。三、邀请成员与重置邀请链接邀请他人加入团队工作区切换到该团队工作区。点击侧边栏的Workspace settings。点击Copy invite link。把邀请链接发送给你想邀请的人。对方打开链接后可能先需要登录接受邀请后即以member身份加入工作区。邀请 FAQ谁能邀请他人任何工作区成员都可以复制邀请链接。我能邀请别人加入 My workspace 吗不能Home 工作区是私有的。请先创建一个团队工作区再邀请他人。被邀请者会获得什么角色一律以 member 身份加入而不是 owner。如果对方已经是成员会怎样tldraw 会提示对方已是成员并直接打开该工作区。重置工作区邀请链接切换到该工作区。点击Workspace settings。在Invite members区域点击Regenerate invite link。复制新的邀请链接并分发给想邀请的人。重置 FAQ谁能重置邀请链接按 用户手册 的产品说明任何工作区成员都可以重置邀请链接该描述对应的权限判定由角色表统一维护具体线上行为请以你所用版本的roles定义为准见下文权限一节。旧链接还有效吗无效。重置会使旧链接作废打开旧链接的人会看到“邀请已过期”。重置链接会移除现有成员吗不会现有成员仍留在工作区中。源码佐证邀请链接由group.inviteSecret与group.inviteLinkEnabled两个字段共同控制见 tlaSchema.ts。regenerateWorkspaceInviteSecret会用uniqueId()生成新的inviteSecret——这正是“旧链接作废”的机制setWorkspaceInviteLinkEnabled则只翻转开关而保留 secret因此重新启用可恢复原链接。在 WorkspaceSettingsDialog.tsx 中重置前会弹出危险操作确认框明确提示旧链接将失效。接受邀请的完整流程未登录先登录 → 校验邀请 → 显示过期或“已是成员” → 加入并等待同步在 workspaces-feature.md 中有详细描述。四、查看成员、变更角色、移除与退出查看工作区成员切换到该工作区。点击Workspace settings。在Members区域查看。成员列表会显示每个成员的姓名与角色。查看成员 FAQ谁能查看成员列表任何工作区成员都可以。为什么 My workspace 里看不到成员Home 工作区是私有的没有可管理的成员列表。从源码看成员列表来自与工作区同步的groupMembers列表中 owners 排在 members 之前、当前用户固定在顶部头像颜色取自group_user.userColor见 WorkspaceSettingsDialog.tsx。变更成员角色切换到该工作区。点击Workspace settings。在Members中找到目标成员。使用其角色菜单选择Owner或Member。变更角色 FAQ谁能变更角色只有 owners。Owners 能做什么Owners 能做成员能做的一切另外还能重命名工作区、变更成员角色、移除成员、删除工作区。Members 能做什么Members 能访问工作区文件、创建文件、移动文件、移除文件以及管理邀请链接。我能把最后一位 owner 改成 member 吗不能。工作区必须始终至少保留一位 owner。源码佐证setWorkspaceMemberRolemutator 首先断言操作者具备manageWorkspace能力随后执行“最后 owner 保护”这一显式不变量检查——如果被降级者当前是 owner则统计该工作区 owner 数量owners.length 1才允许操作否则返回forbidden见 mutators.ts。前端也会对最后一位 owner 禁用“降级为 member”的选项见 WorkspaceSettingsDialog.tsx。对应逻辑在 mutators.test.ts 中有成对的单测覆盖。移除成员切换到该工作区。点击Workspace settings。在Members中打开该成员的角色菜单。点击Remove。在弹出的确认框中点击Remove member。移除 FAQ谁能移除成员只有 owners。我能移除最后一位 owner 吗不能工作区必须始终至少保留一位 ownerremoveWorkspaceMember与setWorkspaceMemberRole中的 owner 计数检查相同见 mutators.ts。被移除的成员会怎样应用更新后该工作区会从其侧边栏消失。如果被移除者正打开着该工作区私有文件则会失去访问权限正在连接的私有文件会话会被以 forbidden 关闭。被移除后还能打开已分享文件吗可以如果该文件仍通过链接分享。工作区成员资格与分享链接访问是分开的要彻底移除链接访问需要把文件设为私有或更改其访客权限。退出工作区切换到该工作区。点击Workspace settings。在Danger zone区域点击Leave workspace...。确认点击Leave workspace。退出后tldraw 会把你带回首页。退出 FAQ任何人都能退出吗Members 可以退出Owners 只有在仍存在另一位 owner 的情况下才能退出。leaveWorkspacemutator 会先统计 owner若你既是唯一 owner 又请求退出则返回forbidden见 mutators.ts。前端WorkspaceSettingsDialog中canLeave role ! owner || ownersCount 1与此对应。我能退出 My workspace 吗不能你无法退出自己的 Home 工作区。退出后文件会怎样你会失去工作区成员身份的访问权限但已通过文件链接分享的文件可能仍然可访问。五、删除工作区切换到该工作区。点击Workspace settings。在Danger zone区域点击Delete workspace...。确认点击Delete workspace。删除工作区无法撤销。删除 FAQ谁能删除工作区只有 owners 可以删除团队工作区。我能删除 My workspace 吗不能你无法删除自己的 Home 工作区。该工作区拥有的文件会怎样会被对所有人删除。只是链接linked进该工作区的文件会怎样工作区中的链接会被移除但原始文件不会被删除。源码佐证deleteWorkspacemutator 依次删除该工作区所有group_file行 → 将该工作区拥有的所有file标记为isDeleted: true→ 将group标记为已删除 → 清理成员关系对应打开这些文件的会话会以 not found 被关闭见 mutators.ts。六、工作区内的文件操作在工作区创建文件切换到目标工作区。点击侧边栏的New file。tldraw 会在活动工作区中创建文件并打开它在桌面端会自动开始重命名。创建文件 FAQ新文件会创建在哪里侧边栏的New file动作会把文件创建在活动工作区。团队工作区中谁能创建文件任何成员都可以。其他成员能看到新文件吗可以。其他成员会通过同步Zero sync收到新文件。新文件默认是分享的吗是。新的工作区文件默认通过链接分享非成员的分享链接访客也能打开。从 workspaces-feature.md 的工程描述看新建文件时后端会写入owningGroupId 目标工作区、对应的group_file行、创建者的file_state行并把shared true、sharedLinkType edit。在工作区搜索文件切换到要搜索的工作区。点击侧边栏的Search。输入文件名或关键词。搜索只在活动工作区的文件列表中进行。搜索 FAQ能一次性跨所有工作区搜索吗不能。搜索只过滤活动工作区的文件列表group_file关联图只包含你所在的工作区见 workspaces-feature.md。为什么找不到另一个工作区的文件先切换到那个工作区再重新搜索。把文件移动到另一个工作区打开文件的文件菜单。选择Move to。选择目标工作区。文件会从旧工作区列表中消失并出现在新工作区列表中。你也可以在Move to菜单中选择New workspace先新建工作区再直接把文件移过去。移动 FAQ谁能移动文件当你同时是源工作区和目标工作区的成员时就可以在两者间移动文件。能把文件移到 My workspace 吗可以在Move to菜单里选择你的 Home 工作区即可。移动会改变分享链接吗不会。移动不会改变文件是已分享、私有、允许访客编辑还是仅访客只读等任何分享状态。如果文件被移到我并不属于的工作区会怎样它可能从你的工作区列表消失。若文件仍通过链接分享你可能还能以访客身份打开。源码佐证moveFileToWorkspacemutator 要求用户在源工作区具备removeFiles、在目标工作区具备addFiles能力members 两者都有所以任意同时隶属两个工作区的成员都能移动随后删除旧的拥有group_file行、更新file.owningGroupId、为目标工作区插入新的group_file行。整个过程不触碰shared与sharedLinkType见 mutators.ts。置顶 / 取消置顶文件打开侧边栏中的文件菜单。点击Pin file置顶。置顶文件会出现在活动工作区文件列表的顶部。取消置顶再次打开文件菜单点击Unpin file。置顶 FAQ置顶是全局的吗不是。置顶属于该文件所在的那个工作区列表。谁能置顶文件该工作区的任何成员都可以置顶/取消置顶。其他成员能看到置顶吗能置顶是工作区文件列表的一部分。源码佐证迁移后的置顶状态存储在group_file.index排序字段上而非file_state.isPinned未置顶文件保持稳定的本地排序以避免文件更新时实时跳动见 tlaSchema.ts 与 workspaces-feature.md。从工作区删除或移除文件打开侧边栏中的文件菜单。点击Delete或Forget。确认该操作。文件被删除或移除后tldraw 会打开该工作区的另一个文件如果已经没有文件则自动创建一个空白文件。删除与移除 FAQDelete 和 Forget 有什么区别如果该工作区拥有这个文件操作会对所有人删除文件如果工作区只是链接了该文件操作只是移除该工作区里的链接原始文件不受影响对应前端removeFileFromWorkspace调用。谁能删除工作区拥有的文件拥有该文件的工作区中的任何成员都可以。正在打开被删除文件的人会怎样文件被删除后已连接的会话会因文件不再存在而关闭以 not found 关闭。源码佐证删除/移除流程由removeFileFromWorkspace逻辑驱动其语义取决于该文件是否是当前工作区拥有的文件见 workspaces-feature.md 的 “Removing and deleting files” 一节与 mutators.ts。本地删除/移除后客户端会导航到该工作区剩余的最新文件没有则新建空白文件。打开来自其它工作区的分享文件打开分享文件链接。如果有权限tldraw 会直接打开文件。如果该文件尚不属于你的任何一个工作区打开后它可能会出现在你的Home 工作区中方便你之后再次找到它。分享文件 FAQ打开分享文件会让我成为工作区成员吗不会。打开分享文件只是通过链接获得文件访问权不会把你加入该文件的工作区。为什么我能编辑一个不属于我工作区的文件因为该文件开启了**访客可编辑visitor editing**的分享设置。为什么分享文件会出现在 My workspace当你打开一个不在自己任何工作区中的分享文件时tldraw 会在 Home 工作区添加一条指向它的链接工程上称为 home guest link让你能够找回它。从源码结构看后端在用户打开文件时会 upsertfile_state对已迁移用户如果该文件不在其任何工作区中服务端还会向 Home 工作区插入一条group_file链接这正是“分享文件出现在 My workspace”的机制见 workspaces-feature.md。导入.tldr文件导入.tldr文件有几种方式把.tldr文件拖到画布上 → 导入到当前文件的拥有工作区。把.tldr文件拖到侧边栏→ 导入到你的Home 工作区。从主菜单导入.tldr文件 → 导入到你的Home 工作区。导入 FAQ为什么导入的文件去了 My workspace侧边栏拖放和主菜单导入默认使用 Home 工作区。想导入到团队工作区请先打开该工作区中的文件再把.tldr文件拖到画布上。这是一个容易踩坑的细节侧边栏“新建文件”按钮会尊重活动工作区但侧边栏导入不会见 workspaces-feature.md 对导入路径不一致的风险提示。七、工作区角色速查表按 用户手册 的角色说明角色可以做什么Member打开与编辑工作区文件、创建文件、移动文件、移除文件、查看成员、复制邀请链接、重置邀请链接。Owner拥有 Member 的全部能力另加重命名工作区、变更成员角色、移除成员、删除工作区。角色 FAQ给同事什么角色最安全除非对方需要管理工作区本身否则设为Member。Member 能删除文件吗能。Members 可以删除该工作区拥有的文件。Member 能重置邀请链接吗能。按文档说明任何成员都可以重置工作区邀请链接。权限模型深度解析从代码看 owner / member 的区别在 capabilities.ts 中所有工作区能力被枚举为四类export const capabilities [ accessFiles, // 打开并编辑工作区文件任何成员 addFiles, // 把文件移入工作区 removeFiles, // 从工作区移除文件 manageWorkspace,// 管理工作区邀请链接、成员角色、名称与删除owners ] as const而 roles.ts 用一张表把角色映射为能力子集作为单一事实来源const roles { member: [accessFiles, addFiles, removeFiles], owner: [accessFiles, addFiles, removeFiles, manageWorkspace], } satisfies Recordstring, readonly Capability[]两个角色唯一的差异就是manageWorkspaceowners 管理整个工作区members 只与文件打交道。授权判断走can(role, capability)函数任意未知或 null 角色一律返回false而不是到处写role owner这类硬编码。这也意味着如果将来想让 member 也能做某些 owner 操作只需修改这一张表。与该主题配套的工程评审文档 workspaces-feature.md 给出了更完整的数据模型与权限后果说明。数据库中存储的只是角色字符串group_user.role枚举见 tlaSchema.ts能力从不持久化而是运行时由这张表推导。对应的角色单测见 roles.test.ts。八、工作区成员资格 vs 文件分享两套独立的系统这是整个工作区模型里最重要的一对概念工作区成员资格控制谁能看到工作区、其成员列表及其文件列表也就是侧边栏。文件分享控制谁能通过链接打开某个文件。二者相互独立一个人可能失去工作区成员资格却仍能以访客身份打开已分享文件一个人也可能是工作区成员即使在文件对访客设为只读时仍保有编辑权成员的编辑权来自成员资格而非访客权限。从数据模型看file上同时存在shared是否分享与sharedLinkTypeview/edit字段见 tlaSchema.tsshared false仅邀请制访问invite-onlyshared truesharedLinkType view访客可只读打开shared truesharedLinkType edit访客可编辑实时画布。新建的工作区文件默认是shared edit访客可编辑。把文件从一个工作区移到另一个工作区不会改变shared或sharedLinkType。分享 FAQ工作区邀请和文件分享链接是一回事吗不是。工作区邀请链接是把某人加为工作区成员文件分享链接只是让某人以访客身份打开某一个文件。移动文件会作废旧分享链接吗不会文件移动时保持相同的分享状态。把某人移出工作区会撤销他已持有的文件链接吗不会。要撤销链接访问需要把文件设为私有或更改文件的访客权限。谁能编辑工作区文件工作区成员可以分享链接访客只有在文件访客权限允许编辑时才能编辑。重要提醒工程层分享链接访客即使被允许编辑画布也无法使用工作区的元数据类变更重命名、分享设置、移动、删除等——那些操作仍要求是拥有工作区的成员。此外文件级“管理员”界面useHasFileAdminRights对拥有该文件的工作区内的所有成员都返回 true因此成员看到文件的删除/分享/发布等控件比“成员”这个词暗示的权限更宽详见 workspaces-feature.md。九、多人在线协作成员/文件变化时会发生什么根据 workspaces-feature.md 的多人场景分析以下行为对理解工作区 UI 的动态变化很有帮助另一位成员在你所在的工作区创建文件通过 Zero 增量同步新文件会出现在你的侧边栏列表中但不会把你从当前文件导航走。另一位 owner 重命名非 Home 工作区新名称对所有成员生效正在打开的文件与成员关系不受影响。另一位成员把当前打开的文件移到你也属于的工作区你的画布连接保持你仍有工作区访问权活动工作区可能变为目标工作区侧边栏中的文件也随之移到目标工作区下。另一位成员把当前打开的文件移到你不属于的工作区该文件不再经由源工作区出现在你的侧边栏活动工作区会回退到 Home画布是否继续可编辑取决于分享状态——仍是 shared edit 则以访客身份保持编辑新建文件默认如此shared view 则转为只读访客私有文件则会被断开连接。这正是“移动文件不等于收回访问权”这一最常见心智落差。owner 把你移出工作区同步后工作区从侧边栏消失该工作区拥有的私有文件会失去访问正连接时以 forbidden 关闭而分享文件仍可能通过链接规则继续访问。owner 删除整个工作区所有成员失去该工作区其拥有的文件被标记删除相关会话以 not found 关闭。owner 修改你的角色升为 owner 后管理设置出现降为 member 后你保留文件访问/编辑/移动/移除与邀请管理能力但失去非 Home 工作区的重命名、成员管理与删除能力。工作区删除/移除当前正在编辑的文件如果文件属于该工作区且被删除你的会话会被关闭如果只是 Home 中的 guest link 被移除文件本身在其拥有工作区和其他分享位置继续存在。这些动态变化之所以能实时反映到侧边栏是因为客户端通过 Zero 同步工作区成员关系与文件关系TldrawApp.preload成员变动、文件移动、删除等都会增量复制到每个成员的客户端workspaces-feature.md。十、易踩坑点与注意事项小结结合用户手册与工程评审文档以下几点值得特别留意把文件移出某工作区并不会自动撤销访问分享状态独立于成员资格保持不变这是当前最容易被误解的行为workspaces-feature.md 的风险区第一条。“成员”在文件层面的权限其实很宽members 可删除其工作区拥有的文件、移动文件、管理邀请链接并且能看到文件级的管理控件。“删除/移除”文案基于文件管理权而非所有权工作区拥有文件时显示 “Delete”对所有人删除Home guest link 时更接近 “Forget”仅移除链接。活动工作区回退可能导致“切换器自己变了”的错觉当打开的文件被移到你不属于的工作区或你失去成员资格时侧边栏会回退到 Home画布却可能继续以访客会话运行。共享文件在成员被移除后仍可能存活要彻底清人还需把相关文件设为私有或调整访客权限。导入路径与新建路径不一致侧边栏“新建文件”跟随活动工作区而侧边栏/主菜单的.tldr导入始终进 Home画布拖放才跟随当前文件的拥有工作区。延伸阅读用户手册原文apps/dotcom/user-manual.md工程评审与数据模型说明角色、同步、多人场景、风险区apps/dotcom/workspaces-feature.md角色→能力映射与can()判断packages/dotcom-shared/src/roles.ts、packages/dotcom-shared/src/capabilities.ts工作区后端 mutator创建/重命名/邀请/成员/移动/删除文件与工作区packages/dotcom-shared/src/mutators.ts工作区相关数据库表结构group、group_user、group_file、filepackages/dotcom-shared/src/tlaSchema.ts前端“管理工作区”对话框 UI 与权限门控apps/dotcom/client/src/tla/components/dialogs/WorkspaceSettingsDialog.tsx权限与 mutator 的行为测试packages/dotcom-shared/src/mutators.test.ts、packages/dotcom-shared/src/roles.test.ts【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考