rich markdown editor

豐富的 Markdown 編輯器

基於 React 和 Prosemirror 的編輯器，為 Outline 提供支持，也可用於以唯讀方式顯示內容。該編輯器是所見即所得的，包括格式化工具，同時保留內聯編寫 Markdown 快捷方式和輸出純 Markdown 的能力。請參閱現場演示故事書。

重要提示：該專案並不試圖成為一個通用的 Markdown 編輯器。它是為 Outline 知識庫構建的，雖然歡迎其他人在您自己的產品中分叉或使用此包，但開發決策以 Outline 的需求為中心。

用法

安裝

yarn add rich-markdown-editor

或者

npm install rich-markdown-editor

請注意， react 、 react-dom和styled-components是必要的對等依賴項。

進口

 import Editor from "rich-markdown-editor" ;

< Editor
  defaultValue = "Hello world!"
/>

克隆此儲存庫並使用yarn start運行 Storybook 以查看各種範例用法。

道具

id

此編輯器的唯一 ID，用於將設定保留在本機儲存中。如果沒有傳遞id ，則編輯器將預設使用位置路徑名稱。

defaultValue

表示編輯器初始值的 Markdown 字串。使用此屬性可以恢復先前儲存的內容，以便使用者繼續編輯。

value

表示編輯器值的 Markdown 字串。使用此屬性可以變更安裝後的編輯器的值，這將重新渲染整個編輯器，因此僅適用於readOnly模式。不要將onChange的值通過管道傳回value ，編輯器會保留自己的內部狀態，這將導致意外的副作用。

placeholder

允許覆蓋佔位符。預設是“寫一些不錯的東西......”。

readOnly

將readOnly設定為false時，編輯器會針對組合進行最佳化。當true時，編輯器可用於顯示先前編寫的內容 - 標題獲得錨點並且連結變得可點擊。

readOnlyWriteCheckboxes

將readOnlyWriteCheckboxes設為true時，作為特殊情況，仍然可以選取或取消選取複選框，而readOnly設為true時，編輯器將無法進行編輯。

autoFocus

當設定true和readOnly設定為false時，自動對焦​​在文件末尾。

maxLength

設定時會在文件上強制執行最大字元長度，不包括 Markdown 語法。

extensions

允許將其他 Prosemirror 插件傳遞到底層 Prosemirror 實例。

disableExtensions

要停用的包含的擴充名稱清單。刪除相應的選單項目和指令。例如，設定為["em", "blockquote"]以停用斜體文字和區塊引用。

theme

允許覆蓋內建主題來品牌化編輯器，例如使用您自己的字體和品牌顏色使編輯器適合您的應用程式。有關應提供的按鍵的範例，請參閱內建主題。

dictionary

允許覆蓋內建的複製字典，例如國際化編輯器。有關應提供的按鍵的範例，請參閱內建字典。

dark

將dark設為true編輯器將使用包含的預設深色主題。請參閱此處的來源。

dir

預設值： auto

控製文檔的方向。可能的值為：

• ltr ：編輯器佈局針對 LTR 文件進行了最佳化，內容明確標記為 LTR。
• rtl ：編輯器佈局針對 RTL 文件進行了最佳化，內容明確標記為 RTL。
• auto ：編輯器佈局由瀏覽器依文件內容決定。

tooltip

一個 React 元件，將包裹在具有可選工具提示的項目周圍。您可以使用它將自己的工具提示庫注入編輯器 - 該元件將傳遞以下屬性：

• tooltip ：帶有工具提示內容的 React 節點
• placement ：枚舉top 、 bottom 、 left 、 right
• children ：工具提示包裝的元件，必須渲染

headingsOffset

將文件標題偏移多個層級的數字。例如，如果您已經將編輯器嵌套在主h1標題下，您可能希望使用者只能建立h2標題及以下標題，在這種情況下，您可以將 prop 設為1 。

scrollTo

表示標題錨點的字串 - 文件將平滑捲動，以便標題在視窗中可見。

embeds

可以選擇定義嵌入，當matcher函數傳回真值時，嵌入將被插入以代替連結。匹配器方法的傳回值將在props.attrs.matches下的組件上可用。如果提供了title和icon ，則嵌入也會出現在區塊選單中。

 < Editor
  embeds = { [
    {
      title : "Google Doc" ,
      keywords : "google docs gdocs" ,
      icon : < GoogleDocIcon /> ,
      defaultHidden : false ,
      matcher : href => href . matches ( / docs.google.com / i ) ,
      component : GoogleDocEmbed
    }
  ] }
/>

回調

uploadImage(file: Blob): Promise<string>

如果您希望編輯器支援圖像，則必須提供此回調。當影像上傳到儲存位置（例如 S3）時，回呼應該接受單一File物件並傳回解析為 url 的承諾。例如：

 < Editor
  uploadImage = { async file => {
    const result = await s3 . upload ( file ) ;
    return result . url ;
  } }
/> 

onBlur(): void

當使用者失去對編輯器 contenteditable 和所有關聯的 UI 元素（例如區塊選單和浮動工具列）的焦點時，會觸發此回呼。如果您只想偵聽可內容編輯區域上的模糊事件，請使用handleDOMEvents屬性。

