ember-rdfa-editor虚拟应用镜像

镜像概述和主要用途

本镜像托管ember-rdfa-editor插件的虚拟应用。ember-rdfa-editor是一个Ember.js插件，提供RDFa感知的富文本编辑器，构成say编辑器的核心。该编辑器可通过插件扩展，为特定内容（如日期、模板、引用等）提供提示，这些提示通常会在内容中插入RDFa标注。

核心功能和特性

• 工具栏支持：包含粗体/斜体/列表/缩进等文本样式按钮
• 插件支持：可通过插件扩展功能，提供内容提示
• 插件配置文件：支持定义不同插件配置文件
• 提示注册表：管理编辑器中的内容提示
• RDFa感知：能够识别和处理RDFa标注

使用场景和适用范围

适用于需要RDFa结构化数据标注的富文本编辑场景，如文档创作、内容管理系统、学术写作等，尤其适合需要对文本内容添加语义化标注的应用。

详细使用方法和配置说明

安装

通过Ember命令安装插件：

ember install @lblod/ember-rdfa-editor

在模板中使用编辑器（Ember Octane语法）：

        <Rdfa::RdfaEditor
          @rdfaEditorInit={{this.rdfaEditorInit}}
          @editorOptions={{hash showToggleRdfaAnnotations="true" showInsertButton=null showRdfa="true" showRdfaHighlight="true" showRdfaHover="true"}}
          @toolbarOptions={{hash showTextStyleButtons="true" showListButtons="true" showIndentButtons="true"}}
        />

rdfaEditorInit回调在编辑器元素插入时调用，提供以下接口：

• 属性htmlContent：清理后的HTML内容（尽可能移除内部状态）
• 属性richNode：文档内部表示的副本
• 属性rootNode：编辑器DOM的副本（包含编辑器元素）
• 函数setHtmlContent(html)：设置编辑器的HTML内容

编辑器选项

通过@editorOptions传递基本选项，值为"true"启用，移除选项或传递null禁用：

• showToggleRdfaAnnotations：显示标注切换开关并添加RDFa标注视图
• showInsertButton：显示模板插入按钮
• showRdfa：在编辑器中显示RDFa
• showRdfaHighlight：显示RDFa高亮
• showRdfaHover：悬停时显示RDFa信息

工具栏选项

通过@toolbarOptions设置工具栏按钮：

• showTextStyleButtons：显示文本样式按钮（粗体、斜体、下划线、删除线）
• showListButtons：显示列表样式按钮（有序列表、无序列表）
• showIndentButtons：显示缩进按钮（缩进、反向缩进）

功能标志

编辑器的部分实验性功能通过功能标志隐藏，可在测试时启用，不建议生产环境使用。标志在应用的config/environment.js中设置：

// config/environment.js
module.exports = function(environment) {
  var ENV = {
    featureFlags: {
      'editor-html-paste': true,
    }
  };

  if (environment === 'production') {
    ENV.featureFlags['editor-html-paste'] = false;
  }

  return ENV;
};

各标志说明：

• editor-html-paste：启用时支持HTML粘贴输入
• editor-extended-html-paste：启用时支持扩展HTML粘贴输入（旧行为）
• editor-force-paragraph：启用时将未包裹的文本输入自动包裹在段落中

样式设置

基础样式

• 使用vanilla css时，ember-rdfa-editor会将默认样式添加到vendor css文件中
• 使用ember-cli-sass时，需手动导入样式：

  @import "ember-rdfa-editor";
  

  通过ember install安装时，会自动在app.scss中添加上述导入语句

自定义样式

使用ember-cli-sass时，可通过覆盖变量自定义编辑器主题，相关变量文件：

• _s-colors.scss：颜色集合
• _s-settings.scss：通用设置（间距、字体、大小、媒体查询等）
• _s-theme.scss：特定主题变量

兼容性

• Ember.js v3.12或更高版本
• Ember CLI v2.13或更高版本
• Node.js v10或更高版本

贡献指南

详见Contributing指南。

插件

添加插件到编辑器

通过以下步骤扩展编辑器功能：

1. 在宿主应用中安装rdfa-editor-plugin作为Ember插件
2. 在宿主应用的app/config/editor-profiles.js中，将插件名称添加到一个或多个编辑器配置文件中

插件会被编辑器自动识别。示例app/config/editor-profiles.js：

export default {
  default: [
    "rdfa-editor-standard-template-plugin",
    "rdfa-editor-date-plugin"
  ],
  all: [
    "rdfa-editor-console-logger-plugin",
    "rdfa-editor-standard-template-plugin",
    "rdfa-editor-date-plugin"
  ],
  none: []
};

开发插件

插件是提供服务的Ember插件，该服务实现execute方法以处理编辑器中的变更，并提供组件显示提示。

服务接口

Ember服务必须提供execute属性（异步函数或Ember Concurrency任务），接受以下参数：

• hrId [string]：提示注册表中事件的唯一标识符
• contexts [Array]：事件应用的文本片段的RDFa上下文
• hintsRegistry [Object]：编辑器的提示注册表
• editor [Object]：RDFa编辑器实例

示例（异步函数）：

export default Service.extend({
  async execute(hrId, contexts, hintsRegistry, editor) {
    // 更新提示注册表中的提示
  }
})

示例（Ember Concurrency任务）：

export default Service.extend({
  execute: task(function * (hrId, contexts, hintsRegistry, editor) {
    // 更新提示注册表中的提示
  })
})

更新提示注册表

execute方法需更新插件在提示注册表中的提示，常用方法：

• addHints(hrId, who, cards)：添加提示
  • hrId：事件唯一标识符
  • who：提示类型标识符（如editor-plugins/date-card）
  • cards：提示对象数组
• removeHintsInRegion(region, hrId, who)：移除指定区域的提示
  • region：[start, end] 区域范围
  • hrId：事件唯一标识符
  • who：提示类型标识符

提示卡片

提示以卡片形式显示，仅适用于文本的特定部分。添加到提示注册表的提示必须是EmberObject，包含以下属性：

• card [string]：显示提示的组件名称
• location [int, int]：提示应用的文本起始和结束索引
• info [Object]：传递给卡片组件的自定义对象
• options.noHighlight [boolean]：设为false时移除提示高亮（用于被动提示）

提示注册表会在提示应用的文本被选中时，使用指定组件渲染提示。