用户

The Users 插件和相关插件可以帮助您管理用户数据和权限。当许多用户在同一文档上协作时，这一点至关重要。

# 其他功能信息

如果您加载任何协作功能插件，则会自动提供用户插件。

您必须在加载协作功能之前设置用户数据。为此，请创建一个插件，该插件需要您使用的所有协作功能并定义用户。

// An example of a plugin that provides user data for an editor
// that uses the `Comments` and `RevisionHistory` plugins.
class UsersIntegration extends Plugin {
    static get requires() {
        return [ 'Comments', 'RevisionHistory' ];
    }

    init() {
        const users = this.editor.plugins.get( 'Users' );

        // Provide user data from your database.
        users.addUser( {
            id: 'u1',
            name: 'Zee Croce'
        } );

        users.addUser( {
            id: 'u2',
            name: 'Mex Haddox'
        } );

        // Define the local user.
        users.defineMe( 'u1' );
    }
}

// More code.
// ...

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        extraPlugins: [ UsersIntegration ],
        // More editor's configuration.
        // ...
    } );

对于实时协作应用程序，用户将由实时协作插件和云服务服务器自动设置和管理，因此您不应使用权限 API。

实时协作编辑插件将根据您的令牌数据自动定义用户数据和权限。

# 本地用户（“我”用户）

本地用户（也称为“我”用户）被视为使用编辑器实例的用户。功能（如评论或修订历史）将将更改归因于该用户。

您可以通过 Users 插件访问“我”用户

    const usersPlugin = editor.plugins.get( 'Users' );

    // We get either `User` or `undefined` if the local user is not set.
    const localUser = usersPlugin.me;

您也可以使用 User 项目上的 isMe 标志来检查它是否是本地用户

    const id = 'e1d1a156789abc92e4b9affff124455bb';
    const user = editor.plugins.get( 'Users' ).getUser( id );

    // It is `true` if it is the "me" user, `false` otherwise.
    const isOwnUser = user.isMe;

本地用户的头像在所有显示的地方都会高亮显示。您可以使用 .ck-user_me CSS 类选择器轻松地覆盖此行为。

    /* Display the local user the same as other users. */
    .ck-user.ck-user_me {
        border: none;
        outline: none;
    }

# 匿名用户

如果您出于某种原因不想或不能提供用户数据，您可以使用匿名用户

const usersPlugin = editor.plugins.get( 'Users' );

usersPlugin.useAnonymousUser();

usersPlugin.me.name; // 'Anonymous'
usersPlugin.me.id; // 'anonymous-user'

匿名用户的头像是一个人脸的轮廓。

您可以使用 config.users.anonymousUserId 属性设置匿名用户的 ID

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // More editor's configuration.
        // ...
        users: {
            anonymousUserId: '0'
        }
    } );

# 用户权限

在许多应用程序中，文档创建工作流程包括几个精确定义的步骤，例如内容创建、讨论、校对、最终审核和接受等。此类应用程序的用户可能具有某些角色和权限。

您可以更改给定用户的权限，从而启用或禁用某些编辑器功能。

对于实时协作应用程序，请参阅云服务文档中的角色和权限指南。

您可以使用 Permissions 插件设置权限。如果您加载任何协作功能插件，它将自动提供。

在定义用户后立即设置权限是一种良好的做法

class UsersIntegration extends Plugin {
    // More methods.
    // ...

    init() {
        const users = this.editor.plugins.get( 'Users' );

        // Provide user data from your database.
        users.addUser( {
            id: 'u1',
            name: 'Zee Croce'
        } );

        users.addUser( {
            id: 'u2',
            name: 'Mex Haddox'
        } );

        // Define the local user.
        users.defineMe( 'u1' );

        // Set permissions.
        const permissions = this.editor.plugins.get( 'Permissions' );

        // "Commentator" role.
        permissions.setPermissions( [
            'comment:write'
        ] );
    }
}

在 Permissions 插件描述中提供了所有定义的权限列表。

您应该在前端和后端保护您的应用程序。即使用户无法通过编辑器执行某些操作，您仍然应该注意保护后端代码中的传入数据。

# 操作作者

The Users#getOperationAuthor() 方法使您能够检查哪个用户创建了给定的操作。这在使用实时协作在集成中创建自定义功能时非常有用。

操作作者可能为 null 有两种情况

对于初始操作（在连接时从服务器获取）。
对于某些没有意义的自动创建的操作（NoOperation）。