onFocus(): void

當使用者獲得焦點在編輯器 contenteditable 或任何關聯的 UI 元素（例如區塊選單或浮動工具列）上時，會觸發此回呼。如果您只想偵聽可內容編輯區域上的焦點事件，請使用handleDOMEvents屬性。

onSave({ done: boolean }): void

當使用者使用鍵盤快速鍵Cmd+S或Cmd+Enter明確請求儲存時，會觸發此回呼。您可以使用它作為將文件保存到遠端伺服器的信號。

onCancel(): void

當在編輯器中按下Cmd+Escape時會觸發此回呼。您可以使用它來取消編輯。

onChange(() => value): void

當編輯器的內容發生變更時（通常是由於使用者輸入（例如按鍵或使用格式設定選項）而發生變更），會觸發此回調。您可以使用它在本地保留編輯器狀態。

它會傳回一個函數，該函數在呼叫時會傳回文件的當前文字值。進行此最佳化是為了避免在每次變更事件時將文件狀態序列化為文本，從而允許主機應用程式選擇何時需要序列化值。

onImageUploadStart(): void

此回呼在uploadImage之前觸發，可用來顯示一些指示上傳正在進行的 UI。

onImageUploadStop(): void

圖片上傳成功或失敗時觸發。

onSearchLink(term: string): Promise<{ title: string, subtitle?: string, url: string }[]>

此編輯器提供了搜尋連結以從格式工具列插入的功能。如果提供此回調，它應該接受搜尋字詞作為唯一參數，並傳回解析為物件陣列的承諾。例如：

 < Editor
  onSearchLink = { async searchTerm => {
    const results = await MyAPI . search ( searchTerm ) ;

    return results . map ( result => {
      title : result . name ,
      subtitle : `Created ${ result . createdAt } ` ,
      url : result . url
    } )
  } }
/> 

onCreateLink(title: string): Promise<string>

此編輯器提供了從格式工具列建立連結的功能，以便即時建立文件。如果提供此回調，它應該接受連結「標題」作為唯一參數，並傳回解析為所建立連結的 url 的承諾，例如：

 < Editor
  onCreateLink = { async title => {
    const url = await MyAPI . create ( {
      title
    } ) ;

    return url ;
  } }
/> 

onShowToast(message: string, type: ToastType): void

當編輯器希望向使用者顯示訊息時觸發。連接到應用程式的通知系統，或簡單地使用window.alert(message) 。第二個參數是 toast 的類型：「error」或「info」。

onClickLink(href: string, event: MouseEvent): void

此回調允許覆蓋連結處理。通常情況下，您希望外部連結打開一個新窗口，並讓內部連結使用像react-router這樣的東西來導航。如果未提供回調，則開啟新分頁的預設行為將套用至所有連結。例如：

 import { history } from "react-router" ;

< Editor
  onClickLink = { ( href , event ) => {
    if ( isInternalLink ( href ) ) {
      history . push ( href ) ;
    } else {
      window . location . href = href ;
    }
  } }
/> 

onHoverLink(event: MouseEvent): boolean

此回調允許檢測使用者何時將滑鼠懸停在文件中的連結上。

 < Editor
  onHoverLink = { event => {
    console . log ( `Hovered link ${ event . target . href } ` ) ;
  } }
/> 

onClickHashtag(tag: string, event: MouseEvent): void

此回調允許處理單擊文件文字中的主題標籤。如果未提供回調，則主題標籤將呈現為常規文本，因此您可以透過傳遞此屬性來選擇是否支援它們。

 import { history } from "react-router" ;

< Editor
  onClickHashtag = { tag => {
    history . push ( `/hashtags/ ${ tag } ` ) ;
  } }
/> 

handleDOMEvents: {[name: string]: (view: EditorView, event: Event) => boolean;}

該物件將事件名稱（ focus 、 paste 、 touchstart等）對應到回呼函數。

 < Editor
  handleDOMEvents = { {
    focus : ( ) => console . log ( "FOCUS" ) ,
    blur : ( ) => console . log ( "BLUR" ) ,
    paste : ( ) => console . log ( "PASTE" ) ,
    touchstart : ( ) => console . log ( "TOUCH START" ) ,
  } }
/>

介面

編輯器元件公開了一些與已安裝的編輯器互動的方法。

focusAtStart(): void

將遊標置於文件的開頭並將其聚焦。

focusAtEnd(): void

將遊標置於文件末尾並聚焦。

getHeadings(): { title: string, level: number, id: string }[]

傳回一個物件數組，其中包含文件中所有標題的文字內容、它們在層次結構中的層級以及錨點 ID。這對於建立您自己的目錄非常有用，因為 v10 中刪除了toc選項。

貢獻

該專案使用yarn來管理依賴關係。您可以使用 npm，但它不會尊重紗線鎖定文件，並且可能安裝略有不同的版本。

 yarn install

在開發中執行時，Storybook 包含在具有熱重載的範例編輯器中。安裝依賴項後，執行yarn start即可開始。

使用yarn link進行開發時，您可以在進行變更時使用yarn watch不斷將變更重建為dist 。

執照

該項目已獲得 BSD 許可。