以下是如何使用 getOperationAuthor() 找出最后一个编辑文档的用户。在这种情况下，您应该跳过 NoOperation 和一些 MarkerOperation，因为它们不会影响文档内容。

let lastUser = null;

editor.model.on( 'applyOperation', ( evt, args ) => {
    const users = editor.plugins.get( 'Users' );
    const operation = args[ 0 ];

    if ( operation.isDocumentOperation && affectsData( operation ) ) {
        const user = users.getOperationAuthor( operation );

        if ( user && user != lastUser ) {
            lastUser = user;

            console.log( lastUser.name, lastUser, operation );
        }
    }

    function affectsData( operation ) {
        return operation.type != 'noop' && ( operation.type != 'marker' || operation.affectsData );
    }
} );

# 主题定制

# 用户头像

您可以通过修改以下 CSS 变量来定义用户头像的外观

:root {
    --ck-user-avatar-size: 40px;
    --ck-user-avatar-background: hsl(210, 52%, 44%);
    --ck-user-name-color: hsl(0, 0%, 100%);

    /* Border color used to highlight the local user. */
    --ck-user-me-border-color: hsl(0, 0%, 100%);
}

# 用户颜色

您还可以定义用于表示其他用户选择的颜色。

默认情况下，为用户定义了 8 种颜色。与整个 CKEditor 5 生态系统一样，PostCSS 用于使用 CSS 变量的强大功能来处理样式。使用 CSS 变量的继承，您可以更改默认颜色。

带有 alpha 通道的颜色（--ck-user-colors--$(number)-alpha）专用于选择（.ck .ck-user__selection--$(number)）。其余类使用定义为 --ck-user-colors--$(number) 的颜色。您可以随意更改此调色板以适合您的 UI。

/* The current color set for users in the collaboration plugins. */
:root {
    --ck-user-colors--0: hsla(235, 73%, 67%, 1);
    --ck-user-colors--0-alpha: hsla(235, 73%, 67%, 0.15);

    --ck-user-colors--1: hsla(173, 100%, 24%, 1);
    --ck-user-colors--1-alpha: hsla(173, 100%, 24%, 0.15);

    --ck-user-colors--2: hsla(0, 46%, 50%, 1);
    --ck-user-colors--2-alpha: hsla(0, 46%, 50%, 0.15);

    --ck-user-colors--3: hsla(256, 54%, 45%, 1);
    --ck-user-colors--3-alpha: hsla(256, 54%, 45%, 0.15);

    --ck-user-colors--4: hsla(95, 50%, 36%, 1);
    --ck-user-colors--4-alpha: hsla(95, 50%, 36%, 0.15);

    --ck-user-colors--5: hsla(336, 78%, 43%, 1);
    --ck-user-colors--5-alpha: hsla(336, 78%, 43%, 0.15);

    --ck-user-colors--6: hsla(0, 80%, 59%, 1);
    --ck-user-colors--6-alpha: hsla(0, 80%, 59%, 0.15);

    --ck-user-colors--7: hsla(184, 90%, 43%, 1);
    --ck-user-colors--7-alpha: hsla(184, 90%, 43%, 0.15);
}

这些颜色在用户存在列表中（除其他用途外）用于表示用户。

# 添加更多用户颜色

如果您发现默认集太小，可以为用户定义其他颜色。

首先，准备一个包含一些颜色定义的 CSS 文件。

// mycolors.css

/* Import the "userColor" mixin to create definitions easily. */
@import "@ckeditor/ckeditor5-collaboration-core/theme/usercolormixin.css";

/**
 * Add some new definitions. The parameters for the "userColor" mixin are:
 *
 * - Color without an alpha channel (main color).
 * - Color with an alpha channel (selection marker color).
 * - Color ordering number.
 */
@mixin userColor hsla(31, 90%, 43%, 1), hsla(31, 90%, 43%, 0.15), 8;
@mixin userColor hsla(61, 90%, 43%, 1), hsla(61, 90%, 43%, 0.15), 9;

然后，导入此 CSS 文件并指定 colorsCount 配置选项。

import './mycolors.css';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // More editor's configuration.
        // ...
        users: {
            colorsCount: 10
        }
    } );

我们每天都在努力使我们的文档保持完整。您是否发现了过时的信息？是否缺少内容？请通过我们的问题追踪器报告。

随着版本 42.0.0 的发布，我们重写了大部分文档以反映新的导入路径和功能。我们感谢您的反馈，帮助我们确保文档的准确性和完整性。